StructuredQuery

Firestore 查詢。

查詢階段的執行順序如下：1. 來自 2.，3. 選取 4. orderBy + startAt + endAt 5. 6. 限制

JSON 表示法 
{
  "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)
  }
}
欄位
select

object (Projection)

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

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

object (CollectionSelector)

要查詢的集合。
where

object (Filter)

要套用的篩選器。
orderBy[]

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
startAt

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 子句中指定的欄位數量。
endAt

object (Cursor)

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

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

需求條件：

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

integer

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

此情況會在 WHERE、START AT 和END AT，但在 LIMIT 子句之前。

需求條件：

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

integer

要傳回的結果數上限。

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

需求條件：

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

object (FindNearest)

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

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

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

投影

要傳回的文件欄位投影。

JSON 表示法 
{
  "fields": [
    {
      object (FieldReference)
    }
  ]
}
欄位
fields[]

object (FieldReference)

要傳回的欄位。

如果留空，系統會傳回所有欄位。如果只要傳回文件名稱，請使用 ['__name__']。

集合選取器

一個集合，例如 messages as m1。

JSON 表示法 
{
  "collectionId": string,
  "allDescendants": boolean
}
欄位
collectionId

string

集合 ID。設定後，請只選取具備這個 ID 的集合。
allDescendants

boolean

設為 false 時，僅選取所屬 RunQueryRequest 所含 parent 直系子項的集合。如果為 true，系統會選取所有子集合。

篩選器

篩選器。

JSON 表示法 
{

  // Union field filter_type can be only one of the following:
  "compositeFilter": {
    object (CompositeFilter)
  },
  "fieldFilter": {
    object (FieldFilter)
  },
  "unaryFilter": {
    object (UnaryFilter)
  }
  // End of list of possible types for union field filter_type.
}
欄位
聯集欄位 filter_type。篩選器類型。filter_type 只能採用下列其中一種設定：
compositeFilter

object (CompositeFilter)

複合篩選器。
fieldFilter

object (FieldFilter)

文件欄位的篩選器。
unaryFilter

object (UnaryFilter)

僅使用一個引數的篩選器。

CompositeFilter

使用指定運算子合併多個其他篩選器的篩選器。

JSON 表示法 
{
  "op": enum (Operator),
  "filters": [
    {
      object (Filter)
    }
  ]
}
欄位
op

enum (Operator)

用於合併多個篩選器的運算子。
filters[]

object (Filter)

要合併的篩選器清單。

需求條件：

  • 至少有一個篩選器。

運算子

複合篩選器運算子。

列舉
OPERATOR_UNSPECIFIED 未指定。不能使用這個值。
AND 文件須符合所有合併的篩選條件。
OR 文件必須至少符合其中一個合併的篩選條件。

欄位篩選器

特定欄位的篩選器。

JSON 表示法 
{
  "field": {
    object (FieldReference)
  },
  "op": enum (Operator),
  "value": {
    object (Value)
  }
}
欄位
field

object (FieldReference)

篩選依據的欄位。
op

enum (Operator)

要做為篩選依據的運算子。
value

object (Value)

要比較的值。

運算子

欄位篩選器運算子。

列舉
OPERATOR_UNSPECIFIED 未指定。不能使用這個值。
LESS_THAN

指定的 field 小於指定的 value。

需求條件：

  • 那field在 orderBy 首位。
LESS_THAN_OR_EQUAL

指定的 field 小於或等於指定的 value。

需求條件：

  • 那field在 orderBy 首位。
GREATER_THAN

指定的 field 大於指定的 value。

需求條件：

  • 那field在 orderBy 首位。
GREATER_THAN_OR_EQUAL

指定的 field 大於或等於指定的 value。

需求條件：

  • 那field在 orderBy 首位。
EQUAL 指定的 field 等於指定的 value。
NOT_EQUAL

指定的 field 不等於指定的 value。

需求條件：

  • 沒有其他 NOT_EQUAL、NOT_IN、IS_NOT_NULL 或 IS_NOT_NAN。
  • 第一個field在 orderBy 首度。
ARRAY_CONTAINS 指定的 field 是包含指定 value 的陣列。
IN

指定的 field 等於指定陣列中的至少一個值。

需求條件：

  • 該 value 是非空白的 ArrayValue，有消防限制。
  • 同一查詢中沒有任何 NOT_IN 篩選器。
ARRAY_CONTAINS_ANY

指定的 field 是一個陣列，其中包含指定陣列中的任一值。

需求條件：

  • 該 value 是非空白的 ArrayValue，有消防限制。
  • 同一串場內沒有其他 ARRAY_CONTAINS_ANY 篩選器。
  • 同一查詢中沒有任何 NOT_IN 篩選器。
NOT_IN

field 的值不在指定的陣列中。

需求條件：

  • 該 value 是非空白的 ArrayValue，最多有 10 個值。
  • 沒有其他 OR、IN、ARRAY_CONTAINS_ANY、NOT_IN、NOT_EQUAL、IS_NOT_NULL 或 IS_NOT_NAN。
  • 第一個field在 orderBy 首度。

一元篩選器

使用單一運算元的篩選器。

JSON 表示法 
{
  "op": enum (Operator),

  // Union field operand_type can be only one of the following:
  "field": {
    object (FieldReference)
  }
  // End of list of possible types for union field operand_type.
}
欄位
op

enum (Operator)

要套用的一元運算子。
聯集欄位 operand_type。篩選器的引數。operand_type 只能採用下列其中一種設定：
field

object (FieldReference)

要套用運算子的欄位。

運算子

一元運算子。

列舉
OPERATOR_UNSPECIFIED 未指定。不能使用這個值。
IS_NAN 指定的 field 等於 NaN。
IS_NULL 指定的 field 等於 NULL。
IS_NOT_NAN

指定的 field 不等於 NaN。

需求條件：

  • 沒有其他 NOT_EQUAL、NOT_IN、IS_NOT_NULL 或 IS_NOT_NAN。
  • 第一個field在 orderBy 首度。
IS_NOT_NULL

指定的 field 不等於 NULL。

需求條件：

  • 單一 NOT_EQUAL、NOT_IN、IS_NOT_NULL 或 IS_NOT_NAN。
  • 第一個field在 orderBy 首度。

順序

欄位順序。

JSON 表示法 
{
  "field": {
    object (FieldReference)
  },
  "direction": enum (Direction)
}
欄位
field

object (FieldReference)

要排序的欄位。
direction

enum (Direction)

排序依據。預設值為 ASCENDING。

方向

排序方向。

列舉
DIRECTION_UNSPECIFIED 未指定。
ASCENDING 遞增。
DESCENDING 遞減。

尋找最近的

「最鄰近項目」搜尋設定。

JSON 表示法 
{
  "vectorField": {
    object (FieldReference)
  },
  "queryVector": {
    object (Value)
  },
  "distanceMeasure": enum (DistanceMeasure),
  "limit": integer
}
欄位
vectorField

object (FieldReference)

執行個體類型，要搜尋的已建立索引向量欄位。系統只能傳回維度與 queryVector 相符的向量。
queryVector

object (Value)

執行個體類型，我們所搜尋的查詢向量。必須是不超過 2048 個尺寸的向量。
distanceMeasure

enum (DistanceMeasure)

執行個體類型，要使用的距離量，必要項目。
limit

integer

執行個體類型，要傳回的最鄰點數量。必須是不超過 1000 的正整數。

距離測量結果

比較向量時使用的距離。

列舉
DISTANCE_MEASURE_UNSPECIFIED 請勿設定。
EUCLIDEAN 測量向量之間的 EUCLIDEAN 距離。請參閱 Euclidean 瞭解詳情
COSINE 依據向量之間的角度比較向量，您就能衡量不是以向量規模為基準的相似度。建議您使用 DOT_PRODUCT 搭配單位正規化向量而不是 COSINE 距離，這在數學上等同於有更好的效能。詳情請參閱餘弦相似度。
DOT_PRODUCT 與餘弦相似，但受到向量的規模影響。詳情請參閱 Dot Product。