Menjalankan kueri agregasi.
Daripada memberikan hasil Document
seperti Firestore.RunQuery
, API ini memungkinkan Anda menjalankan agregasi untuk menghasilkan serangkaian AggregationResult
sisi server.
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/v1/{parent=projects/*/databases/*/documents}:runAggregationQuery
URL menggunakan sintaksis gRPC Transcoding.
Parameter jalur
Parameter | |
---|---|
parent |
Wajib. Nama resource induk. Dalam format: |
Isi permintaan
Isi permintaan memuat data dengan struktur berikut:
Representasi JSON |
---|
{ "explainOptions": { object ( |
Kolom | |
---|---|
explainOptions |
Opsional. Menjelaskan opsi untuk kueri tersebut. 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 |
Kueri agregasi. |
Kolom union consistency_selector . Mode konsistensi untuk kueri secara default disetel ke konsistensi kuat. consistency_selector hanya ada berupa salah satu diantara berikut: |
|
transaction |
Jalankan agregasi dalam transaksi yang sudah aktif. Nilai di sini adalah ID transaksi buram untuk mengeksekusi kueri. String berenkode base64. |
newTransaction |
Memulai transaksi baru sebagai bagian dari kueri, yang setelan defaultnya adalah hanya baca. ID transaksi baru akan ditampilkan sebagai respons pertama dalam aliran data. |
readTime |
Mengeksekusi kueri pada stempel waktu yang ditentukan. Ini harus berupa stempel waktu presisi mikrodetik dalam satu jam terakhir, atau jika Pemulihan Point-in-Time diaktifkan, dapat juga berupa stempel waktu menit penuh dalam 7 hari terakhir. Stempel waktu dalam format RFC3339 UTC "Zulu", dengan resolusi nanodetik dan maksimal sembilan digit fraksional. Contoh: |
Isi respons
Respons untuk Firestore.RunAggregationQuery
.
Jika berhasil, isi respons memuat data dengan struktur berikut:
Representasi JSON |
---|
{ "result": { object ( |
Kolom | |
---|---|
result |
Hasil agregasi tunggal. Tidak ada saat melaporkan progres sebagian. |
transaction |
Transaksi yang dimulai sebagai bagian dari permintaan ini. Hanya ada di respons pertama saat permintaan meminta untuk memulai transaksi baru. String berenkode base64. |
readTime |
Waktu saat hasil agregat dihitung. Hal ini selalu meningkat secara monoton; dalam hal ini, AggregationResult sebelumnya di aliran hasil dijamin tidak berubah antara Jika kueri tidak menampilkan hasil, respons dengan Stempel waktu dalam format RFC3339 UTC "Zulu", dengan resolusi nanodetik dan maksimal sembilan digit fraksional. Contoh: |
explainMetrics |
Mengkueri metrik. Hal ini hanya ada jika |
Cakupan otorisasi
Memerlukan salah satu cakupan OAuth berikut:
https://www.googleapis.com/auth/datastore
https://www.googleapis.com/auth/cloud-platform
Untuk informasi selengkapnya, lihat Ringkasan Autentikasi.
StructuredAggregationQuery
Kueri Firestore untuk menjalankan agregasi pada StructuredQuery
.
Representasi JSON |
---|
{ "aggregations": [ { object ( |
Kolom | |
---|---|
aggregations[] |
Opsional. Serangkaian agregasi yang akan diterapkan pada hasil Memerlukan:
|
Kolom union query_type . Kueri dasar yang akan digabungkan. query_type hanya ada berupa salah satu diantara berikut: |
|
structuredQuery |
Kueri terstruktur bertingkat. |
Agregasi
Menentukan agregasi yang menghasilkan satu hasil.
Representasi JSON |
---|
{ "alias": string, // Union field |
Kolom | |
---|---|
alias |
Opsional. Nama opsional kolom untuk menyimpan hasil agregasi. Jika tidak diberikan, Firestore akan memilih nama default dengan mengikuti format
menjadi:
Memerlukan:
|
Kolom union operator . Jenis agregasi yang akan dilakukan, diperlukan. operator hanya ada berupa salah satu diantara berikut: |
|
count |
Agregator jumlah. |
sum |
Agregator jumlah. |
avg |
Agregator rata-rata. |
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 |
Opsional. Batasan opsional pada jumlah maksimum dokumen yang akan dihitung. Cara ini menyediakan cara untuk menetapkan batas atas jumlah dokumen yang akan dipindai, membatasi latensi, dan biaya. Tidak ditentukan ditafsirkan sebagai tanpa ikatan. Contoh Tingkat Tinggi:
Memerlukan:
|
Total
Jumlah nilai kolom yang diminta.
Hanya nilai numerik yang akan diagregasi. Semua nilai non-numerik termasuk
NULL
akan dilewati.Jika nilai gabungan berisi
NaN
, tampilkanNaN
. Matematika tak terbatas mengikuti standar IEEE-754.Jika kumpulan nilai gabungan kosong, nilai yang ditampilkan adalah 0.
Menampilkan bilangan bulat 64-bit jika semua angka gabungan adalah bilangan bulat dan hasil jumlah tidak meluap. Jika tidak, hasilnya ditampilkan sebagai ganda. Perhatikan bahwa meskipun semua nilai gabungan adalah bilangan bulat, hasilnya akan ditampilkan sebagai ganda jika tidak bisa muat dalam bilangan bulat 64-bit yang telah ditandai. Jika hal ini terjadi, nilai yang ditampilkan akan kehilangan presisi.
Jika terjadi underflow, agregasi floating point bersifat non-deterministik. Ini berarti, menjalankan kueri yang sama berulang kali tanpa perubahan apa pun pada nilai yang mendasarinya dapat memberikan hasil yang sedikit berbeda setiap waktu. Dalam kasus tersebut, nilai harus disimpan sebagai bilangan bulat di atas angka floating point.
Representasi JSON |
---|
{
"field": {
object ( |
Kolom | |
---|---|
field |
Kolom yang akan digabungkan. |
Avg
Rata-rata nilai kolom yang diminta.
Hanya nilai numerik yang akan diagregasi. Semua nilai non-numerik termasuk
NULL
akan dilewati.Jika nilai gabungan berisi
NaN
, tampilkanNaN
. Matematika tak terbatas mengikuti standar IEEE-754.Jika kumpulan nilai gabungan kosong, tampilkan
NULL
.Selalu tampilkan hasilnya sebagai ganda.
Representasi JSON |
---|
{
"field": {
object ( |
Kolom | |
---|---|
field |
Kolom yang akan digabungkan. |
AggregationResult
Hasil satu bucket 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 ( |
Kolom | |
---|---|
aggregateFields |
Hasil fungsi agregasi, misalnya: Kuncinya adalah Objek yang berisi daftar pasangan |