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 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. 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 oferece suporte a uma forma simplificada de consultas count()
:
SELECT COUNT(*) AS total FROM tasks
Neste exemplo, usamos 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 oferece suporte a 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 é compatível apenas com FROM
e WHERE
cláusulas. Consulte a referência sobre 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 aceita 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 é compatível apenas com FROM
e WHERE
cláusulas. 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 aceita uma forma simplificada de consultas sum()
:
SELECT SUM(hours) AS total_hours FROM tasks
Neste exemplo, usamos 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 aceita uma forma simplificada de consultas sum()
:
SELECT SUM(hours) AS total_hours FROM tasks WHERE is_done = false AND tag = 'house'
Neste exemplo, usamos um alias opcional de total_hours
.
O formulário simplificado é compatível apenas com FROM
e WHERE
cláusulas. Consulte a referência sobre GQL para mais informações.
Agregação de avg()
Use a agregação avg()
para retornar a média dos valores numéricos que
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 oferece suporte a uma forma simplificada de consultas avg()
:
SELECT AVG(hours) as avg_hours
Neste exemplo, usamos 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 oferece suporte a uma forma simplificada de consultas avg()
:
SELECT AVG(hours) as avg_hours FROM tasks WHERE is_done = false AND tag = 'house'
Neste exemplo, usamos 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.
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, ela vai precisar de um índice composto, e cada cálculo de agregação vai 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 aceita um formato 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 é compatível apenas com FROM
e WHERE
cláusulas. Consulte a referência sobre GQL para mais informações.
Consultas com agregação múltipla incluem apenas as entidades que 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 ao restrições nas 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 às entidades em que há a propriedade de classificação.Em GQL, o formato simplificado não suporta 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 elimina a duplicação de entidades 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 da 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. Você vai receber uma cobrança
leitura de entidade para até 1.000 entradas de índice correspondentes. Entradas de índice subsequentes
unidades de leitura adicionais com custo correspondente. Há o 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 índices verifica e lê faturas 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 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 do Firestore no modo Datastore.