Chapter · データを接続する
一度の呼び出しでソースを登録し、型付きスキーマを推論し、そのリビジョンをそれに触れるすべてのプランにピン留めする。ファイルと SQLite はインプロセスで動作 — キー不要、データは外に出ない。ライブデータベースはエンジン経由で接続 — 各データベース固有のワイヤープロトコルを直接使用し、認証情報は暗号化、データはコピーされない。
›const sales = await sqai.connect("./data/sales.csv", { name: "sales" })
→ row_count 12 · schema_revision e4938027… · status ready
型付き · ハッシュピン留め · 読み取り専用
IIタイプ一覧
どのドロワーも同じコントラクトに開く：接続方法、必要なもの、外に出るもの。一つ引いてみよ。
インプロセスキー不要 · デーモン不要 · ネットワーク不要
"./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"エンジン経由認証情報暗号化 · データコピーなし
{ 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", … }モードは環境から自動的に判定されます
SQAI_ENGINE_URLself_hosted
自前のエンジン、自前のネットワーク。
SQAI_API_KEYapi
ホスト型エンジン。
いずれも未設定local
プロセス内のみ。
ファイルと SQLite はすべてのモードで動作します。ライブデータベースには api または self_hosted が必要です。エンジンは接続を一度確立した後、常駐デーモンとしてウォーム状態を維持します — クエリごとのコールドスタートはありません。
データベース固有のワイヤープロトコルによる直接接続
IIIワイヤー
エンジンは各データベース固有のワイヤープロトコルで直接接続します。クエリはその場で実行され、組織のスコープ内に限定されます — データベースがコピーされることはありません。
エンジンはデータの所在地でクエリを実行し、組織のスコープ内に限定されます — 設定した範囲を超えてアクセスすることはありません。
保存時に暗号化され、組織スコープで管理され、自組織のクエリ処理にのみ使用されます。コネクターが返すのは名前、タイプ、ステータス、および最終テスト結果のみで、設定内容は返しません。
エンジンはデータベースをコピーしません — 行はその所在地で読み取られます。
›SELECT 1ok · connector: live
テストのたびに実際の接続を確立します — SQL には SELECT 1、オブジェクトストレージには HEAD リクエスト、REST にはサンプルフェッチを使用します。コネクターは実際の接続が成功して初めてライブ状態になります。設定を編集すると未テスト状態に戻ります。
主要ワイヤー · Oracle
エンジンは python-oracledb を Thin モードで同梱し、直接接続します — Instant Client 不要、追加のランタイムプロセス不要、追加の Python パッケージも不要です。エンジンはワイヤーをエンドツーエンドで管理します: ドライバ、有界コネクションプール、認証情報の検証、スキーマブラウズ、Arrow 互換のバッチフェッチパス — 隠れた非プールフォールバック接続は一切ありません。
テーブルは PostgreSQL ワイヤープロトコル経由でその場で読み取られます — クラスターがコピーされることはありません。テスト成功メッセージにも PostgreSQL と表示されます。
オブジェクトストレージとアップロードは同じパーサーを共有します — S3 上の Parquet オブジェクトとアップロードされた Parquet ファイルは、エンジン内で同一として扱われます。
同じリクエスト → 同じ行、同じ順序 · すべてのアクセスが監査可能 · エグレスはデプロイ単位のフェイルクローズ許可リストで制御
IV同一性
すべてのソースは同一の型付き SqaiSource を返す――同じフィールド、同じピン、同じ保証。ウェアハウスをファイルに差し替えても、下流は何も変わらない。
"./data/sales.csv"{ type: "snowflake", connection_string, query }SqaiSource
同一の形状 · すべてのソースソースを問わず、証明書はひとつ。下流のコードは行の在処を知らない。
名前の再バインドは例外をスローする source_already_registered
Vピン
connect() はスキーマリビジョンをすべてのプランと計算にピン留めする。変更されたデータに対してストアドプランをリプレイすると、変更が明示される――数値がサイレントに変わることはない。
schema_revisionschema_revision_mismatchsource_already_registeredprovenance.bindings[0]
source_name"sales"fields["revenue"]schema_revisione4938027…c9b8cfberow_count12input_hash2ea5ede7…478e3212バインドされたすべてのフィールドは、その来歴を持つ。
VIよくある質問
connect() でコード内にソースを登録する。モデルは接続文字列を参照しない――型付きソースに対する読み取り専用の3つのツールを受け取り、どのソースとフィールドに触れられるかはポリシーが決定する。
されない。インプロセスのソースはマシン外に出ない。エンジンのソースは認証情報を暗号化して保持し、行はオンデマンドで読み取られ、コピーされることはない。
いずれでもない。接続はデータベース固有のワイヤプロトコルで直接行われる――エンジンはデータをその場でクエリし、組織のスコープ内に限定し、データベースをコピーしない。
ファイル、インメモリ行、SQLite には不要――これらはアカウントなしでインプロセスで動作する。ライブデータベースとウェアハウスには、ホスト型エンジン用に SQAI_API_KEY、または独自エンジン用に SQAI_ENGINE_URL が必要。
できない。認証情報はコード内の connect() 時に提供され、エンジンで暗号化される。モデルのツール入力が持つのは型付きの意図のみ――接続の詳細もポリシーフィールドも含まれない。
使える。エンジンにはバンドルされた Thin モードドライバが同梱されているため、Oracle クライアントのインストールは不要。
接続時にピン留めされた schema_revision が一致しなくなり、リプレイはサイレントな数値の変化ではなく schema_revision_mismatch を返す。登録済みの名前を再バインドしようとすると source_already_registered がスローされる。