Глава · Подключить данные

Любой источник.
Один вход.

Один вызов регистрирует источник, выводит типизированную схему и фиксирует её ревизию в каждом плане, который её затрагивает. Файлы и SQLite работают внутри процесса — без ключей, ничего не покидает среду. Живые базы данных подключаются через движок напрямую, по собственному проводному протоколу каждой базы: учётные данные зашифрованы, данные не копируются.

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

→ row_count 12 · schema_revision e4938027… · status ready

типизировано · хеш-зафиксировано · только чтение

IIТипы источников

Два лотка. Двадцать шесть ячеек.

Каждая ячейка открывается по одному контракту: как подключается, что требует, что покидает среду. Откройте любую.

Внутри процессабез ключа · без демона · без сети

CSV
случай
файл
подключение
"./data/sales.csv"
авторизация
Не требуется. SQAI читает байты внутри вашего процесса.
ключ
Без ключа — без аккаунта, без карты, полный доступ только для чтения.
данные
Ничего не покидает процесс.
TSV
случай
файл
подключение
"./data/orders.tsv"
авторизация
Не требуется. SQAI читает байты внутри вашего процесса.
ключ
Без ключа — без аккаунта, без карты, полный доступ только для чтения.
данные
Ничего не покидает процесс.
JSON
случай
файл
подключение
"./data/sales.json"
авторизация
Не требуется. SQAI читает байты внутри вашего процесса.
ключ
Без ключа — без аккаунта, без карты, полный доступ только для чтения.
данные
Ничего не покидает процесс.
примечание
Путь или объект.
rows
случай
в памяти
подключение
[{ region: "east", revenue: 512 }, …]
авторизация
Не требуется. SQAI читает байты внутри вашего процесса.
ключ
Без ключа — без аккаунта, без карты, полный доступ только для чтения.
данные
Ничего не покидает процесс.
{ records }
случай
в памяти
подключение
{ records: [ … ] }
авторизация
Не требуется. SQAI читает байты внутри вашего процесса.
ключ
Без ключа — без аккаунта, без карты, полный доступ только для чтения.
данные
Ничего не покидает процесс.
SQLite
случай
встроенная база данных
подключение
{ provider: "sqlite", path, table | query }
авторизация
Не требуется. SQAI читает байты внутри вашего процесса.
ключ
Без ключа — без аккаунта, без карты, полный доступ только для чтения.
данные
Ничего не покидает процесс.
примечание
Полноценная база данных, работающая внутри процесса. Укажите таблицу или запрос только для чтения.
Excel
случай
файл
подключение
"./data/sales.xlsx"
авторизация
Не требуется. SQAI читает байты внутри вашего процесса.
ключ
Без ключа — без аккаунта, без карты, полный доступ только для чтения.
данные
Ничего не покидает процесс.
примечание
Только Python.
Parquet
случай
файл
подключение
"./data/sales.parquet"
авторизация
Не требуется. SQAI читает байты внутри вашего процесса.
ключ
Без ключа — без аккаунта, без карты, полный доступ только для чтения.
данные
Ничего не покидает процесс.
примечание
Только Python.

Через движокучётные данные зашифрованы · данные не копируются

PostgreSQL
случай
реляционная
подключение
{ type: "postgres", host, port, database, user, password, table | query }
авторизация
SQAI_API_KEY для размещённого движка или SQAI_ENGINE_URL для собственного.
ключ
Ключ или URL вашего собственного движка.
данные
Учётные данные зашифрованы на стороне движка. Строки читаются по запросу — никогда не копируются.
MySQL
случай
реляционная
подключение
{ type: "mysql", host, port, database, user, password, table | query }
авторизация
SQAI_API_KEY для размещённого движка или SQAI_ENGINE_URL для собственного.
ключ
Ключ или URL вашего собственного движка.
данные
Учётные данные зашифрованы на стороне движка. Строки читаются по запросу — никогда не копируются.
Oracle
случай
реляционная
подключение
{ type: "oracle", host, port, database, user, password, table | query }
авторизация
SQAI_API_KEY для размещённого движка или SQAI_ENGINE_URL для собственного.
ключ
Ключ или URL вашего собственного движка.
данные
Учётные данные зашифрованы на стороне движка. Строки читаются по запросу — никогда не копируются.
примечание
Встроенный драйвер в режиме Thin — клиент Oracle не требуется.
SQL Server
случай
реляционная
подключение
{ type: "mssql", host, port, database, user, password, table | query }
авторизация
SQAI_API_KEY для размещённого движка или SQAI_ENGINE_URL для собственного.
ключ
Ключ или URL вашего собственного движка.
данные
Учётные данные зашифрованы на стороне движка. Строки читаются по запросу — никогда не копируются.
Snowflake
случай
хранилище данных
подключение
{ type: "snowflake", connection_string, query }
авторизация
SQAI_API_KEY для размещённого движка или SQAI_ENGINE_URL для собственного.
ключ
Ключ или URL вашего собственного движка.
данные
Учётные данные зашифрованы на стороне движка. Строки читаются по запросу — никогда не копируются.
BigQuery
случай
хранилище данных
подключение
{ type: "bigquery", connection_string, query }
авторизация
SQAI_API_KEY для размещённого движка или SQAI_ENGINE_URL для собственного.
ключ
Ключ или URL вашего собственного движка.
данные
Учётные данные зашифрованы на стороне движка. Строки читаются по запросу — никогда не копируются.
ClickHouse
случай
хранилище данных
подключение
{ type: "clickhouse", connection_string, query }
авторизация
SQAI_API_KEY для размещённого движка или SQAI_ENGINE_URL для собственного.
ключ
Ключ или URL вашего собственного движка.
данные
Учётные данные зашифрованы на стороне движка. Строки читаются по запросу — никогда не копируются.
Redshift
случай
хранилище данных
подключение
{ type: "redshift", connection_string, query }
авторизация
SQAI_API_KEY для размещённого движка или SQAI_ENGINE_URL для собственного.
ключ
Ключ или URL вашего собственного движка.
данные
Учётные данные зашифрованы на стороне движка. Строки читаются по запросу — никогда не копируются.
S3
случай
объектное хранилище
подключение
{ type: "s3", … }
авторизация
SQAI_API_KEY для размещённого движка или SQAI_ENGINE_URL для собственного.
ключ
Ключ или URL вашего собственного движка.
данные
Учётные данные зашифрованы на стороне движка. Строки читаются по запросу — никогда не копируются.
GCS
случай
объектное хранилище
подключение
{ type: "gcs", … }
авторизация
SQAI_API_KEY для размещённого движка или SQAI_ENGINE_URL для собственного.
ключ
Ключ или URL вашего собственного движка.
данные
Учётные данные зашифрованы на стороне движка. Строки читаются по запросу — никогда не копируются.
Azure Blob
случай
объектное хранилище
подключение
{ type: "azure_blob", … }
авторизация
SQAI_API_KEY для размещённого движка или SQAI_ENGINE_URL для собственного.
ключ
Ключ или URL вашего собственного движка.
данные
Учётные данные зашифрованы на стороне движка. Строки читаются по запросу — никогда не копируются.
Redis
случай
NoSQL · граф · поиск
подключение
{ type: "redis", … }
авторизация
SQAI_API_KEY для размещённого движка или SQAI_ENGINE_URL для собственного.
ключ
Ключ или URL вашего собственного движка.
данные
Учётные данные зашифрованы на стороне движка. Строки читаются по запросу — никогда не копируются.
Neo4j
случай
NoSQL · граф · поиск
подключение
{ type: "neo4j", … }
авторизация
SQAI_API_KEY для размещённого движка или SQAI_ENGINE_URL для собственного.
ключ
Ключ или URL вашего собственного движка.
данные
Учётные данные зашифрованы на стороне движка. Строки читаются по запросу — никогда не копируются.
Elasticsearch
случай
NoSQL · граф · поиск
подключение
{ type: "elasticsearch", … }
авторизация
SQAI_API_KEY для размещённого движка или SQAI_ENGINE_URL для собственного.
ключ
Ключ или URL вашего собственного движка.
данные
Учётные данные зашифрованы на стороне движка. Строки читаются по запросу — никогда не копируются.
REST
случай
API
подключение
{ type: "rest", … }
авторизация
SQAI_API_KEY для размещённого движка или SQAI_ENGINE_URL для собственного.
ключ
Ключ или URL вашего собственного движка.
данные
Учётные данные зашифрованы на стороне движка. Строки читаются по запросу — никогда не копируются.
GitHub
случай
репозитории кода
подключение
{ type: "github", … }
авторизация
SQAI_API_KEY для размещённого движка или SQAI_ENGINE_URL для собственного.
ключ
Ключ или URL вашего собственного движка.
данные
Учётные данные зашифрованы на стороне движка. Строки читаются по запросу — никогда не копируются.
GitLab
случай
репозитории кода
подключение
{ type: "gitlab", … }
авторизация
SQAI_API_KEY для размещённого движка или SQAI_ENGINE_URL для собственного.
ключ
Ключ или URL вашего собственного движка.
данные
Учётные данные зашифрованы на стороне движка. Строки читаются по запросу — никогда не копируются.
Bitbucket
случай
репозитории кода
подключение
{ type: "bitbucket", … }
авторизация
SQAI_API_KEY для размещённого движка или SQAI_ENGINE_URL для собственного.
ключ
Ключ или URL вашего собственного движка.
данные
Учётные данные зашифрованы на стороне движка. Строки читаются по запросу — никогда не копируются.

Режим определяется автоматически по окружению

SQAI_ENGINE_URLself_hosted

Ваш движок, ваша сеть.

SQAI_API_KEYapi

Размещённый движок.

ни то ни другое не заданоlocal

Только внутри процесса.

Файлы и SQLite работают в любом режиме. Живые базы данных требуют api или self_hosted. Движок устанавливает соединение один раз и остаётся активным — постоянный демон без холодного старта на каждый запрос.

Не синхронизация. Не экспорт.
Не сторонний мост.

прямое подключение по собственному проводному протоколу базы данных

IIIПротокол

Напрямую. До уровня протокола.

Движок подключается напрямую, используя собственный проводной протокол каждой базы данных. Запросы выполняются на месте, в рамках вашей организации — база данных никогда не копируется.

рис. — протокол
ваша база данныхстроки остаются на месте
собственный проводной протокол — используется движком напрямую
движокзапросы только для чтения

На месте, в рамках доступа.

Движок запрашивает данные там, где они хранятся, в рамках вашей организации — и никогда не выходит за пределы настроенного доступа.

Учётные данные защищены.

Зашифрованы в хранилище, ограничены организацией, используются только для обслуживания её запросов. Коннектор никогда не возвращает свою конфигурацию — только имя, тип, статус и результат последнего теста.

никогда не копируется

Движок никогда не копирует вашу базу данных — строки читаются там, где они хранятся.

›SELECT 1ok · connector: live

Каждый тест открывает реальное соединение — SELECT 1 для SQL, HEAD-запрос для объектного хранилища, выборку образца для REST. Коннектор считается активным только после успешного реального соединения; при изменении конфигурации он возвращается в статус непроверенного.

Флагманский протокол · Oracle

Режим Thin. Ничего устанавливать не нужно.

Движок включает python-oracledb в режиме Thin и подключается напрямую — без Instant Client, без дополнительного процесса среды выполнения, без лишних Python-пакетов. Движок полностью контролирует проводной уровень: драйвер, ограниченный пул соединений, проверку учётных данных, просмотр схемы и путь пакетной выборки, совместимый с Arrow — без скрытых непулируемых резервных соединений.

  • только корни SELECT / WITH
  • ограничение ROWNUM с привязкой
  • сохранённый зонд · повторное использование за 0 мс

Redshift отвечает по протоколу PostgreSQL.

Таблицы читаются на месте по проводному протоколу PostgreSQL — кластер никогда не копируется. Даже сообщение об успешном тесте называет PostgreSQL.

Один путь приёма — любой источник.

Объектное хранилище и загружаемые файлы используют одни и те же парсеры — объект Parquet в S3 и загруженный файл Parquet попадают в движок одинаково.

Один запрос → одни строки, один порядок · каждый доступ поддаётся аудиту · исходящий трафик — список разрешений на уровне развёртывания с отказом по умолчанию

IVЕдинообразие

Downstream не отличит CSV от Snowflake.

Каждый источник возвращает один и тот же типизированный SqaiSource — одни поля, одни пины, одни гарантии. Замените файл на хранилище — downstream не заметит разницы.

в процессе"./data/sales.csv"
через движок{ type: "snowflake", connection_string, query }

SqaiSource

единая форма · любой источник
name"sales"
source_ide135c6f7eec0e846c01c4ef8
fieldsregion · product · revenue · cost · units · order_date
typed_fields2 string · 3 number · 1 date
row_count12
schema_revisione4938027ddf0d2210f019770403efd45d350eac28100902ddd7c5191c9b8cfbe
statusready

Один сертификат — для любого источника. Downstream-код никогда не знает, где хранятся строки.

Зарегистрировано однажды.
Никогда не переопределяется.

повторная привязка имени вызывает ошибку source_already_registered

VПин

Данные изменились — воспроизведение это покажет.

connect() фиксирует ревизию схемы в каждом плане и вычислении. Сохранённый план, воспроизведённый на изменившихся данных, явно сигнализирует об изменении — никаких молчаливых расхождений в числах.

schema_revision
Фиксируется в момент connect() в каждом плане и вычислении, обращающемся к источнику.
schema_revision_mismatch
Возвращается при воспроизведении, если данные изменились.
source_already_registered
Источники неизменяемы — имя нельзя тихо перенаправить на другие данные.

provenance.bindings[0]

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

Каждое привязанное поле несёт свою родословную.

VIВопросы

Доступ LLM к базам данных — ответы.

Как предоставить LLM доступ к моей базе данных?

Зарегистрируйте источник в коде через connect(). Модель никогда не видит строку подключения — она получает три инструмента только для чтения над типизированными источниками, а политика определяет, к каким источникам и полям она может обращаться.

При подключении мои данные куда-то копируются?

Нет. Источники в процессе не покидают вашу машину. Источники через движок хранят учётные данные в зашифрованном виде; строки читаются по требованию и никогда не копируются.

SQAI — это синхронизация, экспорт или сторонний мост к моей базе данных?

Ничего из перечисленного. Подключение прямое, по собственному протоколу базы данных — движок запрашивает ваши данные на месте, в рамках вашей организации, и никогда не копирует базу.

Нужен ли API-ключ для подключения данных?

Для файлов, данных в памяти и SQLite — нет: они работают в процессе без какой-либо учётной записи. Для живых баз данных и хранилищ нужен SQAI_API_KEY для размещённого движка или SQAI_ENGINE_URL для собственного.

Может ли модель видеть мои учётные данные?

Нет. Учётные данные передаются в вашем коде в момент connect() и шифруются на движке. Входные данные инструмента модели содержат типизированное намерение — никаких деталей подключения, никаких полей политики.

Поддерживается ли Oracle без установки клиента?

Да. Движок поставляется со встроенным драйвером в режиме Thin — устанавливать клиент Oracle не нужно.

Что происходит при изменении исходных данных?

schema_revision, зафиксированная в момент connect(), перестаёт совпадать, и воспроизведение возвращает schema_revision_mismatch вместо молчаливо изменившихся чисел. Повторная привязка зарегистрированного имени вызывает source_already_registered.

Подключите источник.

Node ≥ 20 · Python ≥ 3.10 · файлы и SQLite не требуют ключа

Документация →