Capítulo · Conecta tus datos

Cada fuente.
Una sola puerta.

Una llamada registra una fuente, infiere un esquema tipado y fija su revisión en cada plan que la toca. Los archivos y SQLite se ejecutan en proceso — sin clave, nada sale. Las bases de datos en vivo se conectan a través de un despliegue privado de SQAI — directamente, mediante el protocolo propio de cada base de datos: credenciales cifradas, sin copia de datos.

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

→ row_count 12 · schema_revision e4938027… · status ready

tipado · fijado por hash · solo lectura

IILos tipos de caso

Dos bandejas. Veintiséis cajones.

Cada cajón abre al mismo contrato: cómo se conecta, qué necesita, qué sale. Abre uno.

En procesosin clave · sin daemon · sin red

CSV
caso
archivo
conectar
"./data/sales.csv"
autenticación
Ninguna. SQAI lee los bytes en tu proceso.
clave
Sin clave para archivos locales — sin tarjeta. El cómputo local usa la clave de dispositivo del sqai login gratuito.
datos
Nada sale del proceso.
TSV
caso
archivo
conectar
"./data/orders.tsv"
autenticación
Ninguna. SQAI lee los bytes en tu proceso.
clave
Sin clave para archivos locales — sin tarjeta. El cómputo local usa la clave de dispositivo del sqai login gratuito.
datos
Nada sale del proceso.
JSON
caso
archivo
conectar
"./data/sales.json"
autenticación
Ninguna. SQAI lee los bytes en tu proceso.
clave
Sin clave para archivos locales — sin tarjeta. El cómputo local usa la clave de dispositivo del sqai login gratuito.
datos
Nada sale del proceso.
nota
Una ruta o un objeto.
rows
caso
en memoria
conectar
[{ region: "east", revenue: 512 }, …]
autenticación
Ninguna. SQAI lee los bytes en tu proceso.
clave
Sin clave para archivos locales — sin tarjeta. El cómputo local usa la clave de dispositivo del sqai login gratuito.
datos
Nada sale del proceso.
{ records }
caso
en memoria
conectar
{ records: [ … ] }
autenticación
Ninguna. SQAI lee los bytes en tu proceso.
clave
Sin clave para archivos locales — sin tarjeta. El cómputo local usa la clave de dispositivo del sqai login gratuito.
datos
Nada sale del proceso.
SQLite
caso
base de datos embebida
conectar
{ provider: "sqlite", path, table | query }
autenticación
Ninguna. SQAI lee los bytes en tu proceso.
clave
Sin clave para archivos locales — sin tarjeta. El cómputo local usa la clave de dispositivo del sqai login gratuito.
datos
Nada sale del proceso.
nota
Una base de datos completa, aún en proceso. Indica una tabla o una consulta de solo lectura.
Excel
caso
archivo
conectar
"./data/sales.xlsx"
autenticación
Ninguna. SQAI lee los bytes en tu proceso.
clave
Sin clave para archivos locales — sin tarjeta. El cómputo local usa la clave de dispositivo del sqai login gratuito.
datos
Nada sale del proceso.
nota
Solo Python.
Parquet
caso
archivo
conectar
"./data/sales.parquet"
autenticación
Ninguna. SQAI lee los bytes en tu proceso.
clave
Sin clave para archivos locales — sin tarjeta. El cómputo local usa la clave de dispositivo del sqai login gratuito.
datos
Nada sale del proceso.
nota
Solo Python.

A través del motorcredenciales cifradas · sin copia de datos

PostgreSQL
caso
relacional
conectar
{ type: "postgres", host, port, database, user, password, table | query }
autenticación
SQAI_DEPLOYMENT_URL, con SQAI_API_KEY solo si tu despliegue requiere autenticación.
clave
La URL de tu despliegue privado, más una clave API opcional.
datos
Credenciales cifradas en tu despliegue de SQAI. Filas leídas bajo demanda — nunca copiadas.
MySQL
caso
relacional
conectar
{ type: "mysql", host, port, database, user, password, table | query }
autenticación
SQAI_DEPLOYMENT_URL, con SQAI_API_KEY solo si tu despliegue requiere autenticación.
clave
La URL de tu despliegue privado, más una clave API opcional.
datos
Credenciales cifradas en tu despliegue de SQAI. Filas leídas bajo demanda — nunca copiadas.
Oracle
caso
relacional
conectar
{ type: "oracle", host, port, database, user, password, table | query }
autenticación
SQAI_DEPLOYMENT_URL, con SQAI_API_KEY solo si tu despliegue requiere autenticación.
clave
La URL de tu despliegue privado, más una clave API opcional.
datos
Credenciales cifradas en tu despliegue de SQAI. Filas leídas bajo demanda — nunca copiadas.
nota
Driver en modo Thin incluido — sin cliente Oracle que instalar.
SQL Server
caso
relacional
conectar
{ type: "mssql", host, port, database, user, password, table | query }
autenticación
SQAI_DEPLOYMENT_URL, con SQAI_API_KEY solo si tu despliegue requiere autenticación.
clave
La URL de tu despliegue privado, más una clave API opcional.
datos
Credenciales cifradas en tu despliegue de SQAI. Filas leídas bajo demanda — nunca copiadas.
Snowflake
caso
almacén de datos
conectar
{ type: "snowflake", connection_string, query }
autenticación
SQAI_DEPLOYMENT_URL, con SQAI_API_KEY solo si tu despliegue requiere autenticación.
clave
La URL de tu despliegue privado, más una clave API opcional.
datos
Credenciales cifradas en tu despliegue de SQAI. Filas leídas bajo demanda — nunca copiadas.
BigQuery
caso
almacén de datos
conectar
{ type: "bigquery", connection_string, query }
autenticación
SQAI_DEPLOYMENT_URL, con SQAI_API_KEY solo si tu despliegue requiere autenticación.
clave
La URL de tu despliegue privado, más una clave API opcional.
datos
Credenciales cifradas en tu despliegue de SQAI. Filas leídas bajo demanda — nunca copiadas.
ClickHouse
caso
almacén de datos
conectar
{ type: "clickhouse", connection_string, query }
autenticación
SQAI_DEPLOYMENT_URL, con SQAI_API_KEY solo si tu despliegue requiere autenticación.
clave
La URL de tu despliegue privado, más una clave API opcional.
datos
Credenciales cifradas en tu despliegue de SQAI. Filas leídas bajo demanda — nunca copiadas.
Redshift
caso
almacén de datos
conectar
{ type: "redshift", connection_string, query }
autenticación
SQAI_DEPLOYMENT_URL, con SQAI_API_KEY solo si tu despliegue requiere autenticación.
clave
La URL de tu despliegue privado, más una clave API opcional.
datos
Credenciales cifradas en tu despliegue de SQAI. Filas leídas bajo demanda — nunca copiadas.
S3
caso
almacenamiento de objetos
conectar
{ type: "s3", … }
autenticación
SQAI_DEPLOYMENT_URL, con SQAI_API_KEY solo si tu despliegue requiere autenticación.
clave
La URL de tu despliegue privado, más una clave API opcional.
datos
Credenciales cifradas en tu despliegue de SQAI. Filas leídas bajo demanda — nunca copiadas.
GCS
caso
almacenamiento de objetos
conectar
{ type: "gcs", … }
autenticación
SQAI_DEPLOYMENT_URL, con SQAI_API_KEY solo si tu despliegue requiere autenticación.
clave
La URL de tu despliegue privado, más una clave API opcional.
datos
Credenciales cifradas en tu despliegue de SQAI. Filas leídas bajo demanda — nunca copiadas.
Azure Blob
caso
almacenamiento de objetos
conectar
{ type: "azure_blob", … }
autenticación
SQAI_DEPLOYMENT_URL, con SQAI_API_KEY solo si tu despliegue requiere autenticación.
clave
La URL de tu despliegue privado, más una clave API opcional.
datos
Credenciales cifradas en tu despliegue de SQAI. Filas leídas bajo demanda — nunca copiadas.
Redis
caso
NoSQL · grafo · búsqueda
conectar
{ type: "redis", … }
autenticación
SQAI_DEPLOYMENT_URL, con SQAI_API_KEY solo si tu despliegue requiere autenticación.
clave
La URL de tu despliegue privado, más una clave API opcional.
datos
Credenciales cifradas en tu despliegue de SQAI. Filas leídas bajo demanda — nunca copiadas.
Neo4j
caso
NoSQL · grafo · búsqueda
conectar
{ type: "neo4j", … }
autenticación
SQAI_DEPLOYMENT_URL, con SQAI_API_KEY solo si tu despliegue requiere autenticación.
clave
La URL de tu despliegue privado, más una clave API opcional.
datos
Credenciales cifradas en tu despliegue de SQAI. Filas leídas bajo demanda — nunca copiadas.
Elasticsearch
caso
NoSQL · grafo · búsqueda
conectar
{ type: "elasticsearch", … }
autenticación
SQAI_DEPLOYMENT_URL, con SQAI_API_KEY solo si tu despliegue requiere autenticación.
clave
La URL de tu despliegue privado, más una clave API opcional.
datos
Credenciales cifradas en tu despliegue de SQAI. Filas leídas bajo demanda — nunca copiadas.
REST
caso
API
conectar
{ type: "rest", … }
autenticación
SQAI_DEPLOYMENT_URL, con SQAI_API_KEY solo si tu despliegue requiere autenticación.
clave
La URL de tu despliegue privado, más una clave API opcional.
datos
Credenciales cifradas en tu despliegue de SQAI. Filas leídas bajo demanda — nunca copiadas.
GitHub
caso
repositorios de código
conectar
{ type: "github", … }
autenticación
SQAI_DEPLOYMENT_URL, con SQAI_API_KEY solo si tu despliegue requiere autenticación.
clave
La URL de tu despliegue privado, más una clave API opcional.
datos
Credenciales cifradas en tu despliegue de SQAI. Filas leídas bajo demanda — nunca copiadas.
GitLab
caso
repositorios de código
conectar
{ type: "gitlab", … }
autenticación
SQAI_DEPLOYMENT_URL, con SQAI_API_KEY solo si tu despliegue requiere autenticación.
clave
La URL de tu despliegue privado, más una clave API opcional.
datos
Credenciales cifradas en tu despliegue de SQAI. Filas leídas bajo demanda — nunca copiadas.
Bitbucket
caso
repositorios de código
conectar
{ type: "bitbucket", … }
autenticación
SQAI_DEPLOYMENT_URL, con SQAI_API_KEY solo si tu despliegue requiere autenticación.
clave
La URL de tu despliegue privado, más una clave API opcional.
datos
Credenciales cifradas en tu despliegue de SQAI. Filas leídas bajo demanda — nunca copiadas.

El modo se infiere del entorno

SQAI_DEPLOYMENT_URLdeployment

Tu despliegue de SQAI, tu red.

SQAI_API_KEYapi

Tu despliegue autenticado de SQAI.

ninguna definidalocal

Solo en proceso.

Los archivos y SQLite funcionan en cualquier modo. Las bases de datos en vivo requieren un despliegue privado de SQAI. SQAI establece la conexión una vez y permanece activo — sin arranque en frío por consulta.

No es una sincronización. No es una exportación.
No es un puente de terceros.

conectividad directa sobre el protocolo de cable nativo de cada base de datos

IIIEl cable

Directo. Hasta el protocolo.

Tu despliegue de SQAI se conecta directamente, hablando el protocolo de cable nativo de cada base de datos. Las consultas se ejecutan en origen, circunscritas a tu organización — tu base de datos nunca se copia.

fig. — el cable
tu base de datoslas filas permanecen en origen
su propio protocolo de cable — hablado directamente por el despliegue de SQAI
despliegue de SQAIconsultas de solo lectura

En origen, en ámbito.

El SQAI runtime consulta tus datos donde residen, circunscrito a tu organización — y nunca accede más allá de lo que configuraste.

Credenciales selladas.

Cifradas en reposo, con ámbito de organización, usadas únicamente para servir las consultas propias de tu organización. Un conector nunca devuelve su configuración — solo nombre, tipo, estado y el último resultado de prueba.

nunca copiada

El SQAI runtime nunca copia tu base de datos — las filas se leen donde residen.

SELECT 1ok · connector: live

Cada prueba abre una conexión real — SELECT 1 para SQL, un HEAD para almacenamiento de objetos, una obtención de muestra para REST. Un conector está activo solo cuando una conexión real tiene éxito; edita su configuración y vuelve al estado no probado.

El cable insignia · Oracle

Modo Thin. Sin nada que instalar.

El SQAI runtime incluye python-oracledb en modo Thin y se conecta directamente — sin Instant Client, sin proceso de runtime adicional, sin paquete Python extra. El SQAI runtime controla el cable de extremo a extremo: el driver, el pool de conexiones acotado, la verificación de credenciales, la exploración de esquemas y una ruta de obtención por lotes compatible con Arrow — nunca una conexión de reserva oculta fuera del pool.

  • raíces solo SELECT / WITH
  • límite ROWNUM acotado
  • sonda persistida · reutilizada a 0 ms

Redshift responde en PostgreSQL.

Las tablas se leen en origen sobre el protocolo de cable de PostgreSQL — el clúster nunca se copia. Incluso el mensaje de éxito de la prueba nombra PostgreSQL.

Un destino, todos los caminos.

El almacenamiento de objetos y las cargas comparten los mismos parsers — un objeto Parquet en S3 y un archivo Parquet cargado llegan al despliegue de SQAI de forma idéntica.

Misma solicitud → mismas filas, mismo orden · cada acceso auditable · el egreso es una lista de permitidos por despliegue con fallo cerrado

IVLa uniformidad

Downstream no distingue CSV de Snowflake.

Cada fuente devuelve el mismo SqaiSource tipado — mismos campos, mismos pins, mismas garantías. Sustituye el almacén por el archivo y nada downstream cambia.

en proceso"./data/sales.csv"
a través de un despliegue privado de SQAI{ type: "snowflake", connection_string, query }

SqaiSource

misma forma · cada fuente
name"sales"
source_ide135c6f7eec0e846c01c4ef8
fieldsregion · product · revenue · cost · units · order_date
typed_fields2 string · 3 number · 1 date
row_count12
schema_revisione4938027ddf0d2210f019770403efd45d350eac28100902ddd7c5191c9b8cfbe
statusready

Un certificado, sea cual sea la fuente. El código downstream nunca sabe dónde viven las filas.

Registrado una vez.
Nunca redefinido.

reasignar un nombre lanza excepción source_already_registered

VEl pin

Cambia el dato. El replay lo dice.

connect() fija una revisión de esquema en cada plan y cómputo. Un plan almacenado y reproducido contra datos modificados expone el cambio — nunca números silenciosamente distintos.

schema_revision
Fijado en el momento de connect() en cada plan y cómputo que accede a la fuente.
schema_revision_mismatch
Lo que devuelve un replay cuando los datos han cambiado por debajo.
source_already_registered
Las fuentes son inmutables — un nombre nunca puede redirigirse silenciosamente a datos distintos.

provenance.bindings[0]

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

Cada campo vinculado lleva su linaje.

VIPreguntas

Acceso de LLM a bases de datos, respondido.

¿Cómo doy acceso a mi base de datos a un LLM?

Registra la fuente en código con connect(). El modelo nunca ve una cadena de conexión — recibe tres herramientas de solo lectura sobre fuentes tipadas, y la política decide qué fuentes y campos puede tocar.

¿Conectar copia mis datos en algún lugar?

No. Las fuentes en proceso nunca salen de tu máquina. Las fuentes del despliegue privado de SQAI mantienen las credenciales cifradas; las filas se leen bajo demanda y nunca se copian.

¿Es SQAI una sincronización, una exportación o un puente de terceros a mi base de datos?

Nada de eso. La conectividad es directa sobre el protocolo nativo de la base de datos — el despliegue de SQAI consulta tus datos en origen, acotado a tu organización, y nunca los copia.

¿Necesito una API key para conectar datos?

No para archivos, filas en memoria ni SQLite — esos corren en proceso sin clave. El cómputo local usa el sqai login gratuito. Las bases de datos y almacenes en vivo necesitan SQAI_DEPLOYMENT_URL, con SQAI_API_KEY solo si tu despliegue requiere autenticación.

¿Puede el modelo ver mis credenciales?

No. Las credenciales se suministran en tu código en el momento de connect() y se cifran en tu despliegue de SQAI. La entrada de herramientas del modelo lleva intención tipada — sin detalles de conexión, sin campos de política.

¿Oracle está soportado sin instalar un cliente?

Sí. El SQAI runtime incluye un driver Thin-mode integrado, por lo que no hay cliente Oracle que instalar.

¿Qué ocurre cuando cambian los datos subyacentes?

La schema_revision fijada en connect() deja de coincidir, y un replay devuelve schema_revision_mismatch en lugar de números silenciosamente distintos. Reasignar un nombre registrado lanza source_already_registered.

Conecta algo.

Node ≥ 20 · Python ≥ 3.10 · archivos y SQLite no necesitan clave