Python API¶

dosi-engine wheel 把 Dosi 装进 Python 进程，模块名是 dosi_engine。编译器、连接器和错误契约都和命令行、REST API 是同一套，DuckDB 和所有数仓驱动都已内置。

安装¶

需要 Python 3.12+：

$ pip install dosi-engine
$ python -c "import dosi_engine; print(dosi_engine.__version__)"
0.2.1

示例¶

from dosi_engine import Engine, QueryError

engine = Engine(model_path="model.yaml")

engine.metrics()        # [{"name": "revenue", "kind": "aggregate", ...}, ...]

engine.compile(
    {"metrics": ["revenue"], "group_by": [{"field": "orders.status"}]},
    dialect="snowflake",
)                       # {"dialect": "snowflake", "sql": "SELECT ...", ...}

engine.execute(
    {"metrics": ["revenue"], "group_by": [{"field": "orders.status"}],
     "order_by": [{"key": "status"}]},
    db_path="orders.duckdb",
)                       # {"columns": [...], "rows": [{"status": ..., "revenue": ...}], "row_count": 3, ...}

try:
    engine.compile({"metrics": ["revenu"]})
except QueryError as e:
    e.code, e.candidates  # ("unknown_metric", ["revenue", "order_count", ...])

查询和结果的 JSON 与 dosi --format json、REST API 完全一致：这里的查询 dict 就是那边的请求体。

`Engine`¶

Engine(...) 加载、校验并编译一个模型，任何一步失败都抛 ModelError。一个 engine 可以同时服务多个调用；编译和执行期间会释放 GIL。

参数	含义
`model_path` / `model_text`	模型：文件（目录按 catalog 读取）或 YAML 文本
`connections`	数仓连接，dict 形式，键沿用连接配置文件的写法。模块本身从不读取连接配置文件
`pool_size`	每个连接的连接池上限（默认 8）
`mode`	`"datus"`（默认）启用 Datus 扩展；`"basic"` 是严格的标准 Apache Ossie
`ontology_path` / `ontology_text`、`mapping_path` / `mapping_text`	本体及其映射，只能用关键字参数传入

方法	返回
`metrics()`、`datasets()`、`dimensions(metric=None)`	模型的指标、数据集和维度
`metric(name)`、`dataset(name)`	其中一个的完整信息，和 `dosi show` 一样
`compile(query, dialect=None, connection=None, pretty=False)`	指标查询的 SQL，不执行
`execute(query, dialect=None, connection=None, timeout_secs=None, db_path=None)`	查询结果的行
`compile_select(...)`、`select(...)`	明细查询的对应方法
`explain(query)`、`explain_select(query)`	逻辑计划，文本形式
`attribute(request, ...)`	指标在两个时段之间为什么变化，见指标归因
`lineage(redact_sql=False)`	血缘图，见指标血缘
`describe(name=None)`、`paths(source, target)`	本体里的概念，以及概念之间的路径
`warnings`	构造时的警告，例如 basic 模式下被忽略的扩展

execute 不传 connection 时，有标记 default: true 的连接就用它，否则用本地 DuckDB： db_path 指定的文件，或者内存数据库。compile、execute、select 和 attribute 还可以传入 SQL 策略，见 SQL 策略提供方。

错误¶

所有错误都是 OsiError 的子类，带着和命令行、REST JSON 一样的 code、candidates 和 hint：模型加载不了是 ModelError，查询无法规划是 QueryError，数仓执行失败是 ExecuteError。错误码列在错误里。

当前引擎支持什么¶

模块常量报告这个版本实现了什么，内容和 dosi info 相同。生成模型的工具先读这些常量，再决定写哪些 Datus 扩展键。

名称	内容
`__version__`	引擎版本，例如 `'0.2.1'`
`SPEC_VERSION`	Apache Ossie 核心规范版本，例如 `'0.2.0.dev0'`
`DATUS_EXT_VERSION`	Datus 扩展版本，例如 `'1.12'`
`DATUS_EXT`	所有 Datus 扩展键，带引入它的版本和忽略它的代价，见扩展版本
`DIALECTS`	`compile` 接受的 SQL 方言
`CONNECTION_TYPES`	`connections` 接受的连接 `type` 取值
`DATUS_AUTHORING_CONTRACT`、`DATUS_AUTHORING_CONTRACT_DIGEST`	编写模型的完整契约及其摘要

接入 Agent 时，编写契约直接从已安装的引擎取，不要自己另存一份：

import dosi_engine

prompt_yaml = dosi_engine.render_datus_authoring_spec()
digest = dosi_engine.DATUS_AUTHORING_CONTRACT_DIGEST

契约与方言无关：当前使用的 SQL 方言由数据源决定，与引擎无关，需要另外告诉 Agent。契约内容不变，摘要就不变，可以用作提示词缓存的键。

dosi_engine.validate(model_text, mode="datus") 不构造 engine 也能检查模型文本。模型有问题时它不抛异常，而是返回 {"valid", "issues", "compile_errors", "warnings", ...}。

从 `datus_osi_engine` 迁移¶

这个包以前叫 datus-osi-engine（模块 datus_osi_engine），现在叫 dosi-engine（模块 dosi_engine）。环境变量和连接配置文件也一起改了名：OSI_* 改为 DOSI_*， ./osi-connections.yaml 改为 ./dosi-connections.yaml，~/.config/osi/ 改为 ~/.config/dosi/。旧的文件路径仍会作为后备被找到；旧的环境变量不再生效。

Python API¶

安装¶

示例¶

Engine¶

错误¶

当前引擎支持什么¶

从 datus_osi_engine 迁移¶

`Engine`¶

从 `datus_osi_engine` 迁移¶