Method: projects.databases.documents.runAggregationQuery

Запускает запрос агрегирования.

Вместо того, чтобы создавать результаты Document , такие как Firestore.RunQuery , этот API позволяет запускать агрегацию для создания серии AggregationResult на стороне сервера.

Пример высокого уровня: 

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

HTTP-запрос

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

URL-адрес использует синтаксис транскодирования gRPC .

Параметры пути

Параметры
parent

string

Необходимый. Имя родительского ресурса. В формате: projects/{projectId}/databases/{databaseId}/documents или projects/{projectId}/databases/{databaseId}/documents/{document_path} . Например: projects/my-project/databases/my-database/documents или projects/my-project/databases/my-database/documents/chatrooms/my-chatroom

Тело запроса

Тело запроса содержит данные следующей структуры:

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.
}
Поля
explainOptions

object ( ExplainOptions )

Необязательный. Объясните варианты запроса. Если установлено, будет возвращена дополнительная статистика запросов. В противном случае будут возвращены только результаты запроса.

Поле объединения query_type . Запрос для выполнения. query_type может быть только одним из следующих:
structuredAggregationQuery

object ( StructuredAggregationQuery )

Агрегирующий запрос.

Объединённое поле consistency_selector . Режим согласованности для запроса по умолчанию — строгая согласованность. consistency_selector может быть только одним из следующих:
transaction

string ( bytes format)

Запустите агрегацию в уже активной транзакции.

Значением здесь является непрозрачный идентификатор транзакции, в которой будет выполнен запрос.

Строка в кодировке Base64.

newTransaction

object ( TransactionOptions )

Запускает новую транзакцию как часть запроса, по умолчанию доступную только для чтения.

Новый идентификатор транзакции будет возвращен в качестве первого ответа в потоке.

readTime

string ( Timestamp format)

Выполняет запрос в заданную временную метку.

Это должна быть метка времени с точностью до микросекунды за последний час или, если включено восстановление на момент времени, дополнительно может быть метка времени с точностью до целой минуты за последние 7 дней.

Временная метка в формате RFC3339 UTC «Зулу» с наносекундным разрешением и до девяти дробных цифр. Примеры: "2014-10-02T15:01:23Z" и "2014-10-02T15:01:23.045123456Z" .

Тело ответа

Ответ на Firestore.RunAggregationQuery .

В случае успеха тело ответа содержит данные следующей структуры:

JSON-представление 
{
  "result": {
    object (AggregationResult)
  },
  "transaction": string,
  "readTime": string,
  "explainMetrics": {
    object (ExplainMetrics)
  }
}
Поля
result

object ( AggregationResult )

Единый результат агрегирования.

Не отображается при сообщении о частичном прогрессе.

transaction

string ( bytes format)

Транзакция, которая была запущена в рамках этого запроса.

Присутствует только в первом ответе, когда запрос запрашивает начало новой транзакции.

Строка в кодировке Base64.

readTime

string ( Timestamp format)

Время, за которое был вычислен совокупный результат. Оно всегда монотонно возрастает; в этом случае предыдущий AggregationResult в потоке результатов гарантированно не изменится между их readTime и этим.

Если запрос не возвращает результатов, будет отправлен ответ с readTime и без result , что представляет собой время выполнения запроса.

Временная метка в формате RFC3339 UTC «Зулу» с наносекундным разрешением и до девяти дробных цифр. Примеры: "2014-10-02T15:01:23Z" и "2014-10-02T15:01:23.045123456Z" .

explainMetrics

object ( ExplainMetrics )

Метрики объяснения запроса. Он присутствует только в том случае, если указан RunAggregationQueryRequest.explain_options , и отправляется только один раз вместе с последним ответом в потоке.

Области авторизации

Требуется одна из следующих областей OAuth:

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

Для получения дополнительной информации см. Обзор аутентификации .

Структурированный запрос агрегации

Запрос Firestore для выполнения агрегации через StructuredQuery .

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.
}
Поля
aggregations[]

object ( Aggregation )

Необязательный. Серия агрегатов, применяемых к результатам structuredQuery .

Требует:

  • Минимум одно и максимум пять агрегатов на запрос.
Поле объединения query_type . Базовый запрос для агрегирования. query_type может быть только одним из следующих:
structuredQuery

object ( StructuredQuery )

Вложенный структурированный запрос.

Агрегация

Определяет агрегацию, которая дает один результат.

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.
}
Поля
alias

string

Необязательный. Необязательное имя поля, в котором будет сохранен результат агрегации.

Если оно не указано, Firestore выберет имя по умолчанию в формате field_<incremental_id++> . Например:

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

становится:

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

Требует:

  • Должен быть уникальным для всех псевдонимов агрегации.
  • Соответствуйте ограничениям document field name .
Полевой operator Союза. Обязательный тип выполняемой агрегации. operator может быть только одним из следующих:
count

object ( Count )

Счетный агрегатор.

sum

object ( Sum )

Суммарный агрегатор.

avg

object ( Avg )

Средний агрегатор.

Считать

Количество документов, соответствующих запросу.

Функция агрегирования COUNT(*) работает со всем документом, поэтому не требует ссылки на поле.

JSON-представление 
{
  "upTo": string
}
Поля
upTo

string ( Int64Value format)

Необязательный. Необязательное ограничение на максимальное количество документов для подсчета.

Это дает возможность установить верхнюю границу количества сканируемых документов, ограничивая задержку и стоимость.

Unspecified интерпретируется как отсутствие ограничений.

Пример высокого уровня:

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

Требует:

  • Должно быть больше нуля, если оно присутствует.

Сумма

Сумма значений запрошенного поля.

  • Будут агрегироваться только числовые значения. Все нечисловые значения, включая NULL пропускаются.

  • Если агрегированные значения содержат NaN , возвращается NaN . Математика Infinity соответствует стандартам IEEE-754.

  • Если набор агрегированных значений пуст, возвращается 0.

  • Возвращает 64-битное целое число, если все агрегированные числа являются целыми числами и результат суммы не переполняется. В противном случае результат возвращается как двойной. Обратите внимание: даже если все агрегированные значения являются целыми числами, результат возвращается как двойное число, если он не может поместиться в 64-битное целое число со знаком. В этом случае возвращаемое значение потеряет точность.

  • Когда происходит опустошение, агрегирование с плавающей запятой является недетерминированным. Это означает, что повторный запуск одного и того же запроса без каких-либо изменений базовых значений может каждый раз давать немного разные результаты. В таких случаях значения следует хранить как целые числа, а не числа с плавающей запятой.

JSON-представление 
{
  "field": {
    object (FieldReference)
  }
}
Поля
field

object ( FieldReference )

Поле для агрегирования.

Среднее

Среднее значение запрошенного поля.

  • Будут агрегироваться только числовые значения. Все нечисловые значения, включая NULL пропускаются.

  • Если агрегированные значения содержат NaN , возвращается NaN . Математика Infinity соответствует стандартам IEEE-754.

  • Если набор агрегированных значений пуст, возвращается NULL .

  • Всегда возвращает результат как двойной.

JSON-представление 
{
  "field": {
    object (FieldReference)
  }
}
Поля
field

object ( FieldReference )

Поле для агрегирования.

Результат агрегации

Результат одного сегмента из запроса агрегации Firestore.

Ключи aggregateFields одинаковы для всех результатов в запросе агрегирования, в отличие от запросов документов, в которых для каждого результата могут присутствовать разные поля.

JSON-представление 
{
  "aggregateFields": {
    string: {
      object (Value)
    },
    ...
  }
}
Поля
aggregateFields

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

Результат функций агрегирования, например: COUNT(*) AS total_docs .

Ключом является alias , назначенный функции агрегации на входе, а размер этой карты равен количеству функций агрегации в запросе.

Объект, содержащий список пар "key": value . Пример: { "name": "wrench", "mass": "1.3kg", "count": "3" } .