Capitolo · Connetti i tuoi dati

Ogni sorgente.
Un'unica porta d'ingresso.

Una sola chiamata registra una sorgente, inferisce uno schema tipizzato e fissa la sua revisione in ogni piano che la coinvolge. File e SQLite girano in-process — nessuna chiave, nulla esce. I database live si connettono attraverso l'engine — direttamente, tramite il protocollo wire nativo di ciascun database: credenziali cifrate, nessun dato copiato.

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

→ row_count 12 · schema_revision e4938027… · status ready

tipizzato · hash-pinnato · sola lettura

III casi per tipo

Due vassoi. Ventisei cassetti.

Ogni cassetto si apre sullo stesso contratto: come si connette, cosa richiede, cosa esce. Aprirne uno.

In-processnessuna chiave · nessun daemon · nessuna rete

CSV
caso
file
connetti
"./data/sales.csv"
auth
Nessuna. SQAI legge i byte nel tuo processo.
chiave
Senza chiave — nessun account, nessuna carta, l'intera superficie in sola lettura.
dati
Nulla esce dal processo.
TSV
caso
file
connetti
"./data/orders.tsv"
auth
Nessuna. SQAI legge i byte nel tuo processo.
chiave
Senza chiave — nessun account, nessuna carta, l'intera superficie in sola lettura.
dati
Nulla esce dal processo.
JSON
caso
file
connetti
"./data/sales.json"
auth
Nessuna. SQAI legge i byte nel tuo processo.
chiave
Senza chiave — nessun account, nessuna carta, l'intera superficie in sola lettura.
dati
Nulla esce dal processo.
nota
Un percorso o un oggetto.
rows
caso
in memoria
connetti
[{ region: "east", revenue: 512 }, …]
auth
Nessuna. SQAI legge i byte nel tuo processo.
chiave
Senza chiave — nessun account, nessuna carta, l'intera superficie in sola lettura.
dati
Nulla esce dal processo.
{ records }
caso
in memoria
connetti
{ records: [ … ] }
auth
Nessuna. SQAI legge i byte nel tuo processo.
chiave
Senza chiave — nessun account, nessuna carta, l'intera superficie in sola lettura.
dati
Nulla esce dal processo.
SQLite
caso
database embedded
connetti
{ provider: "sqlite", path, table | query }
auth
Nessuna. SQAI legge i byte nel tuo processo.
chiave
Senza chiave — nessun account, nessuna carta, l'intera superficie in sola lettura.
dati
Nulla esce dal processo.
nota
Un database completo, ancora in-process. Specifica una tabella o una query in sola lettura.
Excel
caso
file
connetti
"./data/sales.xlsx"
auth
Nessuna. SQAI legge i byte nel tuo processo.
chiave
Senza chiave — nessun account, nessuna carta, l'intera superficie in sola lettura.
dati
Nulla esce dal processo.
nota
Solo Python.
Parquet
caso
file
connetti
"./data/sales.parquet"
auth
Nessuna. SQAI legge i byte nel tuo processo.
chiave
Senza chiave — nessun account, nessuna carta, l'intera superficie in sola lettura.
dati
Nulla esce dal processo.
nota
Solo Python.

Attraverso l'enginecredenziali cifrate · nessun dato copiato

PostgreSQL
caso
relazionale
connetti
{ type: "postgres", host, port, database, user, password, table | query }
auth
SQAI_API_KEY per il motore hosted, o SQAI_ENGINE_URL per il tuo.
chiave
Una chiave, o l'URL del tuo motore.
dati
Credenziali cifrate nel motore. Righe lette su richiesta — mai copiate.
MySQL
caso
relazionale
connetti
{ type: "mysql", host, port, database, user, password, table | query }
auth
SQAI_API_KEY per il motore hosted, o SQAI_ENGINE_URL per il tuo.
chiave
Una chiave, o l'URL del tuo motore.
dati
Credenziali cifrate nel motore. Righe lette su richiesta — mai copiate.
Oracle
caso
relazionale
connetti
{ type: "oracle", host, port, database, user, password, table | query }
auth
SQAI_API_KEY per il motore hosted, o SQAI_ENGINE_URL per il tuo.
chiave
Una chiave, o l'URL del tuo motore.
dati
Credenziali cifrate nel motore. Righe lette su richiesta — mai copiate.
nota
Driver Thin-mode incluso — nessun client Oracle da installare.
SQL Server
caso
relazionale
connetti
{ type: "mssql", host, port, database, user, password, table | query }
auth
SQAI_API_KEY per il motore hosted, o SQAI_ENGINE_URL per il tuo.
chiave
Una chiave, o l'URL del tuo motore.
dati
Credenziali cifrate nel motore. Righe lette su richiesta — mai copiate.
Snowflake
caso
warehouse
connetti
{ type: "snowflake", connection_string, query }
auth
SQAI_API_KEY per il motore hosted, o SQAI_ENGINE_URL per il tuo.
chiave
Una chiave, o l'URL del tuo motore.
dati
Credenziali cifrate nel motore. Righe lette su richiesta — mai copiate.
BigQuery
caso
warehouse
connetti
{ type: "bigquery", connection_string, query }
auth
SQAI_API_KEY per il motore hosted, o SQAI_ENGINE_URL per il tuo.
chiave
Una chiave, o l'URL del tuo motore.
dati
Credenziali cifrate nel motore. Righe lette su richiesta — mai copiate.
ClickHouse
caso
warehouse
connetti
{ type: "clickhouse", connection_string, query }
auth
SQAI_API_KEY per il motore hosted, o SQAI_ENGINE_URL per il tuo.
chiave
Una chiave, o l'URL del tuo motore.
dati
Credenziali cifrate nel motore. Righe lette su richiesta — mai copiate.
Redshift
caso
warehouse
connetti
{ type: "redshift", connection_string, query }
auth
SQAI_API_KEY per il motore hosted, o SQAI_ENGINE_URL per il tuo.
chiave
Una chiave, o l'URL del tuo motore.
dati
Credenziali cifrate nel motore. Righe lette su richiesta — mai copiate.
S3
caso
archiviazione oggetti
connetti
{ type: "s3", … }
auth
SQAI_API_KEY per il motore hosted, o SQAI_ENGINE_URL per il tuo.
chiave
Una chiave, o l'URL del tuo motore.
dati
Credenziali cifrate nel motore. Righe lette su richiesta — mai copiate.
GCS
caso
archiviazione oggetti
connetti
{ type: "gcs", … }
auth
SQAI_API_KEY per il motore hosted, o SQAI_ENGINE_URL per il tuo.
chiave
Una chiave, o l'URL del tuo motore.
dati
Credenziali cifrate nel motore. Righe lette su richiesta — mai copiate.
Azure Blob
caso
archiviazione oggetti
connetti
{ type: "azure_blob", … }
auth
SQAI_API_KEY per il motore hosted, o SQAI_ENGINE_URL per il tuo.
chiave
Una chiave, o l'URL del tuo motore.
dati
Credenziali cifrate nel motore. Righe lette su richiesta — mai copiate.
Redis
caso
NoSQL · grafi · ricerca
connetti
{ type: "redis", … }
auth
SQAI_API_KEY per il motore hosted, o SQAI_ENGINE_URL per il tuo.
chiave
Una chiave, o l'URL del tuo motore.
dati
Credenziali cifrate nel motore. Righe lette su richiesta — mai copiate.
Neo4j
caso
NoSQL · grafi · ricerca
connetti
{ type: "neo4j", … }
auth
SQAI_API_KEY per il motore hosted, o SQAI_ENGINE_URL per il tuo.
chiave
Una chiave, o l'URL del tuo motore.
dati
Credenziali cifrate nel motore. Righe lette su richiesta — mai copiate.
Elasticsearch
caso
NoSQL · grafi · ricerca
connetti
{ type: "elasticsearch", … }
auth
SQAI_API_KEY per il motore hosted, o SQAI_ENGINE_URL per il tuo.
chiave
Una chiave, o l'URL del tuo motore.
dati
Credenziali cifrate nel motore. Righe lette su richiesta — mai copiate.
REST
caso
API
connetti
{ type: "rest", … }
auth
SQAI_API_KEY per il motore hosted, o SQAI_ENGINE_URL per il tuo.
chiave
Una chiave, o l'URL del tuo motore.
dati
Credenziali cifrate nel motore. Righe lette su richiesta — mai copiate.
GitHub
caso
repository di codice
connetti
{ type: "github", … }
auth
SQAI_API_KEY per il motore hosted, o SQAI_ENGINE_URL per il tuo.
chiave
Una chiave, o l'URL del tuo motore.
dati
Credenziali cifrate nel motore. Righe lette su richiesta — mai copiate.
GitLab
caso
repository di codice
connetti
{ type: "gitlab", … }
auth
SQAI_API_KEY per il motore hosted, o SQAI_ENGINE_URL per il tuo.
chiave
Una chiave, o l'URL del tuo motore.
dati
Credenziali cifrate nel motore. Righe lette su richiesta — mai copiate.
Bitbucket
caso
repository di codice
connetti
{ type: "bitbucket", … }
auth
SQAI_API_KEY per il motore hosted, o SQAI_ENGINE_URL per il tuo.
chiave
Una chiave, o l'URL del tuo motore.
dati
Credenziali cifrate nel motore. Righe lette su richiesta — mai copiate.

La modalità viene dedotta dall'ambiente

SQAI_ENGINE_URLself_hosted

Il tuo motore, la tua rete.

SQAI_API_KEYapi

Il motore hosted.

nessuno dei due impostatolocal

Solo in-process.

File e SQLite funzionano in ogni modalità. I database live richiedono api o self_hosted. Il motore apre una connessione una volta sola, poi rimane attivo — un daemon residente, nessun cold start per query.

Non una sincronizzazione. Non un'esportazione.
Non un bridge di terze parti.

connettività diretta tramite il protocollo wire nativo del database

IIIIl wire

Diretto. Fino al protocollo.

Il motore si connette direttamente, parlando il protocollo wire nativo di ciascun database. Le query vengono eseguite in loco, circoscritte alla tua organizzazione — il tuo database non viene mai copiato.

fig. — il wire
il tuo databasele righe restano in loco
il suo protocollo wire nativo — parlato direttamente dal motore
il motorequery in sola lettura

In loco, in perimetro.

Il motore interroga i tuoi dati dove risiedono, circoscritto alla tua organizzazione — e non va mai oltre ciò che hai configurato.

Credenziali sigillate.

Cifrate a riposo, con scope per organizzazione, usate solo per servire le query della tua organizzazione. Un connettore non restituisce mai la propria configurazione — solo nome, tipo, stato e l'ultimo risultato del test.

mai copiato

Il motore non copia mai il tuo database — le righe vengono lette dove risiedono.

SELECT 1ok · connector: live

Ogni test apre una connessione reale — SELECT 1 per SQL, una HEAD per l'object storage, un fetch campione per REST. Un connettore è attivo solo dopo che una connessione reale ha avuto successo; modifica la sua configurazione e torna allo stato non testato.

Il wire di punta · Oracle

Thin mode. Nulla da installare.

Il motore include python-oracledb in Thin mode e si connette direttamente — nessun Instant Client, nessun processo runtime aggiuntivo, nessun pacchetto Python extra. Il motore gestisce il wire dall'inizio alla fine: il driver, il connection pool limitato, la verifica delle credenziali, la navigazione dello schema e un percorso di fetch batch compatibile con Arrow — mai un fallback su connessione non pooled nascosta.

  • radici solo SELECT / WITH
  • limite ROWNUM vincolato
  • probe persistente · riutilizzato a 0 ms

Redshift risponde in PostgreSQL.

Le tabelle vengono lette in loco tramite il protocollo wire di PostgreSQL — il cluster non viene mai copiato. Persino il messaggio di successo del test cita PostgreSQL.

Un punto d'arrivo, ogni percorso.

Object storage e upload condividono gli stessi parser — un oggetto Parquet in S3 e un file Parquet caricato arrivano nel motore in modo identico.

Stessa richiesta → stesse righe, stesso ordine · ogni accesso verificabile · l'egress è una allowlist per deployment a fail-closed

IVL'uniformità

Downstream non distingue CSV da Snowflake.

Ogni sorgente restituisce lo stesso SqaiSource tipizzato — stessi campi, stessi pin, stesse garanzie. Sostituisci il warehouse al file e nulla cambia a valle.

in-process"./data/sales.csv"
attraverso il motore{ type: "snowflake", connection_string, query }

SqaiSource

stessa forma · ogni sorgente
name"sales"
source_ide135c6f7eec0e846c01c4ef8
fieldsregion · product · revenue · cost · units · order_date
typed_fields2 string · 3 number · 1 date
row_count12
schema_revisione4938027ddf0d2210f019770403efd45d350eac28100902ddd7c5191c9b8cfbe
statusready

Un certificato, qualunque sia la sorgente. Il codice a valle non sa mai dove risiedono le righe.

Registrato una volta.
Mai ridefinito.

riassegnare un nome genera un errore source_already_registered

VIl pin

I dati cambiano. Il replay lo dice.

connect() fissa una revisione dello schema in ogni piano e calcolo. Un piano memorizzato rieseguito su dati modificati espone la variazione — mai numeri silenziosamente diversi.

schema_revision
Fissato al momento della connessione in ogni piano e calcolo che accede alla sorgente.
schema_revision_mismatch
Ciò che un replay restituisce quando i dati sottostanti sono cambiati.
source_already_registered
Le sorgenti sono immutabili — un nome non può mai essere reindirizzato silenziosamente a dati diversi.

provenance.bindings[0]

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

Ogni campo associato porta con sé la propria provenienza.

VIDomande

Accesso LLM ai database: le risposte.

Come concedo a un LLM l'accesso al mio database?

Registra la sorgente nel codice con connect(). Il modello non vede mai una stringa di connessione — riceve tre strumenti in sola lettura su sorgenti tipizzate, e la policy decide quali sorgenti e campi può toccare.

La connessione copia i miei dati da qualche parte?

No. Le sorgenti in-process non lasciano mai la tua macchina. Le sorgenti del motore mantengono le credenziali cifrate; le righe vengono lette su richiesta e non vengono mai copiate.

SQAI è una sincronizzazione, un'esportazione o un bridge di terze parti verso il mio database?

Nessuna delle tre. La connettività è diretta tramite il protocollo wire nativo del database — il motore interroga i tuoi dati in loco, circoscritto alla tua organizzazione, senza mai copiare il database.

Serve una API key per connettere i dati?

Non per file, righe in memoria o SQLite — questi girano in-process senza alcun account. Database e warehouse live richiedono SQAI_API_KEY per il motore hosted, o SQAI_ENGINE_URL per il proprio.

Il modello può vedere le mie credenziali?

No. Le credenziali vengono fornite nel codice al momento di connect() e cifrate nel motore. L'input degli strumenti del modello porta intento tipizzato — nessun dettaglio di connessione, nessun campo di policy.

Oracle è supportato senza installare un client?

Sì. Il motore include un driver Thin-mode integrato, quindi non è necessario installare alcun client Oracle.

Cosa succede quando i dati sottostanti cambiano?

La schema_revision fissata al momento della connessione smette di corrispondere, e un replay restituisce schema_revision_mismatch invece di numeri silenziosamente diversi. Riassegnare un nome già registrato genera source_already_registered.

Connetti qualcosa.

Node ≥ 20 · Python ≥ 3.10 · file & SQLite non richiedono chiave