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 之後開始查詢。

OFFSET 需要掃描前 N 個結果才能略過，但開始遊標允許查詢從邏輯位置開始。此位置不需要符合實際結果，系統會從這個位置向前掃描，尋找下一份文件。

需求：

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

object (Cursor)

在結果集中，為查詢結束位置的潛在前置字串。

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

需求：

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

integer

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

此情況會在 WHERE、START AT 和 END AT 指定的限制後方，但在 LIMIT 子句之前。

需求：

• 指定的值必須大於或等於零。

integer

要傳回的結果數上限。

在所有限制之後套用。

需求：

• 指定的值必須大於或等於零。

object (FindNearest)

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

套用到所有其他篩選條件和排序。

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