Relatório Construtor de Consultas Estáticas

Report Static Query Builder

Visão Geral

O MiniQueryBuilder é uma interface fluente para construção de consultas SQL-like no Gaio Data OS. Ele fornece uma forma simples e intuitiva de construir queries com cláusulas como SELECT, FROM, WHERE, GROUP BY, ORDER BY, LIMIT e OFFSET.

---

Uso Básico

// Acesse o query builder através de context.query
const results = await context.query
  .select(['id', 'name', 'created_at'])
  .from('users')
  .filter('status', 'eq', 'active')
  .orderBy('created_at', 'desc')
  .limit(100)
  .run();

Referência da API

Construtor

O query builder é acessado através do objeto context:

// Não é necessário criar uma instância - use context.query
const query = context.query;

---

Métodos

select(fields: string[])

Especifica os campos a serem selecionados na query.

context.query.select(['id', 'name', 'email']);

---

from(table: string)

Especifica a tabela de origem da consulta. Este método é obrigatório.

context.query.from('users');

---

filter(field: string, operator: FilterOperator, value: any)

Adiciona uma condição de filtro à consulta.

context.query.filter('age', 'gt', 18);

Operadores disponíveis:

• eq – igual

• neq – diferente

• gt – maior que

• gte – maior ou igual

• lt – menor que

• lte – menor ou igual

• like – correspondência de padrão com %

• ilike – correspondência de padrão sem diferenciar maiúsculas/minúsculas

• in – dentro de uma lista de valores

• is – verificação de null

• cs – contém (para arrays)

• cd – contido em (para arrays)

• ov – sobreposição (para arrays)

• fts – busca por texto completo

• or – OU lógico

• and – E lógico

---

groupBy(fields: string[])

Especifica os campos para agrupamento.

context.query.groupBy(['department', 'role']);

---

orderBy(field: string, direction: 'asc' | 'desc' = 'asc', nullsPosition?: 'first' | 'last')

Adiciona cláusula ORDER BY à consulta.

context.query.orderBy('created_at', 'desc', 'last');

---

limit(limit: number)

Define o número máximo de linhas a retornar.

context.query.limit(100);

---

offset(offset: number)

Define o número de linhas a serem ignoradas.

context.query.offset(50);

---

run(): Promise<GenericType[]>

Executa a consulta e retorna uma Promise que resolve para um array de resultados. Este é o método principal para executar a query e recuperar os dados.

const results = await context.query
  .select(['id', 'name'])
  .from('users')
  .limit(100)
  .run();

---

Valor de Retorno

Retorna uma Promise que resolve para um array de objetos (GenericType[]) representando os resultados da consulta.

Cada objeto no array corresponde a uma linha do resultado, com propriedades que correspondem às colunas selecionadas.

---

Validação

O método run() realiza as seguintes validações antes de executar a consulta:

• Garante que o limit seja um número

• Garante que o limit não ultrapasse 10.000 linhas

• Verifica implicitamente se a cláusula FROM foi especificada

---

Tratamento de Erros

O método run() pode lançar erros nos seguintes casos:

• Se o limit não for um número: Error('Limit must be a number')

• Se o limit exceder 10.000: Error('Limit must be less than 10000')

• Se a cláusula FROM não for especificada: Error('FROM clause is required. Use .from() to specify a table.')

• Se a requisição à API falhar: O erro retornado pelo cliente da API será propagado.

---

Detalhes de Implementação

O método run() envia uma requisição POST para api/table/query com o schema da consulta e os dados da tarefa. Em seguida, extrai e retorna os dados da resposta.

---

Exemplos

Query Básica

const users = await context.query
  .select(['id', 'name', 'email'])
  .from('users')
  .limit(100)
  .run();

---

Query com Filtro

const activeUsers = await context.query
  .select(['id', 'name', 'email'])
  .from('users')
  .filter('status', 'eq', 'active')
  .run();

---

Query com Agregação

const departmentCounts = await context.query
  .select(['department', 'COUNT(*) as count'])
  .from('employees')
  .groupBy(['department'])
  .orderBy('count', 'desc')
  .run();

---

Paginação

const page = 2;
const pageSize = 50;

const paginatedUsers = await context.query
  .select(['id', 'name', 'email'])
  .from('users')
  .orderBy('id', 'asc')
  .limit(pageSize)
  .offset((page - 1) * pageSize)
  .run();