Method: projects.databases.documents.runAggregationQuery

Toplama sorgusu çalıştırır.

Bu API, Firestore.RunQuery gibi Document sonuçları üretmek yerine, sunucu tarafında bir dizi AggregationResult oluşturmak için toplama çalıştırmaya olanak tanır.

Üst Düzey Örnek:

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

HTTP isteği

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

URL, gRPC Kod Dönüştürme söz dizimini kullanır.

Yol parametreleri

Parametreler
parent

string

Zorunlu. Üst kaynak adı. Şu biçimde: projects/{projectId}/databases/{databaseId}/documents veya projects/{projectId}/databases/{databaseId}/documents/{document_path}. Örneğin: projects/my-project/databases/my-database/documents veya projects/my-project/databases/my-database/documents/chatrooms/my-chatroom

İstek içeriği

İstek gövdesi, aşağıdaki yapıya sahip verileri içerir:

JSON gösterimi 
{
  "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.
}
Alanlar
explainOptions

object (ExplainOptions)

İsteğe bağlı. Sorguyla ilgili seçenekleri açıklayın. Ayarlanırsa ek sorgu istatistikleri döndürülür. Aksi takdirde yalnızca sorgu sonuçları döndürülür.
Birleştirme alanı query_type. Çalıştırılacak sorgu. query_type şunlardan yalnızca biri olabilir:
structuredAggregationQuery

object (StructuredAggregationQuery)

Toplama sorgusu.
Birleştirme alanı consistency_selector. Sorgu için tutarlılık modu, varsayılan olarak güçlü tutarlılıktır. consistency_selector şunlardan yalnızca biri olabilir:
transaction

string (bytes format)

Toplama işlemini zaten etkin olan bir işlemde çalıştırın.

Buradaki değer, sorgunun yürütüleceği opak işlem kimliğidir.

base64 kodlu bir dize.
newTransaction

object (TransactionOptions)

Sorgunun bir parçası olarak yeni bir işlem başlatır. Bu işlem varsayılan olarak salt okunur olur.

Yeni işlem kimliği, akıştaki ilk yanıt olarak döndürülür.
readTime

string (Timestamp format)

Sorguyu belirtilen zaman damgasında yürütür.

Bu, son bir saat içindeki mikrosaniyelik bir hassasiyet zaman damgası olmalıdır. Belirli bir noktadan önceyi kurtarma özelliği etkinse son 7 gün içindeki bir tam dakikalık zaman damgası da olabilir.

RFC3339 UTC "Zulu" zaman damgası biçiminde olmalıdır. Örnekler: "2014-10-02T15:01:23Z" ve "2014-10-02T15:01:23.045123456Z".

Yanıt gövdesi

Firestore.RunAggregationQuery için yanıt.

Başarılı olursa yanıt gövdesi aşağıdaki yapıyla birlikte verileri içerir:

JSON gösterimi 
{
  "result": {
    object (AggregationResult)
  },
  "transaction": string,
  "readTime": string,
  "explainMetrics": {
    object (ExplainMetrics)
  }
}
Alanlar
result

object (AggregationResult)

Tek bir toplama sonucu.

Kısmi ilerleme bildirilirken mevcut değildir.
transaction

string (bytes format)

Bu istek kapsamında başlatılan işlem.

Yalnızca istek yeni bir işlem başlatma isteğinde bulunduğunda ilk yanıtta gösterilir.

base64 kodlu bir dize.
readTime

string (Timestamp format)

Toplu sonucun hesaplandığı zaman. Bu değişim sürekli monoton bir şekilde artmaktadır. Bu durumda, sonuç akışındaki önceki AggregationResult öğesinin, readTime ve bu sonuç arasında değişmediği garanti edilir.

Sorgu hiçbir sonuç döndürmezse readTime değerini içeren ve result içermeyen bir yanıt gönderilmez. Bu, sorgunun çalıştırıldığı zamanı temsil eder.

RFC3339 UTC "Zulu" zaman damgası biçiminde olmalıdır. Örnekler: "2014-10-02T15:01:23Z" ve "2014-10-02T15:01:23.045123456Z".
explainMetrics

object (ExplainMetrics)

Sorgu, metrikleri açıklar. Bu mesaj yalnızca RunAggregationQueryRequest.explain_options sağlandığında mevcuttur ve akıştaki son yanıtla birlikte yalnızca bir kez gönderilir.

Yetkilendirme kapsamları

Aşağıdaki OAuth kapsamlarından birini gerektirir:

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

Daha fazla bilgi için Kimlik Doğrulamaya Genel Bakış başlıklı makaleye bakın.

YapılandırılmışAggregationQuery

StructuredQuery üzerinde toplama çalıştırmayla ilgili Firestore sorgusu.

JSON gösterimi 
{
  "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.
}
Alanlar
aggregations[]

object (Aggregation)

İsteğe bağlı. structuredQuery sonuçlarına uygulanacak toplama serisi.

Gerekenler:

  • Sorgu başına en az bir, en fazla beş toplama.
Birleştirme alanı query_type. Toplama işlemi için temel sorgu. query_type şunlardan yalnızca biri olabilir:
structuredQuery

object (StructuredQuery)

İç içe yerleştirilmiş yapılandırılmış sorgu.

Toplama

Tek bir sonuç üreten bir toplamayı tanımlar.

JSON gösterimi 
{
  "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.
}
Alanlar
alias

string

İsteğe bağlı. Toplama sonucunun depolanacağı alanın isteğe bağlı adı.

Sağlanmazsa Firestore, field_<incremental_id++> biçiminde varsayılan bir ad seçer. Örneğin:

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

şu hale gelir:

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

Gerekenler:

  • Tüm toplama takma adları genelinde benzersiz olmalıdır.
  • document field name sınırlamalarına uyun.
Birleştirme alanı operator. Gerçekleştirilecek toplama türü, zorunludur. operator şunlardan yalnızca biri olabilir:
count

object (Count)

Sayı toplayıcı.
sum

object (Sum)

Toplam toplayıcı.
avg

object (Avg)

Ortalama toplayıcı.

Sayı

Sorguyla eşleşen dokümanların sayısı.

COUNT(*) toplama işlevi belgenin tamamında çalıştığından alan başvurusu gerektirmez.

JSON gösterimi 
{
  "upTo": string
}
Alanlar
upTo

string (Int64Value format)

İsteğe bağlı. Sayılacak maksimum doküman sayısıyla ilgili isteğe bağlı kısıtlama.

Bu, taranacak doküman sayısı için bir üst sınır ayarlamanın bir yolunu sunar, gecikmeyi ve maliyeti sınırlar.

Belirtilmedi, sınır yok olarak yorumlanır.

Üst Düzey Örnek:

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

Gerekenler:

  • Mevcut olduğunda sıfırdan büyük olmalıdır.

Toplam

İstenen alanın değerlerinin toplamı.

  • Yalnızca sayısal değerler toplanır. NULL dahil olmak üzere sayısal olmayan tüm değerler atlanır.

  • Toplam değerler NaN içeriyorsa NaN değerini döndürür. Infinity Matematik, IEEE-754 standartlarını uygular.

  • Toplam değer grubu boşsa 0 değerini döndürür.

  • Tüm toplanan sayılar tam sayıysa ve toplam sonuç taşmıyorsa 64 bitlik bir tam sayı döndürür. Aksi takdirde sonuç, çift duyarlıklı sayı olarak döndürülür. Toplam değerler tam sayı olsa bile, 64 bit imzalı tam sayıya sığmıyorsa sonucun çift değer olarak döndürüleceğini unutmayın. Bu durumda, döndürülen değer kesinlik düzeyini kaybeder.

  • Az akış gerçekleştiğinde, kayan nokta toplaması belirleyici değildir. Diğer bir deyişle, aynı sorguyu temel değerlerde herhangi bir değişiklik olmadan tekrar tekrar çalıştırmak her seferinde biraz farklı sonuçlar verebilir. Böyle durumlarda değerler, kayan noktalı sayılar yerine tam sayı olarak depolanmalıdır.

JSON gösterimi 
{
  "field": {
    object (FieldReference)
  }
}
Alanlar
field

object (FieldReference)

Toplama işlemi için kullanılan alan.

Ort.

İstenen alandaki değerlerin ortalaması.

  • Yalnızca sayısal değerler toplanır. NULL dahil olmak üzere sayısal olmayan tüm değerler atlanır.

  • Toplam değerler NaN içeriyorsa NaN değerini döndürür. Infinity Matematik, IEEE-754 standartlarını uygular.

  • Toplam değer grubu boşsa NULL değerini döndürür.

  • Sonucu her zaman çift duyarlıklı sayı olarak döndürür.

JSON gösterimi 
{
  "field": {
    object (FieldReference)
  }
}
Alanlar
field

object (FieldReference)

Toplama işlemi için kullanılan alan.

AggregationResult

Firestore toplama sorgusundaki tek bir paketin sonucu.

aggregateFields anahtarları, toplama sorgusundaki tüm sonuçlar için aynıdır. Her sonuç için farklı alanlara sahip olabilen belge sorgularının aksine.

JSON gösterimi 
{
  "aggregateFields": {
    string: {
      object (Value)
    },
    ...
  }
}
Alanlar
aggregateFields

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

Toplama işlevlerinin sonucu, ör. COUNT(*) AS total_docs.

Anahtar, girişteki toplama işlevine atanan alias öğesidir. Bu haritanın boyutu, sorgudaki toplama işlevlerinin sayısına eşittir.

"key": value çiftlerinin listesini içeren bir nesne. Örnek: { "name": "wrench", "mass": "1.3kg", "count": "3" }.