Uma consulta de agregação processa os dados de várias entidades indexadas para retornar um único valor de resumo. O Firestore no modo Datastore é compatível com as seguintes consultas de agregação:
count()
sum()
avg()
As consultas de agregação simplificam o código do aplicativo e custam menos do que buscar cada entidade para processamento. Confira nesta página como usar as consultas de agregação.
Agregação count()
Use a agregação count()
para retornar o número total de entidades indexadas que correspondem a uma determinada consulta. Por exemplo, essa agregação count()
retorna o
número total de entidades em um tipo.
Java
Python
Go
aggregationCountQuery := datastore.NewQuery("Task"). NewAggregationQuery(). WithCount("total_tasks") countResults, err := client.RunAggregationQuery(ctx, aggregationCountQuery) count := countResults["total_tasks"] countValue := count.(*datastorepb.Value) fmt.Printf("Number of results from query: %d\n", countValue.GetIntegerValue())
GQL
AGGREGATE COUNT(*) AS total OVER ( SELECT * AS total FROM tasks )
O GQL é compatível com uma forma simplificada de consultas count()
:
SELECT COUNT(*) AS total FROM tasks
Este exemplo usa um alias opcional de total
.
No formato simplificado, há suporte apenas para cláusulas FROM
e WHERE
. Consulte a referência do GQL para mais informações.
A agregação count()
considera todos os filtros na consulta e todas
as cláusulas limit
. Por exemplo, a agregação a seguir retorna uma contagem do
número de entidades que correspondem aos filtros fornecidos.
Java
Python
Go
aggregationCountQuery := datastore.NewQuery("Task"). FilterField("done", "=", true). NewAggregationQuery(). WithCount("total_tasks_done") countResults, err := client.RunAggregationQuery(ctx, aggregationCountQuery) count := countResults["total_tasks_done"] countValue := count.(*datastorepb.Value) fmt.Printf("Number of results from query: %d\n", countValue.GetIntegerValue())
GQL
AGGREGATE COUNT(*) OVER ( SELECT * FROM tasks WHERE is_done = false AND tag = 'house')
O GQL é compatível com uma forma simplificada de consultas count()
:
SELECT COUNT(*) AS total FROM tasks WHERE is_done = false AND tag = 'house'
Este exemplo usa um alias opcional de total
.
No formato simplificado, há suporte apenas para cláusulas
FROM
e WHERE
. Consulte a referência do GQL para mais informações.
Este exemplo mostra como contar até um determinado valor. É possível usar esse método, por exemplo, para interromper a contagem de um determinado número e informar aos usuários que ele foi excedido.
Java
Python
Go
aggregationCountQuery := datastore.NewQuery("Task"). Limit(2). NewAggregationQuery(). WithCount("at_least") countResults, err := client.RunAggregationQuery(ctx, aggregationCountQuery) count := countResults["at_least"] countValue := count.(*datastorepb.Value) fmt.Printf("We have at least %d tasks\n", countValue.GetIntegerValue())
GQL
AGGREGATE COUNT_UP_TO(1000) OVER ( SELECT * FROM tasks WHERE is_done = false)
O GQL é compatível com uma forma simplificada de consultas count_up_to()
:
SELECT COUNT_UP_TO(1000) AS total FROM tasks WHERE is_done = false AND tag = 'house'
Este exemplo usa um alias opcional de total
.
No formato simplificado, há suporte apenas para cláusulas
FROM
e WHERE
. Consulte a referência do GQL para mais informações.
Agregação sum()
Use a agregação sum()
para retornar a soma total dos valores numéricos que correspondem a uma determinada consulta. Por exemplo, a seguinte agregação sum()
retorna a soma total dos valores numéricos da propriedade especificada das
entidades do tipo indicado:
Java
Python
Go
aggregationSumQuery := datastore.NewQuery("Task"). NewAggregationQuery(). WithSum("hours", "total_hours") sumResults, err := client.RunAggregationQuery(ctx, aggregationSumQuery) sum := sumResults["total_hours"] sumValue := sum.(*datastorepb.Value) fmt.Printf("Sum of results from query: %d\n", sumValue.GetIntegerValue())
GQL
AGGREGATE SUM(hours) AS total_hours OVER ( SELECT * FROM tasks )
O GQL é compatível com uma forma simplificada de consultas sum()
:
SELECT SUM(hours) AS total_hours FROM tasks
Este exemplo usa um alias opcional de total_hours
.
No formato simplificado, há suporte apenas para cláusulas FROM
e WHERE
. Consulte a referência do GQL para mais informações.
A agregação sum()
considera todos os filtros na consulta e todas
as cláusulas limit
. Por exemplo, a agregação a seguir retorna uma soma da propriedade especificada com um valor numérico em entidades que correspondem aos filtros fornecidos.
Java
Python
Esta consulta requer um índice como:
- kind: Task properties: - name: done - name: hours
Go
aggregationSumQuery := datastore.NewQuery("Task"). FilterField("done", "=", false). FilterField("tag", "=", "house"). NewAggregationQuery(). WithSum("hours", "total_hours") sumResults, err := client.RunAggregationQuery(ctx, aggregationSumQuery) sum := sumResults["total_hours"] sumValue := sum.(*datastorepb.Value) fmt.Printf("Sum of results from query: %d\n", sumValue.GetIntegerValue())
GQL
AGGREGATE SUM(hours) AS total_hours OVER ( SELECT * FROM tasks WHERE is_done = false AND tag = 'house' )
O GQL é compatível com uma forma simplificada de consultas sum()
:
SELECT SUM(hours) AS total_hours FROM tasks WHERE is_done = false AND tag = 'house'
Este exemplo usa um alias opcional de total_hours
.
No formato simplificado, há suporte apenas para cláusulas FROM
e WHERE
. Consulte a referência do GQL para mais informações.
Agregação avg()
Use a agregação avg()
para retornar a média dos valores numéricos que correspondem a uma determinada consulta. Por exemplo, a agregação avg()
a seguir retorna a média aritmética
da propriedade especificada com base nos valores de propriedade numérica das entidades
que correspondem à consulta:
Java
Python
Go
aggregationAvgQuery := datastore.NewQuery("Task"). NewAggregationQuery(). WithAvg("hours", "avg_hours") avgResults, err := client.RunAggregationQuery(ctx, aggregationAvgQuery) avg := avgResults["avg_hours"] avgValue := avg.(*datastorepb.Value) fmt.Printf("average hours: %f\n", avgValue.GetDoubleValue())
GQL
AGGREGATE AVG(hours) as avg_hours OVER ( SELECT * FROM tasks )
O GQL é compatível com uma forma simplificada de consultas avg()
:
SELECT AVG(hours) as avg_hours
Este exemplo usa um alias opcional de avg_hours
.
No formato simplificado, há suporte apenas para cláusulas FROM
e WHERE
. Consulte a referência do GQL para mais informações.
A agregação avg()
considera todos os filtros na consulta e todas
as cláusulas limit
. Por exemplo, a agregação a seguir retorna a média aritmética da propriedade especificada com base nos valores de propriedade numérica das entidades que correspondem aos filtros de consulta.
Java
Python
Esta consulta requer um índice como:
- kind: Task properties: - name: done - name: hours
Go
aggregationAvgQuery := datastore.NewQuery("Task"). FilterField("done", "=", false). FilterField("tag", "=", "house"). NewAggregationQuery(). WithAvg("hours", "avg_hours") avgResults, err := client.RunAggregationQuery(ctx, aggregationAvgQuery) avg := avgResults["avg_hours"] avgValue := avg.(*datastorepb.Value) fmt.Printf("average hours: %f\n", avgValue.GetDoubleValue())
GQL
AGGREGATE AVG(hours) as avg_hours OVER ( SELECT * FROM tasks WHERE is_done = false AND tag = 'house' )
O GQL é compatível com uma forma simplificada de consultas avg()
:
SELECT AVG(hours) as avg_hours FROM tasks WHERE is_done = false AND tag = 'house'
Este exemplo usa um alias opcional de avg_hours
.
No formato simplificado, há suporte apenas para cláusulas FROM
e WHERE
. Consulte a referência do GQL para mais informações.
Calcular várias agregações em uma consulta
É possível combinar várias agregações em um único pipeline de agregação. Isso pode reduzir o número de leituras de índice necessárias. Se a consulta incluir agregações em vários campos, um índice composto será exigido, e cada cálculo de agregação incluirá apenas as entidades que contêm todos os campos usados por cada agregação.
O exemplo a seguir executa várias agregações em uma única consulta de agregação:
Java
Python
Go
aggregationQuery := datastore.NewQuery("Task"). NewAggregationQuery(). WithCount("total_tasks"). WithSum("hours", "total_hours"). WithAvg("hours", "avg_hours") Results, err := client.RunAggregationQuery(ctx, aggregationQuery) fmt.Printf("Number of results from query: %d\n", Results["total_tasks"].(*datastorepb.Value).GetIntegerValue()) fmt.Printf("Sum of results from query: %d\n", Results["total_hours"].(*datastorepb.Value).GetIntegerValue()) fmt.Printf("Avg of results from query: %f\n", Results["avg_hours"].(*datastorepb.Value).GetDoubleValue())
GQL
AGGREGATE SUM(hours) AS total_hours, COUNT(*) AS total_tasks OVER ( SELECT * FROM tasks WHERE is_done = false AND tag = 'house' )
O GQL é compatível com uma forma simplificada de consultas de agregação:
SELECT SUM(hours) AS total_hours, COUNT(*) AS total_tasks FROM tasks WHERE is_done = false AND tag = 'house'
Neste exemplo, os aliases opcionais de total_hours
e total_tasks
são usados.
No formato simplificado, há suporte apenas para cláusulas FROM
e WHERE
. Consulte a referência do GQL para mais informações.
Consultas com agregação múltipla incluem apenas as entidades que contêm todas as propriedades em cada agregação. Isso pode levar a resultados diferentes da execução de cada agregação separadamente.
Comportamento e limitações
Ao trabalhar com consultas de agregação, considere os seguintes comportamentos e limitações:
- A consulta fornecida à agregação precisa atender às restrições de consultas.
Se uma consulta de agregação não puder ser resolvida em até 60 segundos, ela retornará um erro
DEADLINE_EXCEEDED
. O desempenho depende da configuração do índice e do tamanho do conjunto de dados.Se a operação não puder ser concluída dentro do prazo de 60 segundos, uma alternativa possível é usar cursors para mesclar várias agregações.
As consultas de agregação leem a partir de entradas de índice e incluem apenas propriedades indexadas no cálculo.
Adicionar uma cláusula
OrderBy
à consulta limita a agregação às entidades em que a propriedade de ordenação existe.Em GQL, a forma simplificada não é compatível com cláusulas
ORDER BY
,LIMIT
ouOFFSET
.Em uma consulta de projeção, é possível agregar dados apenas das propriedades na projeção. Por exemplo, na consulta GQL
SELECT a, b FROM k WHERE c = 1
, é possível agregar dados somente entrea
oub
.Uma agregação
count()
não elimina a duplicação de entidades com propriedades de matriz. Cada valor de matriz que corresponde à consulta adiciona um à contagem.Para agregações
sum()
eavg()
, os valores não numéricos são ignorados. A agregaçãosum()
eavg()
considera apenas valores inteiros, valores numéricos de ponto flutuante e carimbos de data/hora. Os carimbos de data/hora são convertidos em valores inteiros em microssegundos parasum()
,avg()
e projeções.Ao combinar várias agregações em uma única consulta,
sum()
eavg()
ignoram valores não numéricos, enquantocount()
inclui valores não numéricos.Se você combinar agregações que estejam em propriedades diferentes, o cálculo vai incluir apenas as entidades que contêm todas essas propriedades. Isso pode levar a resultados diferentes da execução de cada agregação separadamente.
Preços
Os preços das consultas de agregação count()
, sum()
e avg()
dependem do
número de entradas de índice verificadas durante a operação. Você será cobrado por uma
leitura de entidade para até 1.000 entradas de índice correspondentes. As entradas de índice subsequentes
correspondem a unidades de leitura adicionais de custo. Há um custo mínimo de uma unidade de leitura
para cada consulta. Para informações
sobre preços, consulte Preços do Firestore no modo Datastore.
Quando você combina várias agregações em uma única consulta, o mesmo índice é usado para cada agregação e uma única verificação nos dados é executada. Isso pode ajudar a reduzir o número de verificações de índice e leituras faturadas em comparação com a execução de cada agregação separadamente. No entanto, consultas com várias agregações incluem apenas as entidades que contêm todas essas propriedades. Isso pode levar a resultados diferentes da execução de cada agregação separadamente.
A seguir
- Saiba mais sobre consultas.
- Saiba mais sobre as práticas recomendadas para o Firestore no modo Datastore.