Method: projects.databases.documents.runAggregationQuery

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/v1beta1/{parent=projects/*/databases/*/documents}:runAggregationQuery

URL menggunakan sintaksis gRPC Transcoding.

Parameter jalur

Parameter
parent

string

Wajib. 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 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

object (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

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, yang setelan defaultnya adalah hanya baca.

ID transaksi baru akan ditampilkan sebagai respons pertama dalam aliran data.
readTime

string (Timestamp format)

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: "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 sebagian.
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 agregat dihitung. Hal ini selalu meningkat secara monoton; dalam hal ini, AggregationResult sebelumnya di aliran hasil dijamin tidak berubah antara readTime dan yang ini.

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

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

object (ExplainMetrics)

Mengkueri metrik. Hal ini hanya ada jika RunAggregationQueryRequest.explain_options disediakan, dan hanya dikirim sekali dengan respons terakhir di 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 informasi selengkapnya, lihat Ringkasan Autentikasi.

StructuredAggregationQuery

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.

Memerlukan:

  • Minimal satu dan maksimum lima agregasi per kueri.
Kolom union query_type. Kueri dasar yang akan digabungkan. 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 diberikan, 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 (
  ...
);

Memerlukan:
Kolom union operator. Jenis agregasi yang akan dilakukan, diperlukan. operator hanya ada berupa salah satu diantara berikut:
count

object (Count)

Agregator jumlah.
sum

object (Sum)

Agregator jumlah.
avg

object (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

string (Int64Value format)

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:

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

Memerlukan:

  • Harus lebih besar dari nol saat ada.

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, tampilkan NaN. 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 (FieldReference)
  }
}
Kolom
field

object (FieldReference)

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, tampilkan NaN. Matematika tak terbatas mengikuti standar IEEE-754.

  • Jika kumpulan nilai gabungan kosong, tampilkan NULL.

  • Selalu tampilkan hasilnya sebagai ganda.

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

object (FieldReference)

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 (Value)
    },
    ...
  }
}
Kolom
aggregateFields

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

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

Kuncinya adalah alias yang ditetapkan ke 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" }.