> 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

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.gaiodataos.com/gaio-dataos-portuguese/tools/tarefas/entrega/conteudo/relatorio-construtor-de-consultas-estaticas.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.