集計クエリを実行します。
この 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 |
必須。親リソース名。形式は |
リクエスト本文
リクエストの本文には、次の構造のデータが含まれます。
JSON 表現 |
---|
{ "explainOptions": { object ( |
フィールド | |
---|---|
explainOptions |
省略可。クエリのオプションについて説明します。設定すると、追加のクエリ統計情報が返されます。そうでない場合は、クエリ結果のみが返されます。 |
共用体フィールド query_type 。実行するクエリ。query_type は次のいずれかになります。 |
|
structuredAggregationQuery |
集計クエリ。 |
共用体フィールド consistency_selector 。クエリの整合性モード。デフォルトは強整合性です。consistency_selector は次のいずれかになります。 |
|
transaction |
すでにアクティブなトランザクション内で集計を実行します。 この値は、クエリを実行する不透明トランザクション ID です。 Base64 でエンコードされた文字列。 |
newTransaction |
クエリの一部として新しいトランザクションを開始します。デフォルトは読み取り専用です。 新しいトランザクション ID は、ストリーム内の最初のレスポンスとして返されます。 |
readTime |
指定されたタイムスタンプでクエリを実行します。 これは、過去 1 時間以内のマイクロ秒の精度のタイムスタンプにする必要があります。ポイントインタイム リカバリが有効になっている場合は、過去 7 日間以内の 1 分単位のタイムスタンプにすることもできます。 RFC3339 UTC「Zulu」形式のタイムスタンプ。精度はナノ秒まで、小数点以下は最大 9 桁。例: |
レスポンスの本文
Firestore.RunAggregationQuery
に対するレスポンス。
成功すると、レスポンスの本文に次の構造のデータが含まれます。
JSON 表現 |
---|
{ "result": { object ( |
フィールド | |
---|---|
result |
単一の集計結果。 部分的な進捗状況を報告する場合は表示されません。 |
transaction |
このリクエストの一部として開始されたトランザクション。 リクエストが新しいトランザクションの開始をリクエストしたときの最初のレスポンスにのみ存在します。 Base64 でエンコードされた文字列。 |
readTime |
集計結果が計算された時刻。これは常に単調に増加します。この場合、結果ストリームの以前の AggregationResult は、 クエリが結果を返さない場合、 RFC3339 UTC「Zulu」形式のタイムスタンプ。精度はナノ秒まで、小数点以下は最大 9 桁。例: |
explainMetrics |
クエリ説明の指標。これは、 |
承認スコープ
次の OAuth スコープのいずれかが必要です。
https://www.googleapis.com/auth/datastore
https://www.googleapis.com/auth/cloud-platform
詳細については、認証の概要をご覧ください。
StructuredAggregationQuery
StructuredQuery
に対して集計を実行するための Firestore クエリ。
JSON 表現 |
---|
{ "aggregations": [ { object ( |
フィールド | |
---|---|
aggregations[] |
省略可。 必須の要素
|
共用体フィールド query_type 。集計する基本クエリ。query_type は次のいずれかになります。 |
|
structuredQuery |
ネストされた構造化クエリ。 |
集計
単一の結果を生成する集計を定義します。
JSON 表現 |
---|
{ "alias": string, // Union field |
フィールド | |
---|---|
alias |
省略可。集計の結果を格納するフィールドの名前(省略可)。 指定しない場合、Firestore は
は、次のようになります:
必須の要素
|
共用体フィールド operator 。実行する集計のタイプ(必須)。operator は次のいずれかになります。 |
|
count |
カウント アグリゲータ。 |
sum |
合計値。 |
avg |
平均的なアグリゲータ。 |
数
クエリに一致するドキュメントの数。
COUNT(*)
集計関数はドキュメント全体に対して動作するため、フィールド参照は必要ありません。
JSON 表現 |
---|
{ "upTo": string } |
フィールド | |
---|---|
upTo |
省略可。カウントするドキュメントの最大数に関するオプションの制約。 これにより、スキャンするドキュメントの数に上限を設定し、レイテンシとコストを抑えることができます。 [指定なし] は、範囲なしと解釈されます。 大まかな例:
必須の要素
|
合計
リクエストされたフィールドの値の合計。
数値のみが集計されます。
NULL
を含む、数値以外の値はすべてスキップされます。集計値に
NaN
が含まれている場合は、NaN
を返します。無限大の計算は IEEE-754 標準に準拠しています。集計値セットが空の場合は 0 を返します。
集計された数値がすべて整数で、合計結果がオーバーフローしない場合、64 ビットの整数を返します。それ以外の場合、結果は double として返されます。なお、すべての集計値が整数であっても、64 ビット符号付き整数に収まらない場合は、結果が double として返されます。この場合、返される値の精度は低下します。
アンダーフローが発生した場合、浮動小数点集計は非決定的です。つまり、基になる値を変更せずに同じクエリを繰り返し実行すると、毎回わずかに異なる結果が生じる可能性があります。そのような場合、値は浮動小数点数ではなく整数として格納する必要があります。
JSON 表現 |
---|
{
"field": {
object ( |
フィールド | |
---|---|
field |
集計対象のフィールド。 |
Avg
リクエストされたフィールドの値の平均。
数値のみが集計されます。
NULL
を含む、数値以外の値はすべてスキップされます。集計値に
NaN
が含まれている場合は、NaN
を返します。無限大の計算は IEEE-754 標準に準拠しています。集計値セットが空の場合は、
NULL
を返します。結果は常に double として返されます。
JSON 表現 |
---|
{
"field": {
object ( |
フィールド | |
---|---|
field |
集計対象のフィールド。 |
AggregationResult
Firestore 集約クエリからの単一バケットの結果。
aggregateFields
のキーは、結果ごとに異なるフィールドが存在する可能性があるドキュメント クエリとは異なり、集計クエリのすべての結果で同じです。
JSON 表現 |
---|
{
"aggregateFields": {
string: {
object ( |
フィールド | |
---|---|
aggregateFields |
集計関数の結果(例: キーは、入力時に集計関数に割り当てられた
|