Chapter · Connect your data
One call registers a source, infers a typed schema, and pins its revision into every plan that touches it. Files and SQLite run in-process — no key, nothing leaves. Live databases connect through the engine — directly, over each database's own wire protocol: credentials encrypted, no data copied.
›const sales = await sqai.connect("./data/sales.csv", { name: "sales" })
→ row_count 12 · schema_revision e4938027… · status ready
typed · hash-pinned · read-only
IIThe type cases
Every drawer opens to the same contract: how it connects, what it needs, what leaves. Pull one.
In-processno key · no daemon · no network
"./data/sales.csv""./data/orders.tsv""./data/sales.json"[{ region: "east", revenue: 512 }, …]{ records: [ … ] }{ provider: "sqlite", path, table | query }"./data/sales.xlsx""./data/sales.parquet"Through the enginecredentials encrypted · no data copied
{ type: "postgres", host, port, database, user, password, table | query }{ type: "mysql", host, port, database, user, password, table | query }{ type: "oracle", host, port, database, user, password, table | query }{ type: "mssql", host, port, database, user, password, table | query }{ type: "snowflake", connection_string, query }{ type: "bigquery", connection_string, query }{ type: "clickhouse", connection_string, query }{ type: "redshift", connection_string, query }{ type: "s3", … }{ type: "gcs", … }{ type: "azure_blob", … }{ type: "redis", … }{ type: "neo4j", … }{ type: "elasticsearch", … }{ type: "rest", … }{ type: "github", … }{ type: "gitlab", … }{ type: "bitbucket", … }Mode is inferred from the environment
SQAI_ENGINE_URLself_hosted
Your engine, your network.
SQAI_API_KEYapi
The hosted engine.
neither setlocal
In-process only.
Files and SQLite work in every mode. Live databases require api or self_hosted. The engine provisions a connection once, then stays warm — a resident daemon, no per-query cold start.
direct connectivity over the database's own wire protocol
IIIThe wire
The engine connects directly, speaking each database's own wire protocol. Queries run in place, scoped to your organization — your database is never copied.
The engine queries your data where it lives, scoped to your organization — and never reaches beyond what you configured.
Encrypted at rest, org-scoped, used only to serve your organization's own queries. A connector never returns its config — only name, type, status, and the last test result.
The engine never copies your database — rows are read where they live.
›SELECT 1ok · connector: live
Every test opens a real connection — SELECT 1 for SQL, a HEAD for object storage, a sample fetch for REST. A connector is live only once a real connection succeeds; edit its config and it drops back to untested.
The flagship wire · Oracle
The engine bundles python-oracledb in Thin mode and connects directly — no Instant Client, no extra runtime process, no added Python package. The engine owns the wire end to end: the driver, the bounded connection pool, credential verification, schema browse, and an Arrow-compatible batch fetch path — never a hidden unpooled fallback connection.
Tables are read in place over the PostgreSQL wire protocol — the cluster is never copied. Even the test success message names PostgreSQL.
Object storage and uploads share the same parsers — a Parquet object in S3 and an uploaded Parquet file land in the engine identically.
Same request → same rows, same order · every access auditable · egress is a fail-closed per-deployment allowlist
IVThe sameness
Every source returns the same typed SqaiSource — same fields, same pins, same guarantees. Swap the warehouse in for the file and nothing downstream changes.
"./data/sales.csv"{ type: "snowflake", connection_string, query }SqaiSource
same shape · every sourceOne certificate, whatever the source. Downstream code never knows where the rows live.
re-binding a name throws source_already_registered
VThe pin
connect() pins a schema revision into every plan and computation. A stored plan replayed against changed data surfaces the change — never silently different numbers.
schema_revisionschema_revision_mismatchsource_already_registeredprovenance.bindings[0]
source_name"sales"fields["revenue"]schema_revisione4938027…c9b8cfberow_count12input_hash2ea5ede7…478e3212Every bound field carries its lineage.
VIQuestions
Register the source in code with connect(). The model never sees a connection string — it gets three read-only tools over typed sources, and policy decides which sources and fields it may touch.
No. In-process sources never leave your machine. Engine sources keep credentials encrypted; rows are read on demand and never copied.
None of those. Connectivity is direct over the database's own wire protocol — the engine queries your data in place, scoped to your organization, and never copies your database.
Not for files, in-memory rows, or SQLite — those run in-process with no account at all. Live databases and warehouses need SQAI_API_KEY for the hosted engine, or SQAI_ENGINE_URL for your own.
No. Credentials are supplied in your code at connect() time and encrypted at the engine. The model’s tool input carries typed intent — no connection details, no policy fields.
Yes. The engine ships a bundled Thin-mode driver, so there is no Oracle client to install.
The schema_revision pinned at connect time stops matching, and a replay surfaces schema_revision_mismatch instead of silently different numbers. Re-binding a registered name throws source_already_registered.