Capítulo · Conecte seus dados

Toda fonte.
Uma porta de entrada.

Uma chamada registra uma fonte, infere um schema tipado e fixa sua revisão em cada plano que a toca. Arquivos e SQLite rodam em processo — sem chave, nada sai. Bancos de dados ativos conectam-se pela engine — diretamente, pelo protocolo nativo de cada banco: credenciais criptografadas, nenhum dado copiado.

const sales = await sqai.connect("./data/sales.csv", { name: "sales" })

→ row_count 12 · schema_revision e4938027… · status ready

tipado · fixado por hash · somente leitura

IIOs tipos de caso

Duas bandejas. Vinte e seis gavetas.

Cada gaveta abre para o mesmo contrato: como conecta, o que precisa, o que sai. Abra uma.

Em processosem chave · sem daemon · sem rede

CSV
caso
arquivo
conectar
"./data/sales.csv"
autenticação
Nenhuma. SQAI lê os bytes no seu processo.
chave
Sem chave — sem conta, sem cartão, superfície completa somente leitura.
dados
Nada sai do processo.
TSV
caso
arquivo
conectar
"./data/orders.tsv"
autenticação
Nenhuma. SQAI lê os bytes no seu processo.
chave
Sem chave — sem conta, sem cartão, superfície completa somente leitura.
dados
Nada sai do processo.
JSON
caso
arquivo
conectar
"./data/sales.json"
autenticação
Nenhuma. SQAI lê os bytes no seu processo.
chave
Sem chave — sem conta, sem cartão, superfície completa somente leitura.
dados
Nada sai do processo.
nota
Um caminho ou um objeto.
rows
caso
em memória
conectar
[{ region: "east", revenue: 512 }, …]
autenticação
Nenhuma. SQAI lê os bytes no seu processo.
chave
Sem chave — sem conta, sem cartão, superfície completa somente leitura.
dados
Nada sai do processo.
{ records }
caso
em memória
conectar
{ records: [ … ] }
autenticação
Nenhuma. SQAI lê os bytes no seu processo.
chave
Sem chave — sem conta, sem cartão, superfície completa somente leitura.
dados
Nada sai do processo.
SQLite
caso
banco de dados embutido
conectar
{ provider: "sqlite", path, table | query }
autenticação
Nenhuma. SQAI lê os bytes no seu processo.
chave
Sem chave — sem conta, sem cartão, superfície completa somente leitura.
dados
Nada sai do processo.
nota
Um banco de dados completo, ainda em processo. Indique uma tabela ou uma consulta somente leitura.
Excel
caso
arquivo
conectar
"./data/sales.xlsx"
autenticação
Nenhuma. SQAI lê os bytes no seu processo.
chave
Sem chave — sem conta, sem cartão, superfície completa somente leitura.
dados
Nada sai do processo.
nota
Somente Python.
Parquet
caso
arquivo
conectar
"./data/sales.parquet"
autenticação
Nenhuma. SQAI lê os bytes no seu processo.
chave
Sem chave — sem conta, sem cartão, superfície completa somente leitura.
dados
Nada sai do processo.
nota
Somente Python.

Pela enginecredenciais criptografadas · nenhum dado copiado

PostgreSQL
caso
relacional
conectar
{ type: "postgres", host, port, database, user, password, table | query }
autenticação
SQAI_API_KEY para o engine hospedado, ou SQAI_ENGINE_URL para o seu próprio.
chave
Uma chave, ou a URL do seu próprio engine.
dados
Credenciais criptografadas no engine. Linhas lidas sob demanda — nunca copiadas.
MySQL
caso
relacional
conectar
{ type: "mysql", host, port, database, user, password, table | query }
autenticação
SQAI_API_KEY para o engine hospedado, ou SQAI_ENGINE_URL para o seu próprio.
chave
Uma chave, ou a URL do seu próprio engine.
dados
Credenciais criptografadas no engine. Linhas lidas sob demanda — nunca copiadas.
Oracle
caso
relacional
conectar
{ type: "oracle", host, port, database, user, password, table | query }
autenticação
SQAI_API_KEY para o engine hospedado, ou SQAI_ENGINE_URL para o seu próprio.
chave
Uma chave, ou a URL do seu próprio engine.
dados
Credenciais criptografadas no engine. Linhas lidas sob demanda — nunca copiadas.
nota
Driver Thin-mode embutido — nenhum cliente Oracle a instalar.
SQL Server
caso
relacional
conectar
{ type: "mssql", host, port, database, user, password, table | query }
autenticação
SQAI_API_KEY para o engine hospedado, ou SQAI_ENGINE_URL para o seu próprio.
chave
Uma chave, ou a URL do seu próprio engine.
dados
Credenciais criptografadas no engine. Linhas lidas sob demanda — nunca copiadas.
Snowflake
caso
warehouse
conectar
{ type: "snowflake", connection_string, query }
autenticação
SQAI_API_KEY para o engine hospedado, ou SQAI_ENGINE_URL para o seu próprio.
chave
Uma chave, ou a URL do seu próprio engine.
dados
Credenciais criptografadas no engine. Linhas lidas sob demanda — nunca copiadas.
BigQuery
caso
warehouse
conectar
{ type: "bigquery", connection_string, query }
autenticação
SQAI_API_KEY para o engine hospedado, ou SQAI_ENGINE_URL para o seu próprio.
chave
Uma chave, ou a URL do seu próprio engine.
dados
Credenciais criptografadas no engine. Linhas lidas sob demanda — nunca copiadas.
ClickHouse
caso
warehouse
conectar
{ type: "clickhouse", connection_string, query }
autenticação
SQAI_API_KEY para o engine hospedado, ou SQAI_ENGINE_URL para o seu próprio.
chave
Uma chave, ou a URL do seu próprio engine.
dados
Credenciais criptografadas no engine. Linhas lidas sob demanda — nunca copiadas.
Redshift
caso
warehouse
conectar
{ type: "redshift", connection_string, query }
autenticação
SQAI_API_KEY para o engine hospedado, ou SQAI_ENGINE_URL para o seu próprio.
chave
Uma chave, ou a URL do seu próprio engine.
dados
Credenciais criptografadas no engine. Linhas lidas sob demanda — nunca copiadas.
S3
caso
armazenamento de objetos
conectar
{ type: "s3", … }
autenticação
SQAI_API_KEY para o engine hospedado, ou SQAI_ENGINE_URL para o seu próprio.
chave
Uma chave, ou a URL do seu próprio engine.
dados
Credenciais criptografadas no engine. Linhas lidas sob demanda — nunca copiadas.
GCS
caso
armazenamento de objetos
conectar
{ type: "gcs", … }
autenticação
SQAI_API_KEY para o engine hospedado, ou SQAI_ENGINE_URL para o seu próprio.
chave
Uma chave, ou a URL do seu próprio engine.
dados
Credenciais criptografadas no engine. Linhas lidas sob demanda — nunca copiadas.
Azure Blob
caso
armazenamento de objetos
conectar
{ type: "azure_blob", … }
autenticação
SQAI_API_KEY para o engine hospedado, ou SQAI_ENGINE_URL para o seu próprio.
chave
Uma chave, ou a URL do seu próprio engine.
dados
Credenciais criptografadas no engine. Linhas lidas sob demanda — nunca copiadas.
Redis
caso
NoSQL · grafo · busca
conectar
{ type: "redis", … }
autenticação
SQAI_API_KEY para o engine hospedado, ou SQAI_ENGINE_URL para o seu próprio.
chave
Uma chave, ou a URL do seu próprio engine.
dados
Credenciais criptografadas no engine. Linhas lidas sob demanda — nunca copiadas.
Neo4j
caso
NoSQL · grafo · busca
conectar
{ type: "neo4j", … }
autenticação
SQAI_API_KEY para o engine hospedado, ou SQAI_ENGINE_URL para o seu próprio.
chave
Uma chave, ou a URL do seu próprio engine.
dados
Credenciais criptografadas no engine. Linhas lidas sob demanda — nunca copiadas.
Elasticsearch
caso
NoSQL · grafo · busca
conectar
{ type: "elasticsearch", … }
autenticação
SQAI_API_KEY para o engine hospedado, ou SQAI_ENGINE_URL para o seu próprio.
chave
Uma chave, ou a URL do seu próprio engine.
dados
Credenciais criptografadas no engine. Linhas lidas sob demanda — nunca copiadas.
REST
caso
API
conectar
{ type: "rest", … }
autenticação
SQAI_API_KEY para o engine hospedado, ou SQAI_ENGINE_URL para o seu próprio.
chave
Uma chave, ou a URL do seu próprio engine.
dados
Credenciais criptografadas no engine. Linhas lidas sob demanda — nunca copiadas.
GitHub
caso
repositórios de código
conectar
{ type: "github", … }
autenticação
SQAI_API_KEY para o engine hospedado, ou SQAI_ENGINE_URL para o seu próprio.
chave
Uma chave, ou a URL do seu próprio engine.
dados
Credenciais criptografadas no engine. Linhas lidas sob demanda — nunca copiadas.
GitLab
caso
repositórios de código
conectar
{ type: "gitlab", … }
autenticação
SQAI_API_KEY para o engine hospedado, ou SQAI_ENGINE_URL para o seu próprio.
chave
Uma chave, ou a URL do seu próprio engine.
dados
Credenciais criptografadas no engine. Linhas lidas sob demanda — nunca copiadas.
Bitbucket
caso
repositórios de código
conectar
{ type: "bitbucket", … }
autenticação
SQAI_API_KEY para o engine hospedado, ou SQAI_ENGINE_URL para o seu próprio.
chave
Uma chave, ou a URL do seu próprio engine.
dados
Credenciais criptografadas no engine. Linhas lidas sob demanda — nunca copiadas.

O modo é inferido a partir do ambiente

SQAI_ENGINE_URLself_hosted

Seu engine, sua rede.

SQAI_API_KEYapi

O engine hospedado.

nenhum definidolocal

Somente em processo.

Arquivos e SQLite funcionam em qualquer modo. Bancos de dados ao vivo exigem api ou self_hosted. O engine provisiona uma conexão uma única vez e permanece ativo — um daemon residente, sem cold start por consulta.

Não é uma sincronização. Não é uma exportação.
Não é uma ponte de terceiros.

conectividade direta pelo protocolo de rede nativo do banco de dados

IIIO protocolo

Direto. Até o protocolo.

O engine conecta diretamente, falando o protocolo de rede nativo de cada banco de dados. As consultas são executadas no lugar, com escopo para sua organização — seu banco de dados nunca é copiado.

fig. — o protocolo
seu banco de dadoslinhas permanecem no lugar
protocolo de rede nativo — falado diretamente pelo engine
o engineconsultas somente leitura

No lugar, no escopo.

O engine consulta seus dados onde eles residem, com escopo para sua organização — e nunca acessa além do que você configurou.

Credenciais protegidas.

Criptografadas em repouso, com escopo por organização, usadas apenas para atender às consultas da sua organização. Um conector nunca retorna sua configuração — apenas nome, tipo, status e o último resultado de teste.

nunca copiado

O engine nunca copia seu banco de dados — as linhas são lidas onde residem.

SELECT 1ok · connector: live

Cada teste abre uma conexão real — SELECT 1 para SQL, um HEAD para armazenamento de objetos, uma busca de amostra para REST. Um conector só fica ativo após uma conexão real bem-sucedida; edite sua configuração e ele volta ao estado não testado.

O protocolo principal · Oracle

Modo Thin. Nada a instalar.

O engine inclui python-oracledb em modo Thin e conecta diretamente — sem Instant Client, sem processo de runtime adicional, sem pacote Python extra. O engine controla o protocolo de ponta a ponta: o driver, o pool de conexões limitado, a verificação de credenciais, a navegação de esquema e um caminho de busca em lote compatível com Arrow — nunca uma conexão de fallback oculta fora do pool.

  • raízes somente SELECT / WITH
  • limite ROWNUM vinculado
  • sonda persistida · reutilizada em 0 ms

Redshift responde em PostgreSQL.

As tabelas são lidas no lugar pelo protocolo de rede do PostgreSQL — o cluster nunca é copiado. Até a mensagem de sucesso do teste menciona PostgreSQL.

Um destino, todos os caminhos.

Armazenamento de objetos e uploads compartilham os mesmos parsers — um objeto Parquet no S3 e um arquivo Parquet enviado chegam ao engine de forma idêntica.

Mesma requisição → mesmas linhas, mesma ordem · todo acesso auditável · egresso é uma allowlist por implantação com falha fechada

IVA uniformidade

Downstream não distingue CSV de Snowflake.

Cada fonte retorna o mesmo SqaiSource tipado — mesmos campos, mesmos pins, mesmas garantias. Substitua o warehouse pelo arquivo e nada downstream muda.

em processo"./data/sales.csv"
pelo engine{ type: "snowflake", connection_string, query }

SqaiSource

mesma forma · toda fonte
name"sales"
source_ide135c6f7eec0e846c01c4ef8
fieldsregion · product · revenue · cost · units · order_date
typed_fields2 string · 3 number · 1 date
row_count12
schema_revisione4938027ddf0d2210f019770403efd45d350eac28100902ddd7c5191c9b8cfbe
statusready

Um certificado, qualquer que seja a fonte. O código downstream nunca sabe onde as linhas residem.

Registrado uma vez.
Nunca redefinido.

reatribuir um nome lança exceção source_already_registered

VO pin

Mude os dados. O replay dirá.

connect() fixa uma revisão de esquema em cada plano e computação. Um plano armazenado reexecutado sobre dados alterados expõe a mudança — nunca números silenciosamente diferentes.

schema_revision
Fixado no momento do connect em cada plano e computação que toca a fonte.
schema_revision_mismatch
O que um replay retorna quando os dados foram alterados por baixo.
source_already_registered
Fontes são imutáveis — um nome nunca pode ser silenciosamente redirecionado para dados diferentes.

provenance.bindings[0]

source_name"sales"
fields["revenue"]
schema_revisione4938027…c9b8cfbe
row_count12
input_hash2ea5ede7…478e3212

Todo campo vinculado carrega sua linhagem.

VIPerguntas

Acesso de LLM a bancos de dados, respondido.

Como concedo a um LLM acesso ao meu banco de dados?

Registre a fonte em código com connect(). O modelo nunca vê uma string de conexão — recebe três ferramentas somente leitura sobre fontes tipadas, e a política decide quais fontes e campos ele pode acessar.

Conectar copia meus dados para algum lugar?

Não. Fontes em processo nunca saem da sua máquina. Fontes do engine mantêm credenciais criptografadas; as linhas são lidas sob demanda e nunca copiadas.

O SQAI é uma sincronização, uma exportação ou uma ponte de terceiros para meu banco de dados?

Nenhuma dessas. A conectividade é direta pelo protocolo nativo do banco de dados — o engine consulta seus dados no lugar, com escopo para sua organização, e nunca copia seu banco.

Preciso de uma API key para conectar dados?

Não para arquivos, linhas em memória ou SQLite — esses rodam em processo sem nenhuma conta. Bancos e warehouses ao vivo precisam de SQAI_API_KEY para o engine hospedado, ou SQAI_ENGINE_URL para o seu próprio.

O modelo pode ver minhas credenciais?

Não. As credenciais são fornecidas no seu código no momento do connect() e criptografadas no engine. A entrada de ferramenta do modelo carrega intenção tipada — sem detalhes de conexão, sem campos de política.

O Oracle é suportado sem instalar um cliente?

Sim. O engine inclui um driver Thin-mode embutido, portanto não há cliente Oracle a instalar.

O que acontece quando os dados subjacentes mudam?

O schema_revision fixado no connect deixa de corresponder, e um replay retorna schema_revision_mismatch em vez de números silenciosamente diferentes. Reatribuir um nome registrado lança source_already_registered.

Conecte algo.

Node ≥ 20 · Python ≥ 3.10 · arquivos & SQLite dispensam chave