StructuredQuery

Firestore クエリ。

クエリのステージは、1. from 2.、、、、、、、、、、、、、、、、、、、、、、、、、、、、、、、、、、、、、、、、、、、、、、、、、、、、、、、、、、、、、。

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 句の前。

必須の要素

  • 指定する場合は、0 以上の値を指定する必要があります。
limit

integer

返される結果の最大件数です。

他のすべての制約の後に適用されます。

必須の要素

  • 指定する場合は、0 以上の値を指定する必要があります。
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)

引数を 1 つだけ受け取るフィルタ。

CompositeFilter

指定した演算子を使用して他の複数のフィルタを結合するフィルタ。

JSON 表現 
{
  "op": enum (Operator),
  "filters": [
    {
      object (Filter)
    }
  ]
}
フィールド
op

enum (Operator)

複数のフィルタを組み合わせるための演算子。
filters[]

object (Filter)

結合するフィルタのリスト。

必須の要素

  • 少なくとも 1 つのフィルタがあります。

演算子

複合フィルタ演算子。

列挙値
OPERATOR_UNSPECIFIED 指定なし。この値は使用しないでください。
AND ドキュメントは、結合されたすべてのフィルタを満たす必要があります。
OR ドキュメントは組み合わせたフィルタの少なくとも 1 つを満たす必要があります。

フィールド フィルタ

特定のフィールドに対するフィルタ。

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 を下回っています。

必須の要素

  • orderBy ではその field が 1 位です。
LESS_THAN_OR_EQUAL

指定された field が指定された value 以下である。

必須の要素

  • orderBy ではその field が 1 位です。
GREATER_THAN

指定された field が、指定された value を上回っています。

必須の要素

  • orderBy ではその field が 1 位です。
GREATER_THAN_OR_EQUAL

指定された field が指定された value 以上である。

必須の要素

  • orderBy ではその field が 1 位です。
EQUAL 指定された field が指定された value と等しい。
NOT_EQUAL

指定された field が、指定された value と等しくありません。

必須の要素

  • 他に NOT_EQUAL、NOT_IN、IS_NOT_NULL、IS_NOT_NAN はありません。
  • そのfieldがorderByの第 1 位です。
ARRAY_CONTAINS 指定された field は、指定された value を含む配列です。
IN

指定された field が、指定された配列内の 1 つ以上の値と等しい。

必須の要素

  • この value は空でない ArrayValue であり、分離制限が適用されます。
  • 同じクエリに NOT_IN フィルタがありません。
ARRAY_CONTAINS_ANY

指定された field は、指定された配列内のいずれかの値を含む配列です。

必須の要素

  • この value は空でない ArrayValue であり、分離制限が適用されます。
  • 同じ分離内に他の ARRAY_CONTAINS_ANY フィルタがない。
  • 同じクエリに NOT_IN フィルタがありません。
NOT_IN

field の値が指定された配列にありません。

必須の要素

  • この value は、最大 10 個の値を持つ空でない ArrayValue です。
  • 他に OR、IN、ARRAY_CONTAINS_ANY、NOT_IN、NOT_EQUAL、IS_NOT_NULL、IS_NOT_NAN はありません。
  • そのfieldがorderByの第 1 位です。

UnaryFilter

単一のオペランドを持つフィルタ。

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の第 1 位です。
IS_NOT_NULL

指定された field が NULL と等しくない。

必須の要素

  • 1 つの NOT_EQUAL、NOT_IN、IS_NOT_NULL、または IS_NOT_NAN。
  • そのfieldがorderByの第 1 位です。

注文

フィールド上の順序。

JSON 表現 
{
  "field": {
    object (FieldReference)
  },
  "direction": enum (Direction)
}
フィールド
field

object (FieldReference)

並べ替えるフィールド。
direction

enum (Direction)

並べ替えの方向。デフォルトは ASCENDING です。

方向

並べ替えの方向。

列挙型
DIRECTION_UNSPECIFIED 未設定。
ASCENDING 昇順。
DESCENDING 降順。

FindNearest

最近傍探索の構成。

JSON 表現 
{
  "vectorField": {
    object (FieldReference)
  },
  "queryVector": {
    object (Value)
  },
  "distanceMeasure": enum (DistanceMeasure),
  "limit": integer
}
フィールド
vectorField

object (FieldReference)

必須。検索するインデックス付きベクトル フィールド。次元が queryVector に一致するベクトルを含むドキュメントのみが返されます。
queryVector

object (Value)

必須。検索対象のクエリベクトル。2,048 次元以下のベクトルにする必要があります。
distanceMeasure

enum (DistanceMeasure)

必須。使用する距離尺度（必須）。
limit

integer

必須。返される最近傍の数。1,000 以下の正の整数を指定する必要があります。

DistanceMeasure

ベクトルを比較するときに使用する距離の尺度。

列挙型
DISTANCE_MEASURE_UNSPECIFIED 設定しないでください。
EUCLIDEAN ベクトル間の EUCLIDEAN 距離を測定します。詳しくは、ユークリッドをご覧ください。
COSINE ベクトル間の角度に基づいてベクトルを比較します。これにより、ベクトルの大きさに基づかない類似性を測定できます。COSINE 距離ではなく、単位正規化ベクトルで DOT_PRODUCT を使用することをおすすめします。COSINE 距離は数学的に同等でパフォーマンスが向上します。詳しくは、コサイン類似度をご覧ください。
DOT_PRODUCT コサインに似ていますが、ベクトルの大きさの影響を受けます。詳細については、ドット積をご覧ください。