Method: projects.databases.documents.runAggregationQuery

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

Bu API, Firestore.RunQuery gibi Document sonuçları oluşturmak yerine, sunucu tarafında bir dizi AggregationResult üretmek için toplamanın çalıştırılmasına 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/v1/{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ı. Biçimi: 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

İsteğin gövdesi, aşağıdaki yapıya sahip veriler 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ığa ayarlanır. consistency_selector şunlardan yalnızca biri olabilir:
transaction

string (bytes format)

Toplamayı zaten etkin olan bir işlem içinde ç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)

Sorgu kapsamında yeni bir işlem başlatır ve varsayılan olarak salt okunurdur.

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

string (Timestamp format)

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

Bu, son 1 saat içindeki bir mikrosaniye hassasiyetli zaman damgası olmalıdır veya Belirli Bir Noktadan Kurtarma özelliği etkinleştirilmişse son 7 gün içindeki tam bir dakikalık zaman damgası da olabilir.

Nanosaniye çözünürlük ve en fazla dokuz kesir basamağı olan, RFC3339 UTC "Zulu" biçiminde bir zaman damgası. Ö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 metni 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 isteğin bir parçası olarak başlatılan işlem.

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

Base64 kodlu bir dize.
readTime

string (Timestamp format)

Toplam sonucun hesaplandığı zaman. Bu değer her zaman tekdüze artmaktadır. Bu durumda, sonuç akışındaki önceki AggregationResult öğesinin readTime ve bu değer arasında değişmemesi garanti edilir.

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

Nanosaniye çözünürlük ve en fazla dokuz kesir basamağı olan, RFC3339 UTC "Zulu" biçiminde bir zaman damgası. Örnekler: "2014-10-02T15:01:23Z" ve "2014-10-02T15:01:23.045123456Z".
explainMetrics

object (ExplainMetrics)

Sorgu açıklama metrikleri. Bu 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ış sayfasına göz atın.

StructuredAggregationQuery

StructuredQuery üzerinden toplama çalıştırmak için kullanılan 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ı üzerine uygulanacak toplama dizisi.

Gereken:

  • Sorgu başına en az bir, en fazla beş toplama.
Birleştirme alanı query_type. Toplanacak 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 toplama 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ı.

Belirtilmezse Firestore field_<incremental_id++> biçimini izleyen 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 (
  ...
);

Gereken:

  • Tüm toplama takma adlarında benzersiz olmalıdır.
  • document field name sınırlamalarına uyun.
Birleştirme alanı operator. Gerçekleştirilecek toplama türüdür, gerekli. 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ıdır.

COUNT(*) toplama işlevi dokümanın tamamında çalıştığından alana başvuru 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ı sınırlama.

Bu, taranacak doküman sayısı için bir üst sınır ayarlama yolu sağlar, gecikmeyi ve maliyeti sınırlar.

Belirtilmemiş ifadesi, sınır yok olarak yorumlanır.

Üst Düzey Örnek:

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

Gereken:

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

Toplam

İstenen alandaki değerlerin toplamı.

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

  • Toplam değerler NaN içeriyorsa NaN değerini döndürür. Sonsuzluk matematiği, IEEE-754 standartlarına uygundur.

  • Ayarlanmış toplam değer boşsa 0 değerini döndürür.

  • Toplanan tüm sayılar tam sayıysa ve toplam sonuç taşmıyorsa 64 bitlik bir tam sayı döndürür. Aksi takdirde, sonuç bir çift olarak döndürülür. Toplanan tüm değerler tam sayı olsa bile, 64 bit imzalı bir tam sayı içine sığmıyorsa sonucun çift sayı olarak döndürüleceğini unutmayın. Böyle bir durumda, döndürülen değer kesinliği kaybeder.

  • Alt akış gerçekleştiğinde, kayan nokta toplaması belirli bir yöntem değildir. Bu, temel değerlerde herhangi bir değişiklik yapmadan aynı sorguyu tekrar tekrar çalıştırmanın, her seferinde biraz farklı sonuçlar doğurabileceği anlamına gelir. Böyle durumlarda değerler, tam sayı ve kayan nokta sayıları olarak depolanmalıdır.

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

object (FieldReference)

Toplama yapılacak alan.

ORT

İstenen alanın değerlerinin ortalaması.

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

  • Toplam değerler NaN içeriyorsa NaN değerini döndürür. Sonsuzluk matematiği, IEEE-754 standartlarına uygundur.

  • Toplam değer kümesi 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 yapılacak alan.

AggregationResult

Firestore toplama sorgusundaki tek bir paketin sonucudur.

Her sonuç için farklı alanlar bulunabilen doküman sorgularının aksine, aggregateFields anahtarları, toplama sorgusundaki tüm sonuçlar için aynıdır.

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şte toplama işlevine atanan alias değeridir ve bu haritanın boyutu, sorgudaki toplama işlevlerinin sayısına eşittir.

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