Method: projects.databases.documents.runAggregationQuery

Uruchamia zapytanie agregacji.

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

Przykład wysokiego poziomu:

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

To pole jest 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 skonfigurowana, zwracane są dodatkowe statystyki zapytań. W przeciwnym razie zwracane będą tylko wyniki zapytania.
Pole sumy query_type. Zapytanie do wykonania. query_type może być tylko jedną z tych wartości:
structuredAggregationQuery

object (StructuredAggregationQuery)

Zapytanie obejmujące agregację.
Pole sumy consistency_selector. Tryb spójności zapytania domyślnie ustawia silną spójność. consistency_selector może być tylko jedną z tych wartości:
transaction

string (bytes format)

Uruchom agregację w ramach już aktywnej transakcji.

Wartością w tym polu jest nieprzejrzysty identyfikator transakcji, w ramach którego zostanie wykonane zapytanie.

Ciąg zakodowany w standardzie base64.
newTransaction

object (TransactionOptions)

Rozpoczyna nową transakcję w ramach zapytania. Domyślnie jest on ustawiony jako 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 precyzji określona w mikrosekundach z ostatniej godziny lub jeśli włączona jest funkcja odzyskiwania do określonego momentu, może to być dodatkowo sygnatura czasowa obejmująca całą minutę z ostatnich 7 dni.

Sygnatura czasowa w formacie „Zulu” RFC3339 UTC 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ź dotycząca: 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.

Brak w przypadku raportowania częściowego postępu.
transaction

string (bytes format)

Transakcja rozpoczęta w ramach tego żądania.

Występuje tylko w pierwszej odpowiedzi, gdy żądanie zażądało rozpoczęcia nowej transakcji.

Ciąg zakodowany w standardzie base64.
readTime

string (Timestamp format)

Czas obliczenia wyniku zbiorczego. Ta wartość jest zawsze rosnąca monotonicznie. W tym przypadku poprzednia wartość AggregationResult w strumieniu wyników na pewno nie zmieniła się między wartością readTime a tym parametrem.

Jeśli zapytanie nie zwróci żadnych wyników, zostanie wysłana odpowiedź z parametrem readTime i żadnym atrybutem result, która określa czas wykonania zapytania.

Sygnatura czasowa w formacie „Zulu” RFC3339 UTC 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)

Zapytanie dotyczące wskaźników. Jest ona obecna tylko wtedy, gdy podano RunAggregationQueryRequest.explain_options i jest wysyłana tylko raz z ostatnią odpowiedzią w strumieniu.

Zakresy autoryzacji

Wymaga jednego z tych zakresów OAuth:

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

Więcej informacji znajdziesz w artykule Omówienie uwierzytelniania.

StructuredAggregationQuery

Zapytanie Firestore dotyczące uruchomienia agregacji w obiekcie 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 do zastosowania do wyników funkcji structuredQuery.

Wymagane:

  • Od 1 do 5 agregacji na zapytanie.
Pole sumy query_type. Podstawowe zapytanie, na podstawie którego następuje agregacja. query_type może być tylko jedną z tych wartości:
structuredQuery

object (StructuredQuery)

Zagnieżdżone uporządkowane zapytanie.

Agregacja

Definiuje agregację, która daje jeden wynik.

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 ma być przechowywany wynik agregacji.

Jeśli jej nie podasz, Firestore wybierze nazwę domyślną w formacie field_<incremental_id++>. Na 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.
  • Przestrzegaj ograniczeń (document field name).
Pole sumy operator. Wymagany typ agregacji do przeprowadzenia. operator może być tylko jedną z tych wartości:
count

object (Count)

Agregator liczników.
sum

object (Sum)

Agregator sum.
avg

object (Avg)

Przeciętny pośrednik.

Liczba

Liczba dokumentów pasujących do zapytania.

Funkcja agregacji COUNT(*) działa w obrębie całego dokumentu, 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 zliczenia.

Pozwala to ustawić górną granicę liczby dokumentów do skanowania, ograniczając czas oczekiwania i koszty.

Wartość nieokreślona jest interpretowana jako brak ograniczeń.

Przykład wysokiego poziomu:

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

Wymagane:

  • Jeśli występuje, wartość musi być większa niż 0.

Suma

Suma wartości żądanego pola.

  • Agregowane zostaną tylko wartości liczbowe. Wszystkie wartości nieliczbowe, w tym NULL, są pomijane.

  • Jeśli wartości zbiorcze zawierają NaN, zwraca NaN. Infinity Math jest zgodny ze standardami IEEE-754.

  • Jeśli zestaw wartości zagregowanych jest pusty, zwraca wartość 0.

  • Zwraca 64-bitową liczbę całkowitą, jeśli wszystkie zagregowane liczby są liczbami całkowitymi, a wynik sumy nie przekracza. W przeciwnym razie wynik jest zwracany jako liczba zmiennoprzecinkowa. Pamiętaj, że nawet jeśli wszystkie zagregowane wartości są liczbami całkowitymi, to wynik jest zwracany jako liczba zmiennoprzecinkowa, jeśli nie mieści się on w 64-bitowej ze znakiem. W takim przypadku zwrócona wartość straci precyzję.

  • W takim przypadku agregacja liczb zmiennoprzecinkowych nie jest deterministyczna. Oznacza to, że wielokrotne wykonywanie tego samego zapytania bez wprowadzania zmian w wartościach bazowych może za każdym razem przynieść nieco inne wyniki. W takich przypadkach wartości należy przechowywać jako liczby całkowite zamiast liczb zmiennoprzecinkowych.

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

object (FieldReference)

Pole, na podstawie którego mają być agregowane dane.

Śr.

Średnia z wartości żądanego pola.

  • Agregowane zostaną tylko wartości liczbowe. Wszystkie wartości nieliczbowe, w tym NULL, są pomijane.

  • Jeśli wartości zbiorcze zawierają NaN, zwraca NaN. Infinity Math jest zgodny ze standardami IEEE-754.

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

  • Zawsze zwraca wynik jako liczbę zmiennoprzecinkową.

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

object (FieldReference)

Pole, na podstawie którego mają być agregowane dane.

AggregationResult

Wynik pojedynczego zasobnika z zapytania agregacji Firestore.

Klucze funkcji aggregateFields są takie same dla wszystkich wyników zapytania agregacji w przeciwieństwie do zapytań dotyczących dokumentów, które dla każdego wyniku mogą mieć 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 alias przypisany do funkcji agregacji na danych wejściowych, a rozmiar tej mapy jest równy liczbie funkcji agregacji w zapytaniu.

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