StructuredQuery

{
  "select": {
    object (Projection)
  },
  "from": [
    {
      object (CollectionSelector)
    }
  ],
  "where": {
    object (Filter)
  },
  "orderBy": [
    {
      object (Order)
    }
  ],
  "startAt": {
    object (Cursor)
  },
  "endAt": {
    object (Cursor)
  },
  "offset": integer,
  "limit": integer,
  "findNearest": {
    object (FindNearest)
  }
}

object (Projection)

可傳回欄位的選用子集合。

就像 DocumentMask 一樣，適用於查詢傳回的文件。如未設定，則假設呼叫端希望傳回所有欄位。

object (CollectionSelector)

要查詢的集合。

object (Filter)

要套用的篩選器。

object (Order)

要套用至查詢結果的順序。

Firestore 可讓呼叫端提供完整訂購、部分排序或完全不排序。在所有情況下，Firestore 都會透過下列規則確保以穩定的方式排序：

• 必須使用 orderBy 才能參照使用不等式篩選器的所有欄位。
• 所有必填欄位都必須位於 orderBy 中，但目前並未填寫的欄位，都會依照欄位名稱的字母順序排列。
• 如未指定 __name__ 的訂單，系統會依預設附加訂單。

欄位的排序方向會與最後指定的順序相同，如果未指定順序，則會附加「ASCENDING」。例如：

• ORDER BY a 變成 ORDER BY a ASC, __name__ ASC
• ORDER BY a DESC 變成 ORDER BY a DESC, __name__ DESC
• WHERE a > 1 變成 WHERE a > 1 ORDER BY a ASC, __name__ ASC
• WHERE __name__ > ... AND a > 1 變成 WHERE __name__ > ... AND a > 1 ORDER BY a ASC, __name__ ASC

object (Cursor)

結果集內可能開始查詢的位置前置字元。

結果集的排序依據原始查詢的 ORDER BY 子句。

SELECT * FROM k WHERE a = 1 AND b > 2 ORDER BY b ASC, __name__ ASC;

這項查詢的結果是按 (b ASC, __name__ ASC) 排序。

遊標可以參照完整順序或位置的前置字串，但參照的欄位數量不能超過提供的 ORDER BY 值。

延續上述範例，附加以下起始遊標會產生不同的影響：

• START BEFORE (2, /k/123)：在 a = 1 AND b > 2 AND __name__ > /k/123 之前開始查詢。
• START AFTER (10)：在 a = 1 AND b > 10 之後開始查詢。

需要掃描前 N 個結果才能略過，但 OFFSET 不同，起始遊標可讓查詢從邏輯位置開始。這個位置不需要與實際結果相符，系統就會從這個位置往前掃描，尋找下一份文件。

需求條件：

• 值的數量不得大於 ORDER BY 子句中指定的欄位數量。

object (Cursor)

結果集中位置的可能前置字串，查詢結束位置。

這與 START_AT 類似，但前者會控制結束位置，而非起始位置。

需求條件：

• 值的數量不得大於 ORDER BY 子句中指定的欄位數量。

integer

傳回第一個結果前略過的文件數量。

適用範圍是在 WHERE、START AT 和 END AT 指定的限制之後，但位於 LIMIT 子句之前。

需求條件：

• 指定的值必須大於或等於零 (如有)。

integer

要傳回的結果數上限。

在所有其他限制後方套用。

需求條件：

• 指定的值必須大於或等於零 (如有)。

object (FindNearest)

選用設定。可能的鄰近地區搜尋。

系統會先套用所有其他篩選器和排序，再套用這項設定。

找出最接近指定查詢向量的向量嵌入。