Method: projects.databases.documents.runAggregationQuery

Uruchamia zapytanie agregacji.

Zamiast generować wyniki Document takie jak Firestore.RunQuery, ten interfejs API umożliwia przeprowadzenie agregacji w celu wygenerowania serii AggregationResult po stronie serwera.

Ogólny przykład:

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

Żądanie HTTP

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

Adres URL używa składni transkodowania gRPC.

Parametry ścieżki

Parametry
parent

string

Wymagane. Nazwa zasobu nadrzędnego. W formacie: projects/{projectId}/databases/{databaseId}/documents lub projects/{projectId}/databases/{databaseId}/documents/{document_path}. Na przykład: projects/my-project/databases/my-database/documents lub projects/my-project/databases/my-database/documents/chatrooms/my-chatroom

Treść żądania

Treść żądania zawiera dane o następującej strukturze:

Zapis 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.
}
Pola
explainOptions

object (ExplainOptions)

Opcjonalnie. Wyjaśnij opcje zapytania. Jeśli jest ustawione, zwracane są dodatkowe statystyki zapytań. W przeciwnym razie zwracane będą tylko wyniki zapytania.
Pole sumy query_type. Zapytanie do uruchomienia. query_type może mieć tylko jedną z tych wartości:
structuredAggregationQuery

object (StructuredAggregationQuery)

Zapytanie agregujące.
Pole sumy consistency_selector. Tryb spójności zapytania domyślnie ma silną spójność. consistency_selector może mieć tylko jedną z tych wartości:
transaction

string (bytes format)

Uruchom agregację w ramach już aktywnej transakcji.

Wartość w tym miejscu to nieprzejrzysty identyfikator transakcji, w której ma zostać wykonane zapytanie.

Ciąg zakodowany w formacie base64.
newTransaction

object (TransactionOptions)

Uruchamia nową transakcję w ramach zapytania z domyślnym ustawieniem „tylko do odczytu”.

Nowy identyfikator transakcji zostanie zwrócony jako pierwsza odpowiedź w strumieniu.
readTime

string (Timestamp format)

Wykonuje zapytanie o podanej sygnaturze czasowej.

Musi to być sygnatura czasowa z dokładnością do mikrosekundy z ostatniej godziny. Jeśli odzyskiwanie do określonego momentu jest włączone, może to być dodatkowo pełna sygnatura czasowa z ostatnich 7 dni.

Sygnatura czasowa w RFC3339 UTC „Zulu” z rozdzielczością nanosekundową i maksymalnie 9 cyframi po przecinku. Przykłady: "2014-10-02T15:01:23Z" i "2014-10-02T15:01:23.045123456Z".

Treść odpowiedzi

Odpowiedź dla: Firestore.RunAggregationQuery.

W przypadku powodzenia treść żądania zawiera dane o następującej strukturze:

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

object (AggregationResult)

Jeden wynik agregacji.

Nie występuje w przypadku raportowania częściowego postępu.
transaction

string (bytes format)

Transakcja rozpoczęta w ramach tego żądania.

Widoczny tylko w pierwszej odpowiedzi, gdy żądanie dotyczyło rozpoczęcia nowej transakcji.

Ciąg zakodowany w formacie base64.
readTime

string (Timestamp format)

Godzina obliczenia wyniku zagregowanego. Ta wartość jest zawsze monotonicznie rosnąca. w tym przypadku poprzedni wynik AggregationResult w strumieniu wyników nie zmieni się między readTime a tym.

Jeśli zapytanie nie zwróci żadnych wyników, zostanie wysłana odpowiedź z parametrem readTime i brakiem result. Wskazuje ona czas uruchomienia zapytania.

Sygnatura czasowa w RFC3339 UTC „Zulu” z rozdzielczością nanosekundową i maksymalnie 9 cyframi po przecinku. Przykłady: "2014-10-02T15:01:23Z" i "2014-10-02T15:01:23.045123456Z".
explainMetrics

object (ExplainMetrics)

Wskaźniki wyjaśnień zapytania. Ten parametr występuje tylko wtedy, gdy podano RunAggregationQueryRequest.explain_options i jest wysyłany tylko raz z ostatnią odpowiedzią w strumieniu.

Zakresy autoryzacji

Wymaga jednego z tych zakresów protokołu OAuth:

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

Więcej informacji znajdziesz w artykule o uwierzytelnianiu (w języku angielskim).

Zapytanie agregacji uporządkowanych danych

Zapytanie Firestore dotyczące uruchomienia agregacji w zasobniku StructuredQuery.

Zapis 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.
}
Pola
aggregations[]

object (Aggregation)

Opcjonalnie. Seria agregacji, które zostaną zastosowane do wyników funkcji structuredQuery.

Wymagane:

  • Od co najmniej 1 do 5 agregacji na zapytanie.
Pole sumy query_type. Podstawowe zapytanie do agregacji. query_type może mieć tylko jedną z tych wartości:
structuredQuery

object (StructuredQuery)

Zagnieżdżone uporządkowane zapytanie.

Agregacja

Definiuje agregację, która skutkuje jednym wynikiem.

Zapis 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.
}
Pola
alias

string

Opcjonalnie. Opcjonalna nazwa pola, w którym mają być przechowywane wynik agregacji.

Jeśli nie zostanie podana, Firestore wybierze nazwę domyślną w formacie field_<incremental_id++>. Przykład:

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

zmienia się w:

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

Wymagane:

  • Musi być niepowtarzalna wśród wszystkich aliasów agregacji.
  • Zachowaj zgodność z ograniczeniami document field name.
Pole sumy operator. Wymagany typ agregacji do wykonania. operator może mieć tylko jedną z tych wartości:
count

object (Count)

Agregator liczb.
sum

object (Sum)

Agregator sum.
avg

object (Avg)

Przeciętny agregator.

Liczba

Liczba dokumentów pasujących do zapytania.

Funkcja agregacji COUNT(*) działa w całym dokumencie, więc nie wymaga odwołania do pola.

Zapis JSON 
{
  "upTo": string
}
Pola
upTo

string (Int64Value format)

Opcjonalnie. Opcjonalne ograniczenie maksymalnej liczby dokumentów do zliczania.

Umożliwia to ustawienie górnej granicy liczby dokumentów do skanowania, co pozwala ograniczyć czas oczekiwania i koszty.

Wartość nieokreślona jest interpretowana jako brak zakresu.

Ogólny przykład:

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

Wymagane:

  • Wartość musi być większa od zera.

Suma

Suma wartości żądanego pola.

  • Agregowane będą tylko wartości liczbowe. Wszystkie wartości nieliczbowe, w tym NULL, są pominięte.

  • Jeśli zagregowane wartości zawierają wartość NaN, funkcja zwraca NaN. Funkcja matematyki Infinity jest zgodna ze standardami IEEE-754.

  • Jeśli zbiór zagregowanych wartości jest pusty, zwraca 0.

  • Zwraca 64-bitową liczbę całkowitą, jeśli wszystkie zagregowane liczby są liczbami całkowitymi, a wynik sumy nie przekroczy wartości. W przeciwnym razie wynik jest liczbą zmiennoprzecinkową. Nawet jeśli wszystkie zagregowane wartości są liczbami całkowitymi, wynik jest zwracany jako liczba zmiennoprzecinkowa, jeśli nie mieści się w 64-bitowej liczbie znaków ze znakiem. W takim przypadku zwracana wartość utraci precyzję.

  • Gdy występuje niedopełnienie, agregacja zmiennoprzecinkowa jest niedeterministyczna. Oznacza to, że wielokrotne wykonywanie tego samego zapytania bez zmian w wartościach może za każdym razem dawać nieco inne wyniki. W takich przypadkach wartości powinny być przechowywane w postaci liczb całkowitych zamiast liczb zmiennoprzecinkowych.

Zapis JSON 
{
  "field": {
    object (FieldReference)
  }
}
Pola
field

object (FieldReference)

Pole do agregacji.

Średnio

Średnia wartości żądanego pola.

  • Agregowane będą tylko wartości liczbowe. Wszystkie wartości nieliczbowe, w tym NULL, są pominięte.

  • Jeśli zagregowane wartości zawierają wartość NaN, funkcja zwraca NaN. Funkcja matematyki Infinity jest zgodna ze standardami IEEE-754.

  • Jeśli zbiór zagregowanych wartości jest pusty, zwraca NULL.

  • Zawsze zwraca wynik w postaci liczby zmiennoprzecinkowej.

Zapis JSON 
{
  "field": {
    object (FieldReference)
  }
}
Pola
field

object (FieldReference)

Pole do agregacji.

Wynik agregacji

Wynik pojedynczego zasobnika z zapytania agregacji Firestore.

Klucze funkcji aggregateFields są takie same w przypadku wszystkich wyników w zapytaniu agregowanym. W odróżnieniu od zapytań dokumentów, w których przypadku każdy wynik może zawierać inne pola.

Zapis JSON 
{
  "aggregateFields": {
    string: {
      object (Value)
    },
    ...
  }
}
Pola
aggregateFields

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

Wynik funkcji agregacji, np. COUNT(*) AS total_docs.

Klucz to element alias przypisany do funkcji agregacji na danych wejściowych, a rozmiar tej mapy jest równa liczbie funkcji agregacji w zapytaniu.

Obiekt zawierający listę par "key": value. Przykład: { "name": "wrench", "mass": "1.3kg", "count": "3" }.