Method: projects.databases.documents.runAggregationQuery

Menjalankan kueri agregasi.

API ini memungkinkan menjalankan agregasi untuk menghasilkan serangkaian AggregationResult sisi server, bukan memberikan hasil Document seperti Firestore.RunQuery.

Contoh Tingkat Tinggi:

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

Permintaan HTTP

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

URL menggunakan sintaks gRPC Transcoding.

Parameter jalur

Parameter
parent

string

Wajib diisi. Nama resource induk. Dalam format: projects/{projectId}/databases/{databaseId}/documents atau projects/{projectId}/databases/{databaseId}/documents/{document_path}. Contoh: projects/my-project/databases/my-database/documents atau projects/my-project/databases/my-database/documents/chatrooms/my-chatroom

Isi permintaan

Isi permintaan memuat data dengan struktur berikut:

Representasi 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.
}
Kolom
explainOptions

object (ExplainOptions)

Opsional. Menjelaskan opsi untuk kueri. Jika ditetapkan, statistik kueri tambahan akan ditampilkan. Jika tidak, hanya hasil kueri yang akan ditampilkan.
Kolom union query_type. Kueri yang akan dijalankan. query_type hanya ada berupa salah satu diantara berikut:
structuredAggregationQuery

object (StructuredAggregationQuery)

Kueri agregasi.
Kolom union consistency_selector. Mode konsistensi untuk kueri, ditetapkan secara default ke konsistensi kuat. consistency_selector hanya ada berupa salah satu diantara berikut:
transaction

string (bytes format)

Jalankan agregasi dalam transaksi yang sudah aktif.

Nilai di sini adalah ID transaksi buram untuk mengeksekusi kueri.

String berenkode base64.
newTransaction

object (TransactionOptions)

Memulai transaksi baru sebagai bagian dari kueri, dengan setelan default ke hanya baca.

ID transaksi baru akan ditampilkan sebagai respons pertama dalam streaming.
readTime

string (Timestamp format)

Mengeksekusi kueri pada stempel waktu yang diberikan.

Ini harus berupa stempel waktu presisi mikrodetik dalam satu jam terakhir, atau jika Pemulihan Point-in-Time diaktifkan, juga dapat berupa stempel waktu menit penuh dalam 7 hari terakhir.

Stempel waktu dalam RFC3339 UTC "Zulu" , dengan resolusi nanodetik dan hingga sembilan digit pecahan. Contoh: "2014-10-02T15:01:23Z" dan "2014-10-02T15:01:23.045123456Z".

Isi respons

Respons untuk Firestore.RunAggregationQuery.

Jika berhasil, isi respons memuat data dengan struktur berikut:

Representasi JSON 
{
  "result": {
    object (AggregationResult)
  },
  "transaction": string,
  "readTime": string,
  "explainMetrics": {
    object (ExplainMetrics)
  }
}
Kolom
result

object (AggregationResult)

Hasil agregasi tunggal.

Tidak ada saat melaporkan progres parsial.
transaction

string (bytes format)

Transaksi yang dimulai sebagai bagian dari permintaan ini.

Hanya ada di respons pertama saat permintaan meminta untuk memulai transaksi baru.

String berenkode base64.
readTime

string (Timestamp format)

Waktu saat hasil gabungan dihitung. Hal ini selalu meningkat secara monoton; dalam hal ini, AggregationResult sebelumnya di aliran hasil dijamin tidak akan berubah antara readTime dan yang ini.

Jika kueri tidak menampilkan hasil, respons dengan readTime dan tidak ada result akan dikirim, dan ini menunjukkan waktu saat kueri dijalankan.

Stempel waktu dalam RFC3339 UTC "Zulu" , dengan resolusi nanodetik dan hingga sembilan digit pecahan. Contoh: "2014-10-02T15:01:23Z" dan "2014-10-02T15:01:23.045123456Z".
explainMetrics

object (ExplainMetrics)

Metrik penjelasan kueri. Ini hanya ada saat RunAggregationQueryRequest.explain_options disediakan, dan hanya dikirim sekali dengan respons terakhir dalam aliran data.

Cakupan otorisasi

Memerlukan salah satu cakupan OAuth berikut:

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

Untuk mengetahui informasi selengkapnya, lihat Ringkasan Autentikasi.

Kueri Agregasi Terstruktur

Kueri Firestore untuk menjalankan agregasi pada StructuredQuery.

Representasi 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.
}
Kolom
aggregations[]

object (Aggregation)

Opsional. Serangkaian agregasi yang akan diterapkan pada hasil structuredQuery.

Membutuhkan:

  • Minimal satu dan maksimum lima agregasi per kueri.
Kolom union query_type. Kueri dasar yang akan diagregasi. query_type hanya ada berupa salah satu diantara berikut:
structuredQuery

object (StructuredQuery)

Kueri terstruktur bertingkat.

Agregasi

Menentukan agregasi yang menghasilkan satu hasil.

Representasi 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.
}
Kolom
alias

string

Opsional. Nama opsional kolom untuk menyimpan hasil agregasi.

Jika tidak disediakan, Firestore akan memilih nama default dengan mengikuti format field_<incremental_id++>. Contoh:

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 (
  ...
);

menjadi:

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 (
  ...
);

Membutuhkan:
Kolom union operator. Jenis agregasi yang akan dilakukan, wajib diisi. operator hanya ada berupa salah satu diantara berikut:
count

object (Count)

Agregator penghitungan.
sum

object (Sum)

Agregator jumlah.
avg

object (Avg)

Rata-rata agregator.

Jumlah

Jumlah dokumen yang cocok dengan kueri.

Fungsi agregasi COUNT(*) beroperasi di seluruh dokumen sehingga tidak memerlukan referensi kolom.

Representasi JSON 
{
  "upTo": string
}
Kolom
upTo

string (Int64Value format)

Opsional. Batasan opsional pada jumlah maksimum dokumen yang akan dihitung.

Hal ini menyediakan cara untuk menetapkan batas atas jumlah dokumen yang akan dipindai, membatasi latensi, dan biaya.

{i>Unspecified<i} ditafsirkan sebagai tidak terikat.

Contoh Tingkat Tinggi:

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

Membutuhkan:

  • Harus lebih besar dari nol jika ada.

Jumlah

Jumlah nilai kolom yang diminta.

  • Hanya nilai numerik yang akan diagregasi. Semua nilai non-numerik termasuk NULL dilewati.

  • Jika nilai gabungan berisi NaN, akan menampilkan NaN. Matematika tanpa batas mengikuti standar IEEE-754.

  • Jika kumpulan nilai gabungan kosong, akan menampilkan 0.

  • Menampilkan bilangan bulat 64-bit jika semua bilangan yang diagregasi adalah bilangan bulat dan hasil penjumlahan tidak meluap. Jika tidak, hasilnya akan ditampilkan sebagai double. Perhatikan bahwa meskipun semua nilai yang diagregasi adalah bilangan bulat, hasilnya akan ditampilkan sebagai ganda jika tidak sesuai dengan bilangan bulat dengan tanda tangan 64-bit. Jika ini terjadi, nilai yang ditampilkan akan kehilangan presisi.

  • Jika underflow terjadi, agregasi floating point bersifat non-deterministik. Artinya, menjalankan kueri yang sama berulang kali tanpa mengubah nilai dasar dapat memberikan hasil yang sedikit berbeda setiap kalinya. Dalam kasus tersebut, nilai harus disimpan sebagai bilangan bulat di atas angka floating point.

Representasi JSON 
{
  "field": {
    object (FieldReference)
  }
}
Kolom
field

object (FieldReference)

Kolom tempat agregat.

Rata-rata

Rata-rata nilai kolom yang diminta.

  • Hanya nilai numerik yang akan diagregasi. Semua nilai non-numerik termasuk NULL dilewati.

  • Jika nilai gabungan berisi NaN, akan menampilkan NaN. Matematika tanpa batas mengikuti standar IEEE-754.

  • Jika kumpulan nilai gabungan kosong, NULL akan ditampilkan.

  • Selalu menampilkan hasil sebagai double.

Representasi JSON 
{
  "field": {
    object (FieldReference)
  }
}
Kolom
field

object (FieldReference)

Kolom tempat agregat.

Hasil Agregasi

Hasil bucket tunggal dari kueri agregasi Firestore.

Kunci aggregateFields sama untuk semua hasil dalam kueri agregasi, tidak seperti kueri dokumen yang dapat memiliki kolom berbeda untuk setiap hasil.

Representasi JSON 
{
  "aggregateFields": {
    string: {
      object (Value)
    },
    ...
  }
}
Kolom
aggregateFields

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

Hasil fungsi agregasi, misalnya: COUNT(*) AS total_docs.

Kuncinya adalah alias yang ditetapkan untuk fungsi agregasi pada input dan ukuran peta ini sama dengan jumlah fungsi agregasi dalam kueri.

Objek yang berisi daftar pasangan "key": value. Contoh: { "name": "wrench", "mass": "1.3kg", "count": "3" }.