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 del motor — 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 — sin cuenta, sin tarjeta, superficie completa de solo lectura.
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 — sin cuenta, sin tarjeta, superficie completa de solo lectura.
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 — sin cuenta, sin tarjeta, superficie completa de solo lectura.
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 — sin cuenta, sin tarjeta, superficie completa de solo lectura.
datos
Nada sale del proceso.
{ records }
caso
en memoria
conectar
{ records: [ … ] }
autenticación
Ninguna. SQAI lee los bytes en tu proceso.
clave
Sin clave — sin cuenta, sin tarjeta, superficie completa de solo lectura.
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 — sin cuenta, sin tarjeta, superficie completa de solo lectura.
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 — sin cuenta, sin tarjeta, superficie completa de solo lectura.
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 — sin cuenta, sin tarjeta, superficie completa de solo lectura.
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_API_KEY para el motor alojado, o SQAI_ENGINE_URL para el tuyo.
clave
Una clave, o la URL de tu propio motor.
datos
Credenciales cifradas en el motor. Filas leídas bajo demanda — nunca copiadas.
MySQL
caso
relacional
conectar
{ type: "mysql", host, port, database, user, password, table | query }
autenticación
SQAI_API_KEY para el motor alojado, o SQAI_ENGINE_URL para el tuyo.
clave
Una clave, o la URL de tu propio motor.
datos
Credenciales cifradas en el motor. Filas leídas bajo demanda — nunca copiadas.
Oracle
caso
relacional
conectar
{ type: "oracle", host, port, database, user, password, table | query }
autenticación
SQAI_API_KEY para el motor alojado, o SQAI_ENGINE_URL para el tuyo.
clave
Una clave, o la URL de tu propio motor.
datos
Credenciales cifradas en el motor. 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_API_KEY para el motor alojado, o SQAI_ENGINE_URL para el tuyo.
clave
Una clave, o la URL de tu propio motor.
datos
Credenciales cifradas en el motor. Filas leídas bajo demanda — nunca copiadas.
Snowflake
caso
almacén de datos
conectar
{ type: "snowflake", connection_string, query }
autenticación
SQAI_API_KEY para el motor alojado, o SQAI_ENGINE_URL para el tuyo.
clave
Una clave, o la URL de tu propio motor.
datos
Credenciales cifradas en el motor. Filas leídas bajo demanda — nunca copiadas.
BigQuery
caso
almacén de datos
conectar
{ type: "bigquery", connection_string, query }
autenticación
SQAI_API_KEY para el motor alojado, o SQAI_ENGINE_URL para el tuyo.
clave
Una clave, o la URL de tu propio motor.
datos
Credenciales cifradas en el motor. Filas leídas bajo demanda — nunca copiadas.
ClickHouse
caso
almacén de datos
conectar
{ type: "clickhouse", connection_string, query }
autenticación
SQAI_API_KEY para el motor alojado, o SQAI_ENGINE_URL para el tuyo.
clave
Una clave, o la URL de tu propio motor.
datos
Credenciales cifradas en el motor. Filas leídas bajo demanda — nunca copiadas.
Redshift
caso
almacén de datos
conectar
{ type: "redshift", connection_string, query }
autenticación
SQAI_API_KEY para el motor alojado, o SQAI_ENGINE_URL para el tuyo.
clave
Una clave, o la URL de tu propio motor.
datos
Credenciales cifradas en el motor. Filas leídas bajo demanda — nunca copiadas.
S3
caso
almacenamiento de objetos
conectar
{ type: "s3", … }
autenticación
SQAI_API_KEY para el motor alojado, o SQAI_ENGINE_URL para el tuyo.
clave
Una clave, o la URL de tu propio motor.
datos
Credenciales cifradas en el motor. Filas leídas bajo demanda — nunca copiadas.
GCS
caso
almacenamiento de objetos
conectar
{ type: "gcs", … }
autenticación
SQAI_API_KEY para el motor alojado, o SQAI_ENGINE_URL para el tuyo.
clave
Una clave, o la URL de tu propio motor.
datos
Credenciales cifradas en el motor. Filas leídas bajo demanda — nunca copiadas.
Azure Blob
caso
almacenamiento de objetos
conectar
{ type: "azure_blob", … }
autenticación
SQAI_API_KEY para el motor alojado, o SQAI_ENGINE_URL para el tuyo.
clave
Una clave, o la URL de tu propio motor.
datos
Credenciales cifradas en el motor. Filas leídas bajo demanda — nunca copiadas.
Redis
caso
NoSQL · grafo · búsqueda
conectar
{ type: "redis", … }
autenticación
SQAI_API_KEY para el motor alojado, o SQAI_ENGINE_URL para el tuyo.
clave
Una clave, o la URL de tu propio motor.
datos
Credenciales cifradas en el motor. Filas leídas bajo demanda — nunca copiadas.
Neo4j
caso
NoSQL · grafo · búsqueda
conectar
{ type: "neo4j", … }
autenticación
SQAI_API_KEY para el motor alojado, o SQAI_ENGINE_URL para el tuyo.
clave
Una clave, o la URL de tu propio motor.
datos
Credenciales cifradas en el motor. Filas leídas bajo demanda — nunca copiadas.
Elasticsearch
caso
NoSQL · grafo · búsqueda
conectar
{ type: "elasticsearch", … }
autenticación
SQAI_API_KEY para el motor alojado, o SQAI_ENGINE_URL para el tuyo.
clave
Una clave, o la URL de tu propio motor.
datos
Credenciales cifradas en el motor. Filas leídas bajo demanda — nunca copiadas.
REST
caso
API
conectar
{ type: "rest", … }
autenticación
SQAI_API_KEY para el motor alojado, o SQAI_ENGINE_URL para el tuyo.
clave
Una clave, o la URL de tu propio motor.
datos
Credenciales cifradas en el motor. Filas leídas bajo demanda — nunca copiadas.
GitHub
caso
repositorios de código
conectar
{ type: "github", … }
autenticación
SQAI_API_KEY para el motor alojado, o SQAI_ENGINE_URL para el tuyo.
clave
Una clave, o la URL de tu propio motor.
datos
Credenciales cifradas en el motor. Filas leídas bajo demanda — nunca copiadas.
GitLab
caso
repositorios de código
conectar
{ type: "gitlab", … }
autenticación
SQAI_API_KEY para el motor alojado, o SQAI_ENGINE_URL para el tuyo.
clave
Una clave, o la URL de tu propio motor.
datos
Credenciales cifradas en el motor. Filas leídas bajo demanda — nunca copiadas.
Bitbucket
caso
repositorios de código
conectar
{ type: "bitbucket", … }
autenticación
SQAI_API_KEY para el motor alojado, o SQAI_ENGINE_URL para el tuyo.
clave
Una clave, o la URL de tu propio motor.
datos
Credenciales cifradas en el motor. Filas leídas bajo demanda — nunca copiadas.

El modo se infiere del entorno

SQAI_ENGINE_URLself_hosted

Tu motor, tu red.

SQAI_API_KEYapi

El motor alojado.

ninguna definidalocal

Solo en proceso.

Los archivos y SQLite funcionan en cualquier modo. Las bases de datos en vivo requieren api o self_hosted. El motor establece la conexión una vez y permanece activo — un daemon residente, 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.

El motor 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 motor
el motorconsultas de solo lectura

En origen, en ámbito.

El motor 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 motor 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 motor incluye python-oracledb en modo Thin y se conecta directamente — sin Instant Client, sin proceso de runtime adicional, sin paquete Python extra. El motor 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 motor 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 del motor{ 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 motor 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 motor 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 ninguna cuenta. Las bases de datos y almacenes en vivo necesitan SQAI_API_KEY para el motor alojado, o SQAI_ENGINE_URL para el propio.

¿Puede el modelo ver mis credenciales?

No. Las credenciales se suministran en tu código en el momento de connect() y se cifran en el motor. 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 motor 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