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 por um deployment privado SQAI — 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 para arquivos locais — sem cartão. Computação local usa a chave de dispositivo gratuita do sqai login.
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 para arquivos locais — sem cartão. Computação local usa a chave de dispositivo gratuita do sqai login.
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 para arquivos locais — sem cartão. Computação local usa a chave de dispositivo gratuita do sqai login.
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 para arquivos locais — sem cartão. Computação local usa a chave de dispositivo gratuita do sqai login.
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 para arquivos locais — sem cartão. Computação local usa a chave de dispositivo gratuita do sqai login.
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 para arquivos locais — sem cartão. Computação local usa a chave de dispositivo gratuita do sqai login.
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 para arquivos locais — sem cartão. Computação local usa a chave de dispositivo gratuita do sqai login.
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 para arquivos locais — sem cartão. Computação local usa a chave de dispositivo gratuita do sqai login.
dados
Nada sai do processo.
nota
Somente Python.

Deployment privado SQAIcredenciais criptografadas · nenhum dado copiado

PostgreSQL
caso
relacional
conectar
{ type: "postgres", host, port, database, user, password, table | query }
autenticação
SQAI_DEPLOYMENT_URL, com SQAI_API_KEY apenas se seu deployment exigir autenticação.
chave
A URL do seu deployment privado, mais uma chave de API opcional.
dados
Credenciais criptografadas no seu deployment SQAI. Linhas lidas sob demanda — nunca copiadas.
MySQL
caso
relacional
conectar
{ type: "mysql", host, port, database, user, password, table | query }
autenticação
SQAI_DEPLOYMENT_URL, com SQAI_API_KEY apenas se seu deployment exigir autenticação.
chave
A URL do seu deployment privado, mais uma chave de API opcional.
dados
Credenciais criptografadas no seu deployment SQAI. Linhas lidas sob demanda — nunca copiadas.
Oracle
caso
relacional
conectar
{ type: "oracle", host, port, database, user, password, table | query }
autenticação
SQAI_DEPLOYMENT_URL, com SQAI_API_KEY apenas se seu deployment exigir autenticação.
chave
A URL do seu deployment privado, mais uma chave de API opcional.
dados
Credenciais criptografadas no seu deployment SQAI. 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_DEPLOYMENT_URL, com SQAI_API_KEY apenas se seu deployment exigir autenticação.
chave
A URL do seu deployment privado, mais uma chave de API opcional.
dados
Credenciais criptografadas no seu deployment SQAI. Linhas lidas sob demanda — nunca copiadas.
Snowflake
caso
warehouse
conectar
{ type: "snowflake", connection_string, query }
autenticação
SQAI_DEPLOYMENT_URL, com SQAI_API_KEY apenas se seu deployment exigir autenticação.
chave
A URL do seu deployment privado, mais uma chave de API opcional.
dados
Credenciais criptografadas no seu deployment SQAI. Linhas lidas sob demanda — nunca copiadas.
BigQuery
caso
warehouse
conectar
{ type: "bigquery", connection_string, query }
autenticação
SQAI_DEPLOYMENT_URL, com SQAI_API_KEY apenas se seu deployment exigir autenticação.
chave
A URL do seu deployment privado, mais uma chave de API opcional.
dados
Credenciais criptografadas no seu deployment SQAI. Linhas lidas sob demanda — nunca copiadas.
ClickHouse
caso
warehouse
conectar
{ type: "clickhouse", connection_string, query }
autenticação
SQAI_DEPLOYMENT_URL, com SQAI_API_KEY apenas se seu deployment exigir autenticação.
chave
A URL do seu deployment privado, mais uma chave de API opcional.
dados
Credenciais criptografadas no seu deployment SQAI. Linhas lidas sob demanda — nunca copiadas.
Redshift
caso
warehouse
conectar
{ type: "redshift", connection_string, query }
autenticação
SQAI_DEPLOYMENT_URL, com SQAI_API_KEY apenas se seu deployment exigir autenticação.
chave
A URL do seu deployment privado, mais uma chave de API opcional.
dados
Credenciais criptografadas no seu deployment SQAI. Linhas lidas sob demanda — nunca copiadas.
S3
caso
armazenamento de objetos
conectar
{ type: "s3", … }
autenticação
SQAI_DEPLOYMENT_URL, com SQAI_API_KEY apenas se seu deployment exigir autenticação.
chave
A URL do seu deployment privado, mais uma chave de API opcional.
dados
Credenciais criptografadas no seu deployment SQAI. Linhas lidas sob demanda — nunca copiadas.
GCS
caso
armazenamento de objetos
conectar
{ type: "gcs", … }
autenticação
SQAI_DEPLOYMENT_URL, com SQAI_API_KEY apenas se seu deployment exigir autenticação.
chave
A URL do seu deployment privado, mais uma chave de API opcional.
dados
Credenciais criptografadas no seu deployment SQAI. Linhas lidas sob demanda — nunca copiadas.
Azure Blob
caso
armazenamento de objetos
conectar
{ type: "azure_blob", … }
autenticação
SQAI_DEPLOYMENT_URL, com SQAI_API_KEY apenas se seu deployment exigir autenticação.
chave
A URL do seu deployment privado, mais uma chave de API opcional.
dados
Credenciais criptografadas no seu deployment SQAI. Linhas lidas sob demanda — nunca copiadas.
Redis
caso
NoSQL · grafo · busca
conectar
{ type: "redis", … }
autenticação
SQAI_DEPLOYMENT_URL, com SQAI_API_KEY apenas se seu deployment exigir autenticação.
chave
A URL do seu deployment privado, mais uma chave de API opcional.
dados
Credenciais criptografadas no seu deployment SQAI. Linhas lidas sob demanda — nunca copiadas.
Neo4j
caso
NoSQL · grafo · busca
conectar
{ type: "neo4j", … }
autenticação
SQAI_DEPLOYMENT_URL, com SQAI_API_KEY apenas se seu deployment exigir autenticação.
chave
A URL do seu deployment privado, mais uma chave de API opcional.
dados
Credenciais criptografadas no seu deployment SQAI. Linhas lidas sob demanda — nunca copiadas.
Elasticsearch
caso
NoSQL · grafo · busca
conectar
{ type: "elasticsearch", … }
autenticação
SQAI_DEPLOYMENT_URL, com SQAI_API_KEY apenas se seu deployment exigir autenticação.
chave
A URL do seu deployment privado, mais uma chave de API opcional.
dados
Credenciais criptografadas no seu deployment SQAI. Linhas lidas sob demanda — nunca copiadas.
REST
caso
API
conectar
{ type: "rest", … }
autenticação
SQAI_DEPLOYMENT_URL, com SQAI_API_KEY apenas se seu deployment exigir autenticação.
chave
A URL do seu deployment privado, mais uma chave de API opcional.
dados
Credenciais criptografadas no seu deployment SQAI. Linhas lidas sob demanda — nunca copiadas.
GitHub
caso
repositórios de código
conectar
{ type: "github", … }
autenticação
SQAI_DEPLOYMENT_URL, com SQAI_API_KEY apenas se seu deployment exigir autenticação.
chave
A URL do seu deployment privado, mais uma chave de API opcional.
dados
Credenciais criptografadas no seu deployment SQAI. Linhas lidas sob demanda — nunca copiadas.
GitLab
caso
repositórios de código
conectar
{ type: "gitlab", … }
autenticação
SQAI_DEPLOYMENT_URL, com SQAI_API_KEY apenas se seu deployment exigir autenticação.
chave
A URL do seu deployment privado, mais uma chave de API opcional.
dados
Credenciais criptografadas no seu deployment SQAI. Linhas lidas sob demanda — nunca copiadas.
Bitbucket
caso
repositórios de código
conectar
{ type: "bitbucket", … }
autenticação
SQAI_DEPLOYMENT_URL, com SQAI_API_KEY apenas se seu deployment exigir autenticação.
chave
A URL do seu deployment privado, mais uma chave de API opcional.
dados
Credenciais criptografadas no seu deployment SQAI. Linhas lidas sob demanda — nunca copiadas.

O modo é inferido a partir do ambiente

SQAI_DEPLOYMENT_URLdeployment

Seu deployment SQAI, sua rede.

SQAI_API_KEYapi

Seu deployment SQAI autenticado.

nenhum definidolocal

Somente em processo.

Arquivos e SQLite funcionam em qualquer modo. Bancos de dados ao vivo exigem um deployment privado SQAI. O SQAI provisiona uma conexão uma única vez e permanece ativo — 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.

Seu deployment SQAI conecta diretamente, falando o protocolo 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 deployment SQAI
deployment SQAIconsultas somente leitura

No lugar, no escopo.

O SQAI runtime 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 SQAI runtime 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 deployment SQAI inclui python-oracledb em modo Thin e conecta diretamente — sem Instant Client, sem processo de runtime adicional, sem pacote Python extra. O SQAI runtime 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 deployment SQAI 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"
por um deployment privado SQAI{ 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 deployment SQAI 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 deployment SQAI 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 chave. Computação local usa a chave de dispositivo gratuita do sqai login. Bancos e warehouses ao vivo precisam de SQAI_DEPLOYMENT_URL, com SQAI_API_KEY apenas se seu deployment exigir autenticação.

O modelo pode ver minhas credenciais?

Não. As credenciais são fornecidas no seu código no momento do connect() e criptografadas no deployment SQAI. 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 SQAI runtime 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