Planilhas com SQL

Consulte as células de todas as planilhas com uma instrução SQL e preencha relatórios sem que os dados passem pelo agente.

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).

Quando os fatos ficam prontos

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:

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

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

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

Consultar

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

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

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

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

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:

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

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.