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/v1/{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)

集計対象のフィールド。

Avg

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

  • 数値のみが集計されます。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" }