aggregate

aggregate()

Executa múltiplas operações estatísticas customizadas (count, sum, avg, min, max, distinct) em uma única chamada, otimizada para performance.

Sintaxe

await db.aggregate(operations: AggregateOperation[]): Promise<AggregateResult>

Parâmetros

operations: Array de operações de agregação

Estrutura de Operação:

{
  type: 'count' | 'sum' | 'avg' | 'min' | 'max' | 'distinct',
  field?: string,  // Obrigatório para sum, avg, min, max, distinct
  key?: string     // Opcional: chave específica para análise
}

Retorno

Objeto com chaves nomeadas baseadas no tipo e campo:

{
  [operationType_field]: any
}

Exemplos

Agregação Completa com Dados de Usuários

await db.set('user.123', { name: 'João', age: 25, money: 1000 });
await db.set('user.456', { name: 'Maria', age: 30, money: 1500 });
await db.set('user.789', { name: 'Pedro', age: 35, money: 2000 });

const stats = await db.aggregate([
  { type: 'count' },
  { type: 'sum', field: 'money' },
  { type: 'avg', field: 'age' },
  { type: 'min', field: 'money' },
  { type: 'max', field: 'money' },
  { type: 'distinct', field: 'name' }
]);

console.log(stats);
// {
//   count_all: 3,
//   sum_money: 4500,
//   avg_age: 30,
//   min_money: 1000,
//   max_money: 2000,
//   distinct_name: ['João', 'Maria', 'Pedro']
// }

Agregação de Array Específico

await db.set('scores', [
  { id: '1', value: { points: 85, level: 1 } },
  { id: '2', value: { points: 92, level: 2 } },
  { id: '3', value: { points: 78, level: 1 } }
]);

const arrayStats = await db.aggregate([
  { type: 'count', key: 'scores' },
  { type: 'sum', field: 'points', key: 'scores' },
  { type: 'avg', field: 'points', key: 'scores' }
]);

console.log(arrayStats);
// {
//   count_all: 3,
//   sum_points: 255,
//   avg_points: 85
// }

Operações Mínimas

// Apenas contar registros
const countOnly = await db.aggregate([
  { type: 'count' }
]);
// { count_all: 10 }

// Soma específica
const sumOnly = await db.aggregate([
  { type: 'sum', field: 'price' }
]);
// { sum_price: 1250.50 }

Tipos de Operação

Tipo	Descrição	Requer Field	Exemplo
`count`	Conta registros	❌	`{ type: 'count' }`
`sum`	Soma valores numéricos	✅	`{ type: 'sum', field: 'price' }`
`avg`	Calcula média	✅	`{ type: 'avg', field: 'age' }`
`min`	Valor mínimo	✅	`{ type: 'min', field: 'score' }`
`max`	Valor máximo	✅	`{ type: 'max', field: 'score' }`
`distinct`	Valores únicos	✅	`{ type: 'distinct', field: 'category' }`

Casos de Uso

Dashboards com múltiplas métricas customizáveis
Relatórios estatísticos flexíveis
Análise de dados específicos por campo
Otimização de múltiplas consultas em uma só

Validação e Erros

// ❌ Erro: Operação sem field obrigatório
await db.aggregate([
  { type: 'sum' } // Faltando field
]);
// Error: Operation 'sum' requires a field parameter

// ❌ Erro: Tipo de operação inválido
await db.aggregate([
  { type: 'invalid' }
]);
// Error: Unsupported aggregation operation: invalid

Comportamento

Performance: Alta eficiência para múltiplas operações
Flexibilidade: Combine diferentes tipos de análise
Validação: Verificação automática de parâmetros obrigatórios
Chaves Dinâmicas: Resultado com nomes baseados na operação

Métodos Relacionados

count() - Conta registros específicos
sum() - Soma valores numéricos
avg() - Calcula média dos valores
min() - Encontra o menor valor
max() - Encontra o maior valor
distinct() - Valores únicos de um campo