> For the complete documentation index, see [llms.txt](https://docs.gaiodataos.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.gaiodataos.com/gaio-dataos-portuguese/tools/tarefas/entrega/conteudo/relatorio-construtor-de-consultas-estaticas.md).

# 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

```javascript
// 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`:

```javascript
// 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.

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

***

#### from(table: string)

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

```javascript
context.query.from('users');
```

***

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

Adiciona uma condição de filtro à consulta.

```javascript
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.

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

***

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

Adiciona cláusula ORDER BY à consulta.

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

***

#### limit(limit: number)

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

```javascript
context.query.limit(100);
```

***

#### offset(offset: number)

Define o número de linhas a serem ignoradas.

```javascript
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.

```javascript
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

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

***

#### Query com Filtro

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

***

#### Query com Agregação

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

***

#### Paginação

```javascript
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();
```