StructuredQuery

Firestore クエリ。

クエリ ステージは、次の順序で実行されます。1. から 2. ここで、3. select 4. orderBy + startAt + endAt 5. offset 6. limit

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__'] を使用します。

CollectionSelector

コレクションの選択（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 つを満たす必要があります。

FieldFilter

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

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 は、指定された配列内の少なくとも 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 で最初に行われます。

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 で最初に行われます。
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 降順。

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 コサインに似ていますが、ベクトルの大きさの影響を受けます。詳しくは、ドットプロダクトをご覧ください。