Chapitre · Connect your data

Chaque source.
Une seule entrée.

Un seul appel enregistre une source, infère un schéma typé et épingle sa révision dans chaque plan qui la touche. Les fichiers et SQLite s'exécutent en processus — aucune clé, rien ne sort. Les bases de données actives se connectent via le moteur — directement, via le protocole natif de chaque base : identifiants chiffrés, aucune donnée copiée.

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

→ row_count 12 · schema_revision e4938027… · status ready

typé · épinglé par hash · lecture seule

IILes types de cas

Deux plateaux. Vingt-six tiroirs.

Chaque tiroir s'ouvre sur le même contrat : comment il se connecte, ce dont il a besoin, ce qui sort. Ouvrez-en un.

En processussans clé · sans daemon · sans réseau

CSV
cas
fichier
connexion
"./data/sales.csv"
auth
Aucune. SQAI lit les octets dans votre processus.
clé
Sans clé — aucun compte, aucune carte, surface complète en lecture seule.
données
Rien ne quitte le processus.
TSV
cas
fichier
connexion
"./data/orders.tsv"
auth
Aucune. SQAI lit les octets dans votre processus.
clé
Sans clé — aucun compte, aucune carte, surface complète en lecture seule.
données
Rien ne quitte le processus.
JSON
cas
fichier
connexion
"./data/sales.json"
auth
Aucune. SQAI lit les octets dans votre processus.
clé
Sans clé — aucun compte, aucune carte, surface complète en lecture seule.
données
Rien ne quitte le processus.
note
Un chemin ou un objet.
rows
cas
en mémoire
connexion
[{ region: "east", revenue: 512 }, …]
auth
Aucune. SQAI lit les octets dans votre processus.
clé
Sans clé — aucun compte, aucune carte, surface complète en lecture seule.
données
Rien ne quitte le processus.
{ records }
cas
en mémoire
connexion
{ records: [ … ] }
auth
Aucune. SQAI lit les octets dans votre processus.
clé
Sans clé — aucun compte, aucune carte, surface complète en lecture seule.
données
Rien ne quitte le processus.
SQLite
cas
base embarquée
connexion
{ provider: "sqlite", path, table | query }
auth
Aucune. SQAI lit les octets dans votre processus.
clé
Sans clé — aucun compte, aucune carte, surface complète en lecture seule.
données
Rien ne quitte le processus.
note
Une base complète, toujours en processus. Nommez une table ou une requête en lecture seule.
Excel
cas
fichier
connexion
"./data/sales.xlsx"
auth
Aucune. SQAI lit les octets dans votre processus.
clé
Sans clé — aucun compte, aucune carte, surface complète en lecture seule.
données
Rien ne quitte le processus.
note
Python uniquement.
Parquet
cas
fichier
connexion
"./data/sales.parquet"
auth
Aucune. SQAI lit les octets dans votre processus.
clé
Sans clé — aucun compte, aucune carte, surface complète en lecture seule.
données
Rien ne quitte le processus.
note
Python uniquement.

Via le moteuridentifiants chiffrés · aucune donnée copiée

PostgreSQL
cas
relationnel
connexion
{ type: "postgres", host, port, database, user, password, table | query }
auth
SQAI_API_KEY pour le moteur hébergé, ou SQAI_ENGINE_URL pour le vôtre.
clé
Une clé, ou l'URL de votre propre moteur.
données
Identifiants chiffrés au niveau du moteur. Lignes lues à la demande — jamais copiées.
MySQL
cas
relationnel
connexion
{ type: "mysql", host, port, database, user, password, table | query }
auth
SQAI_API_KEY pour le moteur hébergé, ou SQAI_ENGINE_URL pour le vôtre.
clé
Une clé, ou l'URL de votre propre moteur.
données
Identifiants chiffrés au niveau du moteur. Lignes lues à la demande — jamais copiées.
Oracle
cas
relationnel
connexion
{ type: "oracle", host, port, database, user, password, table | query }
auth
SQAI_API_KEY pour le moteur hébergé, ou SQAI_ENGINE_URL pour le vôtre.
clé
Une clé, ou l'URL de votre propre moteur.
données
Identifiants chiffrés au niveau du moteur. Lignes lues à la demande — jamais copiées.
note
Pilote Thin intégré — aucun client Oracle à installer.
SQL Server
cas
relationnel
connexion
{ type: "mssql", host, port, database, user, password, table | query }
auth
SQAI_API_KEY pour le moteur hébergé, ou SQAI_ENGINE_URL pour le vôtre.
clé
Une clé, ou l'URL de votre propre moteur.
données
Identifiants chiffrés au niveau du moteur. Lignes lues à la demande — jamais copiées.
Snowflake
cas
entrepôt
connexion
{ type: "snowflake", connection_string, query }
auth
SQAI_API_KEY pour le moteur hébergé, ou SQAI_ENGINE_URL pour le vôtre.
clé
Une clé, ou l'URL de votre propre moteur.
données
Identifiants chiffrés au niveau du moteur. Lignes lues à la demande — jamais copiées.
BigQuery
cas
entrepôt
connexion
{ type: "bigquery", connection_string, query }
auth
SQAI_API_KEY pour le moteur hébergé, ou SQAI_ENGINE_URL pour le vôtre.
clé
Une clé, ou l'URL de votre propre moteur.
données
Identifiants chiffrés au niveau du moteur. Lignes lues à la demande — jamais copiées.
ClickHouse
cas
entrepôt
connexion
{ type: "clickhouse", connection_string, query }
auth
SQAI_API_KEY pour le moteur hébergé, ou SQAI_ENGINE_URL pour le vôtre.
clé
Une clé, ou l'URL de votre propre moteur.
données
Identifiants chiffrés au niveau du moteur. Lignes lues à la demande — jamais copiées.
Redshift
cas
entrepôt
connexion
{ type: "redshift", connection_string, query }
auth
SQAI_API_KEY pour le moteur hébergé, ou SQAI_ENGINE_URL pour le vôtre.
clé
Une clé, ou l'URL de votre propre moteur.
données
Identifiants chiffrés au niveau du moteur. Lignes lues à la demande — jamais copiées.
S3
cas
stockage objet
connexion
{ type: "s3", … }
auth
SQAI_API_KEY pour le moteur hébergé, ou SQAI_ENGINE_URL pour le vôtre.
clé
Une clé, ou l'URL de votre propre moteur.
données
Identifiants chiffrés au niveau du moteur. Lignes lues à la demande — jamais copiées.
GCS
cas
stockage objet
connexion
{ type: "gcs", … }
auth
SQAI_API_KEY pour le moteur hébergé, ou SQAI_ENGINE_URL pour le vôtre.
clé
Une clé, ou l'URL de votre propre moteur.
données
Identifiants chiffrés au niveau du moteur. Lignes lues à la demande — jamais copiées.
Azure Blob
cas
stockage objet
connexion
{ type: "azure_blob", … }
auth
SQAI_API_KEY pour le moteur hébergé, ou SQAI_ENGINE_URL pour le vôtre.
clé
Une clé, ou l'URL de votre propre moteur.
données
Identifiants chiffrés au niveau du moteur. Lignes lues à la demande — jamais copiées.
Redis
cas
NoSQL · graphe · recherche
connexion
{ type: "redis", … }
auth
SQAI_API_KEY pour le moteur hébergé, ou SQAI_ENGINE_URL pour le vôtre.
clé
Une clé, ou l'URL de votre propre moteur.
données
Identifiants chiffrés au niveau du moteur. Lignes lues à la demande — jamais copiées.
Neo4j
cas
NoSQL · graphe · recherche
connexion
{ type: "neo4j", … }
auth
SQAI_API_KEY pour le moteur hébergé, ou SQAI_ENGINE_URL pour le vôtre.
clé
Une clé, ou l'URL de votre propre moteur.
données
Identifiants chiffrés au niveau du moteur. Lignes lues à la demande — jamais copiées.
Elasticsearch
cas
NoSQL · graphe · recherche
connexion
{ type: "elasticsearch", … }
auth
SQAI_API_KEY pour le moteur hébergé, ou SQAI_ENGINE_URL pour le vôtre.
clé
Une clé, ou l'URL de votre propre moteur.
données
Identifiants chiffrés au niveau du moteur. Lignes lues à la demande — jamais copiées.
REST
cas
API
connexion
{ type: "rest", … }
auth
SQAI_API_KEY pour le moteur hébergé, ou SQAI_ENGINE_URL pour le vôtre.
clé
Une clé, ou l'URL de votre propre moteur.
données
Identifiants chiffrés au niveau du moteur. Lignes lues à la demande — jamais copiées.
GitHub
cas
dépôts de code
connexion
{ type: "github", … }
auth
SQAI_API_KEY pour le moteur hébergé, ou SQAI_ENGINE_URL pour le vôtre.
clé
Une clé, ou l'URL de votre propre moteur.
données
Identifiants chiffrés au niveau du moteur. Lignes lues à la demande — jamais copiées.
GitLab
cas
dépôts de code
connexion
{ type: "gitlab", … }
auth
SQAI_API_KEY pour le moteur hébergé, ou SQAI_ENGINE_URL pour le vôtre.
clé
Une clé, ou l'URL de votre propre moteur.
données
Identifiants chiffrés au niveau du moteur. Lignes lues à la demande — jamais copiées.
Bitbucket
cas
dépôts de code
connexion
{ type: "bitbucket", … }
auth
SQAI_API_KEY pour le moteur hébergé, ou SQAI_ENGINE_URL pour le vôtre.
clé
Une clé, ou l'URL de votre propre moteur.
données
Identifiants chiffrés au niveau du moteur. Lignes lues à la demande — jamais copiées.

Le mode est déduit de l'environnement

SQAI_ENGINE_URLself_hosted

Votre moteur, votre réseau.

SQAI_API_KEYapi

Le moteur hébergé.

aucun des deux définilocal

En processus uniquement.

Les fichiers et SQLite fonctionnent dans tous les modes. Les bases de données actives requièrent api ou self_hosted. Le moteur établit une connexion une seule fois, puis reste actif — un démon résident, sans démarrage à froid par requête.

Pas une synchronisation. Pas un export.
Pas un pont tiers.

connectivité directe via le protocole filaire natif de la base de données

IIILe protocole

Direct. Au niveau du protocole.

Le moteur se connecte directement, en parlant le protocole filaire natif de chaque base de données. Les requêtes s'exécutent sur place, dans le périmètre de votre organisation — votre base n'est jamais copiée.

fig. — le protocole
votre base de donnéesles lignes restent en place
son propre protocole filaire — parlé directement par le moteur
le moteurrequêtes en lecture seule

Sur place, dans le périmètre.

Le moteur interroge vos données là où elles résident, dans le périmètre de votre organisation — sans jamais dépasser ce que vous avez configuré.

Identifiants scellés.

Chiffrés au repos, limités à l'organisation, utilisés uniquement pour servir les requêtes de votre organisation. Un connecteur ne retourne jamais sa configuration — seulement le nom, le type, le statut et le dernier résultat de test.

jamais copiée

Le moteur ne copie jamais votre base de données — les lignes sont lues là où elles résident.

›SELECT 1ok · connector: live

Chaque test ouvre une vraie connexion — SELECT 1 pour SQL, un HEAD pour le stockage objet, une récupération d'échantillon pour REST. Un connecteur n'est actif qu'une fois la connexion réelle établie ; modifiez sa configuration et il repasse à l'état non testé.

Le protocole phare · Oracle

Mode Thin. Rien à installer.

Le moteur intègre python-oracledb en mode Thin et se connecte directement — sans Instant Client, sans processus d'exécution supplémentaire, sans package Python additionnel. Le moteur maîtrise le protocole de bout en bout : le pilote, le pool de connexions borné, la vérification des identifiants, la navigation dans le schéma et un chemin de récupération par lots compatible Arrow — sans jamais recourir à une connexion de secours non mutualisée.

  • racines SELECT / WITH uniquement
  • limite ROWNUM liée
  • sonde persistée · réutilisée à 0 ms

Redshift répond en PostgreSQL.

Les tables sont lues sur place via le protocole filaire PostgreSQL — le cluster n'est jamais copié. Même le message de succès du test mentionne PostgreSQL.

Un point d'entrée, tous les chemins.

Le stockage objet et les fichiers téléversés partagent les mêmes parseurs — un objet Parquet dans S3 et un fichier Parquet téléversé arrivent dans le moteur de façon identique.

Même requête → mêmes lignes, même ordre · chaque accès auditable · l'egress est une liste d'autorisation fail-closed par déploiement

IVL'uniformité

En aval, CSV et Snowflake sont indiscernables.

Chaque source retourne le même SqaiSource typé — mêmes champs, mêmes pins, mêmes garanties. Remplacez le fichier par l'entrepôt : rien en aval ne change.

en processus"./data/sales.csv"
via le moteur{ type: "snowflake", connection_string, query }

SqaiSource

même forme · toute source
name"sales"
source_ide135c6f7eec0e846c01c4ef8
fieldsregion · product · revenue · cost · units · order_date
typed_fields2 string · 3 number · 1 date
row_count12
schema_revisione4938027ddf0d2210f019770403efd45d350eac28100902ddd7c5191c9b8cfbe
statusready

Un seul certificat, quelle que soit la source. Le code en aval ne sait jamais où résident les lignes.

Enregistré une fois.
Jamais redéfini.

rebinder un nom lève une exception source_already_registered

VLe pin

Les données changent. Le replay le dit.

connect() ancre une révision de schéma dans chaque plan et chaque calcul. Un plan stocké rejoué sur des données modifiées expose le changement — jamais des chiffres silencieusement différents.

schema_revision
Ancré à la connexion dans chaque plan et calcul touchant la source.
schema_revision_mismatch
Ce qu'un replay retourne lorsque les données ont changé sous lui.
source_already_registered
Les sources sont immuables — un nom ne peut jamais être silencieusement redirigé vers d'autres données.

provenance.bindings[0]

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

Chaque champ lié porte sa lignée.

VIQuestions

Accès LLM aux bases de données : les réponses.

Comment donner à un LLM accès à ma base de données ?

Enregistrez la source dans le code avec connect(). Le modèle ne voit jamais de chaîne de connexion — il dispose de trois outils en lecture seule sur des sources typées, et la politique détermine quelles sources et quels champs il peut consulter.

La connexion copie-t-elle mes données quelque part ?

Non. Les sources en processus ne quittent jamais votre machine. Les sources moteur conservent les identifiants chiffrés ; les lignes sont lues à la demande et ne sont jamais copiées.

SQAI est-il une synchronisation, un export ou un pont tiers vers ma base de données ?

Rien de tout cela. La connectivité est directe via le protocole natif de la base de données — le moteur interroge vos données sur place, dans le périmètre de votre organisation, sans jamais les copier.

Ai-je besoin d'une clé API pour connecter des données ?

Pas pour les fichiers, les données en mémoire ou SQLite — ceux-ci s'exécutent en processus sans aucun compte. Les bases de données et entrepôts actifs nécessitent SQAI_API_KEY pour le moteur hébergé, ou SQAI_ENGINE_URL pour le vôtre.

Le modèle peut-il voir mes identifiants ?

Non. Les identifiants sont fournis dans votre code au moment de connect() et chiffrés au niveau du moteur. L'entrée outil du modèle porte une intention typée — aucun détail de connexion, aucun champ de politique.

Oracle est-il pris en charge sans installer de client ?

Oui. Le moteur embarque un pilote Thin-mode intégré — aucun client Oracle à installer.

Que se passe-t-il lorsque les données sous-jacentes changent ?

La schema_revision ancrée à la connexion cesse de correspondre, et un replay remonte schema_revision_mismatch plutôt que des chiffres silencieusement différents. Rebinder un nom enregistré lève source_already_registered.

Connectez quelque chose.

Node ≥ 20 · Python ≥ 3.10 · fichiers & SQLite sans clé

Lire la documentation →