> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Seleção de traces e logs com OQL

> Escreva uma única consulta em pipeline para traces e logs, com estágios fetch, filter, sort e limit, e execute-a pela API, pela CLI ou pelo AI Studio.

Consulte [URLs e autenticação HTTP](/docs/pt-BR/reference/base-urls.md) e a referência da API para os formatos completos de solicitação e resposta.

**Casos de uso**

* Executar a mesma seleção pela API, pela CLI e pelo **AI Studio**.
* Combinar várias condições em uma única expressão em vez de montar um array `filters`.
* Repassar uma investigação salva a um colega como uma única linha de texto.

***

## Visão geral

OQL é uma linguagem de pipeline para selecionar **Traces** e **Logs**. Uma consulta nomeia o sinal e depois adiciona estágios separados por `|`:

```txt theme={"theme":{"light":"github-light","dark":"github-dark"}}
fetch <signal> | filter <expr> | sort <field> <order> | limit <n>
```

`fetch` vem primeiro e é obrigatório. `filter` pode se repetir, e todos os filtros são combinados com `and`. Um estágio `sort` ou `limit` repetido usa o último valor. A OQL é compilada no mesmo planejador e registro de campos que o array estruturado `filters`, então um campo ou operador que funciona ali também funciona na OQL. Não há estágio de agregação: linhas calculadas e séries temporais vêm da [Telemetry API](/docs/pt-BR/ai-studio/observability/telemetry-api.md).

## Início rápido

Execute uma consulta de traces em uma janela de tempo. A API aceita somente timestamps RFC 3339.

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://router.toqan.ai/eu/v3/traces/query \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "2026-10-01T00:00:00Z",
    "to": "2026-10-02T00:00:00Z",
    "oql": "fetch traces | filter status == \"error\" | limit 20"
  }'
```

Os resultados ficam em `search.data`. Use os exemplos abaixo no campo `oql` do SDK ou no corpo da requisição. Os intervalos da API usam timestamps RFC 3339.

## Estágios

| Estágio | Forma | Regras |
| - | - | - |
| `fetch` | `fetch traces`, `fetch logs` | Obrigatório e primeiro. Qualquer outro início é rejeitado. |
| `filter` | `filter <field> <operator> <value>` | Opcional e repetível. Todos os filtros são combinados com `and`, então filtros contraditórios não retornam linhas. |
| `sort` | `sort <field> <asc\|desc>` | Opcional e repetível. Cada sinal fixa o campo que aceita, e um estágio repetido usa o último valor. |
| `limit` | `limit <n>` | Opcional e repetível. Usa o último valor e substitui o campo `limit` da solicitação. |

## Expressões de filtro

Duas formas são interpretadas como o mesmo filtro. A forma com símbolos cobre igualdade e ordenação:

| Escrito | Operador | Exemplo |
| - | - | - |
| `A == B` | `eq` | `status == "error"` |
| `A != B` | `neq` | `status != "error"` |
| `A > B` | `gt` | `tokens.total > 100` |
| `A >= B` | `gte` | `tokens.total >= 100` |
| `A < B` | `lt` | `tokens.total < 100` |
| `A <= B` | `lte` | `tokens.total <= 100` |

A forma com palavras cobre os operadores que precisam de sintaxe própria:

| Escrito | Exemplo |
| - | - |
| `A contains B` | `name contains "responses"` |
| `A in (B, C)` | `status in ("error", "success")` |
| `A not_in (B, C)` | `status not_in ("error")` |
| `A between (B, C)` | `start_time between ("2026-10-01T00:00:00Z", "2026-10-02T00:00:00Z")` |
| `A exists` | `tokens.total exists` |

As listas usam parênteses ou colchetes e são separadas por vírgulas. Os valores podem ser colocados entre `"` ou `'`, o que permite que um valor contenha espaços; uma aspa dentro de um valor exige o outro caractere de aspas.

Os operadores aceitos por um campo dependem do seu tipo, e não do parser. Uma expressão válida no tipo de campo errado ainda é rejeitada:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{ "code": 3, "message": "invalid filter: operator \"exists\" is not allowed for \"status\"", "details": [] }
```

A tabela de tipos e operadores está em [Gramática de filtros](/docs/pt-BR/ai-studio/observability/traces.md#filter-grammar); os campos aceitos e seus operadores vêm de `GET /v3/traces/fields` para traces e de `GET /v3/logs/fields` para logs.

Os filtros de status usam a grafia `success` e `error`; [Valores de status de trace](/docs/pt-BR/ai-studio/observability/telemetry-api.md#trace-status-values) relaciona esses valores aos da Telemetry API e de Reporting.

## Regras por sinal

| | Traces | Logs |
| - | - | - |
| Início | `fetch traces` | `fetch logs` |
| Endpoint | `POST /v3/traces/query` | `POST /v3/logs/query` |
| Ordenação | Somente `sort end_time desc` | Somente `sort timestamp desc` |
| `limit` do pipeline | Até 200 | Até 1000 |
| Timestamps | RFC 3339 no corpo da solicitação, valores relativos pela CLI | igual |
| Campos seletores | Somente `oql`; `filters` e `query` são rejeitados como campos desconhecidos | Somente `oql`; `filters` e `query` são aceitos, mas ignorados, então uma solicitação que os envia os descarta silenciosamente |

## Exemplos

**Traces com falha no último dia**

```text OQL theme={"theme":{"light":"github-light","dark":"github-dark"}}
fetch traces | filter status == "error" | sort end_time desc | limit 50
```

**Traces cujo nome corresponde a um deployment**, pelo nome do trace

```text OQL theme={"theme":{"light":"github-light","dark":"github-dark"}}
fetch traces | filter name contains "responses" | limit 20
```

**Traces em qualquer um de dois estados**

```text OQL theme={"theme":{"light":"github-light","dark":"github-dark"}}
fetch traces | filter status in ("error", "success") | limit 20
```

**Logs de erro, dos mais recentes para os mais antigos**

```text OQL theme={"theme":{"light":"github-light","dark":"github-dark"}}
fetch logs | filter severity_text == "ERROR" | sort timestamp desc | limit 100
```

**Traces caros**, combinando dois filtros

```text OQL theme={"theme":{"light":"github-light","dark":"github-dark"}}
fetch traces | filter tokens.total > 1000 | filter status == "success" | limit 20
```

**Logs de erro pelo SDK**, com o cliente do Início rápido

A OQL escrita no **AI Studio** chega ao mesmo endpoint, então as regras acima continuam valendo. A barra de consulta em **Traces** e **Logs** alterna entre um construtor e a OQL, e o formulário de relatório do Insights aceita o mesmo dialeto somente para estágios `filter`: `sort` e `limit` são rejeitados ali. As sugestões de campos vêm do registro de campos do workspace.

## Erros

| Mensagem | Causa |
| - | - |
| `invalid oql: query must start with fetch traces` | Início ausente ou que nomeia outro sinal; a mensagem repete o início esperado pelo sinal, então uma consulta de logs mostra `fetch logs` |
| `invalid oql: unsupported command "..."` | Um estágio diferente de `filter`, `sort` e `limit` |
| `invalid oql: unterminated quote` | Um `"` ou `'` que é aberto e nunca fechado |
| `invalid oql: malformed list` | Uma lista sem o `)` ou `]` de fechamento |
| `invalid oql: between expects exactly two values` | `between` com um ou três valores |
| `invalid oql: limit cannot exceed 200` | Uma consulta de traces acima do limite do pipeline |
| `validation error: limit: must be greater than or equal to 1 and less than or equal to 1000` | Uma consulta de logs acima do limite do pipeline |
| `invalid sort: only end_time desc is supported` | Qualquer outra ordenação de traces |
| `invalid sort: only timestamp desc is supported` | Qualquer outra ordenação de logs |
| `invalid filter: unknown field "..."` | Uma consulta de traces que nomeia um campo desconhecido pelo registro. Uma consulta de logs responde `filter[0]: unknown field "..."` |
| `invalid filter: operator "..." is not allowed for "..."` | Uma consulta de traces que aplica um operador fora da lista do campo, publicada por `GET /v3/traces/fields` |

Uma consulta malformada é rejeitada antes que o planejador seja executado, então uma solicitação inválida nunca retorna linhas parciais.

## Limitações

| Limitação | Impacto | Alternativa |
| - | - | - |
| Sem agregação | `summarize`, `group by` e contagens não fazem parte da linguagem | Use a [Telemetry API](/docs/pt-BR/ai-studio/observability/telemetry-api.md) |
| Um campo de ordenação | Cada sinal aceita um campo de ordenação: `end_time desc` para traces, `timestamp desc` para logs | Escolha a ordenação que importa |
| Os campos vêm do registro | Um atributo de span personalizado só existe depois que o workspace o registra | Confira a lista de campos antes de escrever a consulta |
| Traces não aceitam seletor estruturado | `filters` e `query` são campos desconhecidos em `/v3/traces/query` | Expresse cada condição como um estágio `filter` |
| O texto do pipeline não diferencia maiúsculas de minúsculas nos comandos | `FETCH` e `fetch` são iguais | Escolha uma grafia por consulta para facilitar a leitura |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.