Uma consulta de agregação processa os dados de várias entidades indexadas para retornam um único valor de resumo. O Firestore no modo Datastore é compatível com os 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. Leia esta página para saber como usar as consultas de agregação.
Agregação de 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 de 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 aceita uma forma simplificada de consultas count()
:
SELECT COUNT(*) AS total FROM tasks
Este exemplo usa um alias opcional de total
.
O formulário simplificado é compatível apenas com FROM
e WHERE
cláusulas. Consulte a referência sobre 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 de
o 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 aceita uma forma simplificada de consultas count()
:
SELECT COUNT(*) AS total FROM tasks WHERE is_done = false AND tag = 'house'
Neste exemplo, usamos um alias opcional de total
.
O formulário simplificado aceita apenas cláusulas FROM
e
WHERE
. Consulte a referência do GQL para mais informações.
Este exemplo mostra como contar até um determinado valor. Você pode usar isso para, por exemplo, parar de contar em um determinado número e informar aos usuários que eles ultrapassaram esse número.
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 oferece suporte a uma forma simplificada de consultas count_up_to()
:
SELECT COUNT_UP_TO(1000) AS total FROM tasks WHERE is_done = false AND tag = 'house'
Neste exemplo, usamos um alias opcional de total
.
O formulário simplificado aceita apenas cláusulas FROM
e
WHERE
. Consulte a referência sobre GQL para mais informações.
Agregação de sum()
Use a agregação sum()
para retornar a soma total dos valores numéricos correspondentes.
em uma determinada consulta. Por exemplo, a agregação sum()
a seguir retorna a soma total dos valores numéricos da propriedade especificada de
entidades do tipo especificado:
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 oferece suporte a uma forma simplificada de consultas sum()
:
SELECT SUM(hours) AS total_hours FROM tasks
Este exemplo usa um alias opcional de total_hours
.
O formulário simplificado aceita apenas cláusulas FROM
e WHERE
. Consulte a referência sobre 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 de
a propriedade especificada com um valor numérico em entidades que correspondem à determinada
filtros.
Java
Python
Essa 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 oferece suporte a 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
.
O formulário simplificado aceita apenas cláusulas FROM
e WHERE
. Consulte a referência do GQL para mais informações.
Agregação de avg()
Use a agregação avg()
para retornar a média dos valores numéricos que
correspondem a uma determinada consulta. Por exemplo, o avg()
a seguir
agregação retorna o valor aritmético
média da propriedade especificada a partir dos valores de propriedade numéricos 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 aceita uma forma simplificada de consultas avg()
:
SELECT AVG(hours) as avg_hours
Este exemplo usa um alias opcional de avg_hours
.
O formulário simplificado é compatível apenas com FROM
e WHERE
cláusulas. Consulte a referência sobre 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 o valor aritmético
média da propriedade especificada a partir dos valores de propriedade numéricos das entidades que
correspondem aos filtros de consulta.
Java
Python
Essa 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 aceita 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
.
O formulário simplificado aceita apenas cláusulas FROM
e WHERE
. Consulte a referência sobre 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, a consulta exige um índice composto, e cada agregação cálculo inclui apenas as entidades que contêm todos os campos usados pelo 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 oferece suporte a um formulário simplificado para consultas de agregação:
SELECT SUM(hours) AS total_hours, COUNT(*) AS total_tasks FROM tasks WHERE is_done = false AND tag = 'house'
Este exemplo usa os aliases opcionais de total_hours
e total_tasks
.
O formulário simplificado aceita apenas cláusulas FROM
e WHERE
. Consulte a referência sobre GQL para mais informações.
Consultas com várias agregações 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 que você fornece à agregação precisa atender às restrições em consultas.
Se uma consulta de agregação não puder ser resolvida em até 60 segundos, ela retornará um
DEADLINE_EXCEEDED
erro. 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 cursores para mesclar várias agregações.
As consultas de agregação leem as entradas de índice e incluem apenas propriedades indexadas no cálculo.
Adicionar uma cláusula
OrderBy
à consulta limita a agregação ao entidades em que a propriedade de classificação existe.No GQL, o formulário simplificado não oferece suporte a cláusulas
ORDER BY
,LIMIT
ouOFFSET
.Em uma consulta de projeção, só é possível agregar dados das propriedades. na projeção. Por exemplo, na consulta GQL
SELECT a, b FROM k WHERE c = 1
, só é possível agregar dados entrea
oub
.Uma agregação
count()
não remove entidades duplicadas com propriedades de matriz. Cada valor de matriz que corresponde à consulta adiciona um à contagem.Nas agregações
sum()
eavg()
, os valores não numéricos são ignorados.sum()
e a agregaçãoavg()
considera apenas valores inteiros, valores numéricos de ponto flutuante e carimbos de data/hora. As marcações de tempo são convertido em valores inteiros de 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 estão em propriedades diferentes, o cálculo inclui apenas as entidades que contêm todas essas propriedades. Isso pode levar a resultados diferentes com a execução de cada agregação separadamente.
Preços
O preço das consultas de agregação count()
, sum()
e avg()
depende
o número de entradas de índice verificadas durante a operação. É cobrada uma
leitura de entidade para até 1.000 entradas de índice correspondentes. As entradas de índice subsequentes
corresponderam a unidades de leitura adicionais. Há um custo mínimo de uma unidade de leitura
para cada consulta. Para preços
informações, consulte Preços do Firestore no modo Datastore.
Se você combinar várias agregações em uma única consulta, ela usará a mesma para cada agregação e faz uma única verificação dos dados. Isso pode ajudar a reduzir o número de leituras e verificações de índice cobrado em comparação com a execução de cada agregação separadamente. No entanto, as 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.