跳转至

安装 Dosi

几分钟就能让 dosi 命令跑起来。跟着做完，会得到可执行文件，并验证它能读模型。

目前需要从源码构建

Dosi 还在 1.0 之前，暂不提供预编译的可执行文件，需要用 Rust 从源码构建。 就一句 cargo build，默认构建除了 Rust 什么都不需要： 本地 DuckDB 引擎已经内置，不装数据库也能立刻跑真实查询。

前置条件

  • Rust（stable，1.75+）。用 rustup 安装： 
    $ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
  • Git，用来克隆仓库。
  • （可选） Python 3.12+，只有要用 Python 绑定时才需要。

上手不需要任何数据库，默认构建自带进程内 DuckDB。

构建 CLI

$ git clone https://github.com/Datus-ai/osi-engine.git
$ cd dosi-engine
$ cargo build --release

可执行文件生成在 target/release/dosi。加进 PATH，或者就地运行：

$ ./target/release/dosi --help
# or, without copying it anywhere:
$ cargo run --release --bin dosi -- --help

文档里的示例为求简洁一律写作 dosi …。没加进 PATH 的话， 请读作 ./target/release/dosi …。

验证是否可用

拿一份内置的示例模型校验一下：

$ dosi validate --model fixtures/orders/model.yaml
✓ 1 semantic model(s) valid

出现这一行，就可以去看第一个指标查询教程了。

选择要构建的内容（数仓）

默认构建只能连本地 DuckDB，学习和编译 SQL 够用了。要执行到真实数仓上， 按需带上对应 feature 构建，可执行文件才不会臃肿：

要查询的数仓 构建时加上
DuckDB（本地，内置） （默认 —— 无需额外参数）
MySQL、TiDB、StarRocks、Doris --features exec-mysql
Postgres --features exec-postgres
Hologres --features exec-hologres
GaussDB / openGauss --features exec-gaussdb
Oracle --features exec-oracle
ClickHouse、Trino --features exec-http
Snowflake --features exec-snowflake
全部 --features exec-all

比如同时支持 Postgres 和 ClickHouse：

$ cargo build --release --features "exec-postgres exec-http"

各数仓的连接配置（主机、凭据、TLS）见连接数仓。 这些 feature 只影响 --execute；不带它们也照样能为任意方言编译 SQL。

可选：Python 绑定

想从 Python 调用 Dosi（模块名 dosi_engine），用 maturin 构建一个 wheel，需要 Python 3.12+：

$ cd crates/dosi-py
$ PYO3_PYTHON=$(command -v python3.12) uvx maturin build --release -o ../../target/wheels
$ pip install ../../target/wheels/dosi_engine-*.whl

快速检查：

$ python -c "from dosi_engine import Engine; print('ok')"
ok

Python API 与 CLI 一一对应：构造 Engine(model_path=…)，再调用 .metrics()、.compile(...)、.execute(...)。（专门的 Python API 参考页在计划中。）

模块级常量说明这个构建实现了哪些能力，内容与 dosi info 一致。 生成模型的工具在决定输出哪些 Datus 扩展键之前，应该先读它：

>>> import dosi_engine
>>> dosi_engine.SPEC_VERSION          # the OSI core spec
'0.2.0.dev0'
>>> dosi_engine.DATUS_EXT_VERSION     # the Datus extension version
'1.1'
>>> [k["key"] for k in dosi_engine.DATUS_EXT["keys"]]
['join_type', 'fill_nulls_with', 'time_dimension', 'time_granularity', 'dataset']

DATUS_EXT["keys"] 的每一项还带有引入它的版本号，以及忽略它的代价，见 datus-extensions.md。

从 datus_osi_engine 迁移过来

本项目此前叫 osi-engine，Python 包名也随之改动： datus-osi-engine / datus_osi_engine 现已改为 dosi-engine / dosi_engine。 新代码直接 import dosi_engine 即可。

还有消费方在导入旧模块（比如 datus-semantic-osi-engine 适配器）也不必改动。 crates/dosi-py/shim/ 会以旧名 datus-osi-engine 构建一个兼容垫片， 它依赖 dosi-engine 并重新导出为 datus_osi_engine，导入时抛出 DeprecationWarning：

$ pip install ./crates/dosi-py/shim          # after installing the dosi_engine wheel
$ python -W once -c "import datus_osi_engine"
DeprecationWarning: datus-osi-engine has been renamed to dosi-engine; import
dosi_engine instead (this compatibility shim will be removed in a future release)

（用 -W once 是因为在 __main__ 之外 Python 默认隐藏 DeprecationWarning。）

垫片只在仓库里构建，不会发布，wheel 流水线只发 dosi-engine。 它会在未来某个版本移除，请当作迁移窗口，而不是永久别名。

环境变量和连接配置文件也一并改名：OSI_* → DOSI_*、 ./osi-connections.yaml → ./dosi-connections.yaml、 ~/.config/osi/ → ~/.config/dosi/。旧文件路径仍会作为回退被发现 （connectors.md），旧环境变量则不会。 OSSIE_DIR 保持不变，"OSI" 指的仍是规范本身。

下一步