---
title: Planilhas com SQL
description: Consulte as células de todas as planilhas com uma instrução SQL e preencha relatórios sem que os dados passem pelo agente.
sidebar:
  order: 3
---

Cada planilha `.xlsx`, `.xlsm` ou `.csv` enviada vira fatos que o agente consulta com SQL. Uma pergunta sobre dez planilhas cabe em uma chamada `sql`, em vez de dez leituras de arquivo. `sql` e `sql_schema` rodam dentro de scripts `query`; `sql_write` e `sheet_write`, dentro de scripts `execute` ([MCP](/docs/agents/mcp)).

## Quando os fatos ficam prontos [#readiness]

Todo arquivo tem um `status`, que `get`, `files_list`, `file_read` e `document_search` informam; os que não estão `ready` trazem em `statusMessage` o que fazer:

| Status | Significado |
| :-- | :-- |
| `processing` | O arquivo ainda está sendo lido. |
| `ready` | As células ou o texto já podem ser consultados. |
| `too_large` | O arquivo passa do limite de células ou de tamanho por planilha do plano. Ele continua disponível para download; divida-o em partes menores e envie de novo, ou mude de plano. |
| `limit_reached` | Os dados processados da organização chegaram ao limite do plano. O arquivo fica guardado e é lido sozinho quando houver espaço: ao mudar de plano, apagar arquivos ou tabelas SQL. |
| `failed` | O arquivo não pôde ser lido. |
| `stored` | Um tipo que a Siglata guarda, mas não lê, como um vídeo. |

A Siglata guarda apenas fatos determinísticos: nunca recalcula fórmulas, nunca adivinha versões nem localidades. A interpretação fica com o agente.

## Tabelas e funções [#facts]

Chame `sql_schema` para ver as colunas de cada tabela, as funções e os objetos que você pode ler.

| Tabela | Conteúdo |
| :-- | :-- |
| `sheet_files` | Um registro por planilha, com o estado dos fatos. |
| `cells` | Uma linha por célula: arquivo, aba, endereço, linha, coluna, texto bruto, valor tipado, fórmula e formato numérico. |
| `styles` | Fonte, preenchimento, borda e alinhamento de cada estilo. |
| `sheets` | Abas e intervalos usados. |
| `excel_tables` | Tabelas do Excel. |
| `defined_names` | Nomes definidos. |
| `merges` | Células mescladas. |

| Função | Uso |
| :-- | :-- |
| `sheet_rows(file, sheet)` | Linhas largas de uma aba, com as colunas por letra (`A`, `B`, `C`…). |
| `parse_number(text, locale)` | Converte texto como `1.234,56` (`pt-BR`) ou `1,234.56` (`en-US`) em número. |
| `parse_date(text, format)` | Converte texto em data com um padrão como `DD/MM/YYYY`. |
| `column_letters(col)` | Converte o número da coluna em letras. |

Valores de CSV ficam como texto; use `parse_number` e `parse_date` para interpretá-los.

## Consultar [#query]

`sql` (`files:read`) executa um único `SELECT` na sintaxe do Postgres, em um script `query`:

```js
return await sql({
  query: `SELECT raw AS filial, count(*) AS celulas
FROM cells
WHERE sheet = 'Vendas' AND col = 2 AND row >= 2
GROUP BY raw`,
});
```

- Devolve as linhas que cabem em 100.000 bytes de JSON, sem limite de linhas, e roda por no máximo 10 s. Quando algo fica de fora, a resposta traz `truncated: true` e `next`, que explica como paginar com `ORDER BY` e `LIMIT`/`OFFSET` ou estreitar o `SELECT`.
- Nomeie tabelas sem esquema. Só as funções e os tipos listados são aceitos; catálogos do sistema e comandos que alteram dados são recusados.
- Antes de um comando rodar, a Siglata limita a memória do banco que ele poderia usar no pior caso, pelos valores mais longos das tabelas que ele lê e por uma regra de tamanho para cada função, operador e conversão, através de cada CTE, subconsulta e view. Um comando acima de 128 MiB é recusado com `too_large`, antes de rodar, em `SELECT`, `CREATE VIEW` e `CREATE TABLE AS`: monte valores menores (menos `concat`, `replace`, conversões ou construtores de JSON e de array aninhados), selecione menos colunas ou divida o trabalho. `WITH RECURSIVE` é recusado (use `generate_series`), e um padrão de expressão regular ou de `SIMILAR TO` precisa ser uma constante de texto de no máximo 2.000 estados compilados. No máximo 4 comandos rodam ao mesmo tempo; um comando que encontra todos ocupados falha com `conflict`, e basta tentar de novo.
- Cada recusa tem um código, como `relation_not_allowed`, `function_not_allowed`, `timeout` ou `conflict` (repita a chamada).

## Views e snapshots [#views-and-snapshots]

`sql_write` (`files:write`) cria e remove objetos seus, em um script `execute`:

| Instrução | Resultado |
| :-- | :-- |
| `CREATE VIEW nome AS SELECT …` | Uma view compartilhada com a organização. Cada membro a lê com o próprio acesso. |
| `CREATE TABLE nome AS SELECT …` | Um snapshot que só você lê, sobre `sources` (os ids dos arquivos que ele pode ler; todos os que você lê, se omitido). Conta no limite de planilhas que o agente consulta. |
| `DROP VIEW nome` ou `DROP TABLE nome` | Remove um objeto que você criou. |

```js
return await sql_write({
  query:
    "CREATE TABLE vendas_agosto AS SELECT raw FROM cells WHERE sheet = 'Agosto'",
  sources: ["<id da planilha>"],
});
```

Um snapshot segue os arquivos de origem: fica oculto enquanto uma origem está na lixeira, volta quando ela é restaurada e é removido quando ela é excluída definitivamente.

## Preencher um relatório [#fill]

`sheet_write`, em um script `execute`, aceita um patch de consulta `{ sheet, anchor, query }` (exige também `files:read`). Ele roda o `SELECT` e escreve todas as linhas a partir da célula `anchor` de uma nova edição do modelo, mantendo a formatação:

```js
return await sheet_write({
  fileId: "<id do modelo>",
  requestId: "vendas-setembro-2026",
  patches: [
    {
      sheet: "Relatório",
      anchor: "A2",
      query: "SELECT filial, receita FROM vendas_mes",
    },
  ],
});
```

As linhas não passam pelo contexto do agente; a resposta traz apenas o novo arquivo e o intervalo escrito. Um resultado acima de 5.000 linhas, 8 MiB ou 1.000.000 de células falha com `too_large`, sem criar arquivo.

## Permissões [#permissions]

O SQL vê apenas as células dos arquivos ativos que o usuário da conexão pode ler. Um arquivo restrito exige uma permissão; outra organização nunca aparece. Arquivos na lixeira ficam ocultos até serem restaurados.