Method: projects.databases.documents.runAggregationQuery

集計クエリを実行します。

この API を使用すると、Firestore.RunQuery のような Document の結果を生成する代わりに、集計を実行して一連の AggregationResult をサーバー側で生成できます。

大まかな例:

-- Return the number of documents in table given a filter.
SELECT COUNT(*) FROM ( SELECT * FROM k where a = true );

HTTP リクエスト

POST https://firestore.googleapis.com/v1beta1/{parent=projects/*/databases/*/documents}:runAggregationQuery

この URL は gRPC Transcoding 構文を使用します。

パスパラメータ

パラメータ
parent

string

必須。親リソース名。形式は projects/{projectId}/databases/{databaseId}/documents または projects/{projectId}/databases/{databaseId}/documents/{document_path} です。例: projects/my-project/databases/my-database/documents、projects/my-project/databases/my-database/documents/chatrooms/my-chatroom

リクエストの本文

リクエストの本文には、次の構造のデータが含まれます。

JSON 表現 
{
  "explainOptions": {
    object (ExplainOptions)
  },

  // Union field query_type can be only one of the following:
  "structuredAggregationQuery": {
    object (StructuredAggregationQuery)
  }
  // End of list of possible types for union field query_type.

  // Union field consistency_selector can be only one of the following:
  "transaction": string,
  "newTransaction": {
    object (TransactionOptions)
  },
  "readTime": string
  // End of list of possible types for union field consistency_selector.
}
フィールド
explainOptions

object (ExplainOptions)

省略可。クエリのオプションを説明します。設定すると、追加のクエリ統計情報が返されます。そうでない場合は、クエリ結果のみが返されます。
共用体フィールド query_type。実行するクエリ。query_type は次のいずれかになります。
structuredAggregationQuery

object (StructuredAggregationQuery)

集計クエリ。
共用体フィールド consistency_selector。クエリの整合性モードはデフォルトで強整合性になります。consistency_selector は次のいずれかになります。
transaction

string (bytes format)

すでにアクティブなトランザクション内で集計を実行します。

この値は、クエリを実行する不透明なトランザクション ID です。

Base64 でエンコードされた文字列。
newTransaction

object (TransactionOptions)

クエリの一部として新しいトランザクションを開始します。デフォルトは読み取り専用です。

新しい取引 ID が、ストリームの最初のレスポンスとして返されます。
readTime

string (Timestamp format)

指定されたタイムスタンプでクエリを実行します。

これは、過去 1 時間以内のマイクロ秒精度のタイムスタンプである必要があります。ポイントインタイム リカバリが有効になっている場合は、過去 7 日間の 1 分単位のタイムスタンプでも構いません。

RFC3339 UTC「Zulu」形式のタイムスタンプ。精度はナノ秒まで、小数点以下は最大 9 桁。例: "2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z"。

レスポンスの本文

Firestore.RunAggregationQuery に対するレスポンス。

成功した場合、レスポンスの本文には次の構造のデータが含まれます。

JSON 表現 
{
  "result": {
    object (AggregationResult)
  },
  "transaction": string,
  "readTime": string,
  "explainMetrics": {
    object (ExplainMetrics)
  }
}
フィールド
result

object (AggregationResult)

単一の集計結果。

部分的な進捗状況を報告している場合は表示されません。
transaction

string (bytes format)

このリクエストの一部として開始されたトランザクション。

リクエストが新しいトランザクションの開始をリクエストしたとき、最初のレスポンスにのみ存在します。

Base64 でエンコードされた文字列。
readTime

string (Timestamp format)

集計結果が計算された時刻。これは常に単調に増加します。この場合、結果ストリームの前の AggregationResult が、readTime とこの AggregationResult の間で変更されていないことが保証されます。

クエリから結果が返されない場合は、readTime が含まれ、result がないレスポンスが送信されます。これはクエリが実行された時刻を表します。

RFC3339 UTC「Zulu」形式のタイムスタンプ。精度はナノ秒まで、小数点以下は最大 9 桁。例: "2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z"。
explainMetrics

object (ExplainMetrics)

クエリ説明指標をクエリします。これは RunAggregationQueryRequest.explain_options が指定されている場合のみ存在し、ストリームの最後のレスポンスで 1 回だけ送信されます。

認可スコープ

以下のいずれかの OAuth スコープが必要です。

  • https://www.googleapis.com/auth/datastore
  • https://www.googleapis.com/auth/cloud-platform

詳細については、認証の概要をご覧ください。

StructuredAggregationQuery

StructuredQuery に対して集計を実行するための Firestore クエリ。

JSON 表現 
{
  "aggregations": [
    {
      object (Aggregation)
    }
  ],

  // Union field query_type can be only one of the following:
  "structuredQuery": {
    object (StructuredQuery)
  }
  // End of list of possible types for union field query_type.
}
フィールド
aggregations[]

object (Aggregation)

省略可。structuredQuery の結果に適用する一連の集計。

必須の要素

  • クエリごとに最小 1 つ、最大 5 つの集計。
共用体フィールド query_type。集計に使用する基本クエリ。query_type は次のいずれかになります。
structuredQuery

object (StructuredQuery)

ネストされた構造化クエリ。

集計

単一の結果を生成する集計を定義します。

JSON 表現 
{
  "alias": string,

  // Union field operator can be only one of the following:
  "count": {
    object (Count)
  },
  "sum": {
    object (Sum)
  },
  "avg": {
    object (Avg)
  }
  // End of list of possible types for union field operator.
}
フィールド
alias

string

省略可。集計の結果を保存するフィールドの名前（省略可）。

指定しない場合、Firestore は field_<incremental_id++> の形式のデフォルト名を選択します。例:

AGGREGATE
  COUNT_UP_TO(1) AS count_up_to_1,
  COUNT_UP_TO(2),
  COUNT_UP_TO(3) AS count_up_to_3,
  COUNT(*)
OVER (
  ...
);

次のようになります。

AGGREGATE
  COUNT_UP_TO(1) AS count_up_to_1,
  COUNT_UP_TO(2) AS field_1,
  COUNT_UP_TO(3) AS count_up_to_3,
  COUNT(*) AS field_2
OVER (
  ...
);

必須の要素

  • すべての集計エイリアスで一意である必要があります。
  • document field name の制限に従います。
共用体フィールド operator。実行する集計のタイプ。必須です。operator は次のいずれかになります。
count

object (Count)

カウント アグリゲータ。
sum

object (Sum)

合計集計関数。
avg

object (Avg)

平均アグリゲータ。

カウント

クエリに一致するドキュメントの数。

COUNT(*) 集計関数はドキュメント全体で動作するため、フィールド参照は必要ありません。

JSON 表現 
{
  "upTo": string
}
フィールド
upTo

string (Int64Value format)

省略可。カウントするドキュメントの最大数に関する任意の制約。

これにより、スキャンするドキュメント数に上限を設定し、レイテンシとコストを抑えることができます。

指定しない場合は、境界なしと解釈されます。

大まかな例:

AGGREGATE COUNT_UP_TO(1000) OVER ( SELECT * FROM k );

必須の要素

  • 指定する場合は 0 より大きい値にする必要があります。

合計

リクエストされたフィールドの値の合計。

  • 集計されるのは数値のみです。数値以外の値（NULL など）はすべてスキップされます。

  • 集計値に NaN が含まれている場合は、NaN を返します。無限大の数学は IEEE-754 規格に準拠しています。

  • 集計値セットが空の場合は 0 を返します。

  • 集計された数値がすべて整数で、合計結果がオーバーフローしない場合は、64 ビット整数を返します。それ以外の場合、結果は double として返されます。すべての集計値が整数であっても、64 ビット符号付き整数に収まらない場合は、結果が double として返されます。この場合、戻り値の精度が失われます。

  • アンダーフローが発生すると、浮動小数点集計は非決定的になります。つまり、基になる値を変更せずに同じクエリを繰り返し実行すると、毎回少し異なる結果が生成される可能性があります。このような場合、値は浮動小数点数ではなく整数として格納する必要があります。

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

object (FieldReference)

集計するフィールド。

平均

リクエストされたフィールドの値の平均。

  • 集計されるのは数値のみです。数値以外の値（NULL など）はすべてスキップされます。

  • 集計値に NaN が含まれている場合は、NaN を返します。無限大の数学は IEEE-754 規格に準拠しています。

  • 集計値セットが空の場合は、NULL を返します。

  • 結果は常に double として返します。

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

object (FieldReference)

集計するフィールド。

AggregationResult

Firestore 集計クエリからの単一バケットの結果。

aggregateFields のキーは、結果ごとに異なるフィールドが存在するドキュメント クエリとは異なり、集計クエリのすべての結果で同じです。

JSON 表現 
{
  "aggregateFields": {
    string: {
      object (Value)
    },
    ...
  }
}
フィールド
aggregateFields

map (key: string, value: object (Value))

集計関数の結果（例: COUNT(*) AS total_docs）。

キーは入力時に集計関数に割り当てられた alias で、このマップのサイズはクエリ内の集計関数の数と同じです。

"key": value ペアのリストを含むオブジェクト。例: { "name": "wrench", "mass": "1.3kg", "count": "3" }