内容
义 Rails
[](https://pypi.org/project/semantic/) [ [![Docs](https://img.shields.io/badge/docs--rails.comf766ehttps://semantic-rails.com<p align="center"><ahttps://semantic"><picture><="(prefers-color-scheme: dark)" srcset="website/assets/images/logo-readme-dark.svg"><source media="(prefers-color-scheme)" srcset="website/assets/images/logo-readme-light.svg"><img src="website/assets/images/logo-readme-light.svg" alt="Semantic Rails" width="520></a></ 如果智能查询之前无法执行 → 检查 → 计划/构建选项 → 有效值 → 验证 → → 执行`它就没有语 — 它只是一个注册表的 SQL。Semantic Rails智能代理的运行时，它使得这个循环是Semantic Rails 是一个-2.0的、面向的语义了一个 MCP 服务器（stdio + HTTP）和/JSON API都是一个单独的可表面。建模错误 — 未知指标、维度不匹配、无效过滤器、策略冲突 — 是结构化的信封，其中包含`恢复提示`和`最近匹配`；传输级错误（无效 JSON、缺少身份验证、未路由路径）使用一个更精简的信封，带有`代码`和`消息`。所有非主题意图都通过`发现`和`计划`中的相关性底线路由，然后运行时才会回答。DuckDB 在本地运行，无；Snowflake、Postgres、BigQuery、Databricks、Athena、ClickHouse、MotherDuckLake 通过可选驱动程序连接。
```bash
pip install semantic-rails
semantic-rails packages 出捆绑的 jaffle_shop 证明包
semantic-rails query --package jaffle_shop-json '{
"version,
"select": [{"expression": {"measure": "measure.jaffle.revenue_usdas": "red"}],
"group_by": ["affle_store_name "order_by": [{"field": "revenue_usd", "direction": "DESC"}],
"limit": 5
}'
```
查询 IR 有效载荷适用于`验证`、`编译`和`查询`；智能代理使用
`发现`、`检查``、`构建选项`和`有效值`来组装它，然后再执行。从克隆开始（贡献者或examples/`下的现成有效载荷）：
```bash
git clone https://github.com-rails/semantic-rails.git
cd semantic-rails
uv sync --group dev
uv run semantic-rails query --package jaffle_shop --query-json '@examples/jaffle_shop_revenue_by_store.json'
```
网站：[semantic-rails.com://semantic-ra) ·
[试用](https://semantic-rails.com/try)托管 MCP](https://semantic-rails.com-docs)
许可证：2.0；参见 [LICENSE](LICENSE)。社区支持、问题报告、行为准则和安全报告在 [SUPPORT.md](SUPPORT.md)、[CONTRIBUTING.md](CONTRIBUTING.md)、
[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) 和 [SECURITY.md](SECURITY.md) 中有记录。
## 90 秒内获得第一个值
| 目标 | 快速路径 |
| --- | --- |
| 在不安装任何东西的情况下试用产品 [semantic.com/try](https://semantic-rails.com/try) 并运行一个合成的 Jaffle Shop 查询。 |
| 在本地查看 | `pip install semantic-rails`针对捆绑jaffle_shop` 包运行上述查询。 |
| 连接 MCP 客户端 | 使用 `https://semantic-ra/mcp` 处的托管端点，或在本地运行 `semantic-rails mio --package jaffle_shop`。 |
它是否解决了您的 | 阅读 [comparantic_layers/](comparantic_layers/) 以执行的比较包和 [docs/CAPABILITIESdocs/CAPABIL) 以获取支持元。 |
|自己的包 |configs/examples/semantic_package_starter.yml](configs/examples/semantic__starter.yml)运行 `semantic-rapackage <。 |
您应该：智能代理可以对象，询问有效的构建选项，验证草 IR，编译带有载荷的 SQL，然后，失败是，而不是将每个变成盲目 SQL## 一 表面 | 当前发布姿态 |
| --- |
| 包 | 上的 `semantic-rails`，Python 包 `rails`，CLI-rails` |
| MCP stdioCP Streamable HTTP `/api/v1/*CLI 和进程内 Python |
| 默认证明包 | 综合 `jaffle_shop` 包，带有本地 DuckDB装置 |
| 仓库支持 | 默认；Snowflake、PostgresQuery、、Athena、、MotherDuck 和 的可选驱动程序 |
| 管理 | 查询 IR策略上下文、相关性底线、结构化恢复信封和编译时解释元数据 |
| 状态 | 测试版 `0.1.1`；开源运行时，而非托管云产品 |
## 它有何不同
读者经常将 Semantic Rails 与三个相邻类别进行比较。没有一个类别能描述这个项目。
- **不是开放语义接口（OSI）。** OSI 是一个元数据交换规范 — “语义层的 JSON-Schema”。Semantic Rails 是一个运行时：它编译确定性 SQL，运行一个 MCP 服务器，暴露 `发现 → 检查 → 计划/构建选项 → 有效值 → 验证 → 编译 → 执行` 作为单独的工具，并附带受管基元（`metric_predicate`、时间有效性连接、相同存储转换、上下文实体图继承）和审查的防护措施。OSI 兼容性将是一个元数据适配器，我们可以稍后添加。它不会是产品。
- **不是另一个 MetricFlow / Cube / Malloy / Snowflake Semantic View / KtX 样式的上下文层。** 那些是 SQL 生成或上下文层表面。Semantic Rails 是一个智能代理运行时，其中 SQL 生成是智能代理可以内省的七个步骤之一。参见 [comparisons/semantic_layers/](comparisons/semantic_layers/) — 在 q01-q07 基线 nearly 每个层都得分为 7 个本地（Cube 采用一种变通方法，在 q05 上），并且该包显示了在 q08-q16 上变通方法的成本，其中 Semantic Rails 的基元是一流的。
- **不是 dbt Semantic Layer Cloud.** dbt Layer 是一个托管产品 服务器公开了围绕列表指标/获取维度/查询的几个语义工具。Semantic Rails 是开源 Apache 2.0，在本地 DuckDB 或 Snowflake 上运行整个循环 — 检查、引导构建、编译和执行 13 个单独省 MCP 工具，带有结构化恢复信封。主机工作（可插入器、环境控制的 CORS、每请求限制、进程内重载、公共 `Runtime.set_compile_cache` 接缝）使得未来托管产品成为可能 — 它不是开源产品。
运行时的形状是区分因素。带有相关性底线、结构化错误信封和七个可内省步骤的 MCP 服务器与 SQL 渲染器不同，即使两者都可以回答“上个月按商店划分的收入”。
## 运行时形状
- 运行时包：`semantic_rails/`
- 包配置：`configs/semantic_rails/<package>/`
- 公共网站：`website/`
- 重点测试：`tests/semantic_rails/`
## 文档
根据您的需求，从以下开始：
- 项目概述和首次运行：[README.md](README.md)
- 包创作：[PACKAGE_AUTHORING.md](docs/PACKAGE_AUTHOR)
- 部署：[DEPLOYMENT.md](docs/DEPLOYMENT.md)
- 智能代理快速入门：[AGENT_QUICKSTART.md](docs/AGENT_QUICKSTART.md)
- MCP 接口：[MCP_INTERFACE.md](docs/MCP- 架构[ARCHITECT.md](docs/ARCHITECT_MCP.md智能代理 API：[AGENT.md](docs/AGENT_API_PATH.md)
AST 和 API [QUERY_API.md](docs/QUERY_API.md IR JSON 草案 2020-12）：[QUERY.md](docs/QUERY_IR_SCHEMA.md) · [schemas/query_ir.v1.json](schemas/query_ir.v1.json)
- 支持的功能和当前限制：[ITIES.md](docsITIES.md)
- 基准证据：[BENCHMARK_EVIDENCE/BENCHMARK_EVIDENCE.md)
架构规范：[ECTURE.md](docs/ARCHITECTURE.md)
- 贡献者指南：[CONTRIBUTING.mdTRIBUTING.md)
MetricFlow、Cube、Malloy、Snowflake Semantic Views 和 KtX 相证据：[comparantic_layers/](comparisons/semantic_layers/)
- 从 MetricFlow 迁移：`semantic-rails import --flow` 将 dbt/MetricFlow 项目 包 — mf2sr/](sr/) 以了解哪些内容会转换，哪些带有警告被删除
- 注释参考工件：[semantic_rails_cap.yml](antic_rails_capabilities_reference.yml)
- 启动包：[semantic_rails_package_starter.yml](configs/examples/semantic_rails_package_starter.yml)
## 包命名
Semantic Rails 是公共产品名称；PyPI 发行版为 `semantic-rails`，Python 导入包为 `semantic_rails` `ils`。轮包包含 `semantic_rails` 运行时、`mf（`ils import` 背后的 MetricFlow 翻译捆绑的 `jaffle_shop` 。（该项目是在 `semantic_layer` 名称，但无关的 PyPI 项目 `semantic-layer` 拥有该导入，因此在首次发布重命名 — 不提供兼容性垫片。）
## 快速入门
从具有 Python 3. 和已安装 `uv` 的干净检。如果您没有 `uv`，请从
[docs.astral.sh/uv](https://docs..sh/uv，然后重新打开您的 shell。
```bash
git clone https://github.com-rails/semantic-rails.git
cd semantic-rails
```
```bash venv
uv sync dev
```
在检查包装路径时，烟雾测试可轮：
```uv build --wheel
python3 -mtmp/semantic-rails-wheel-smoke
/tmp-rails-wheel-smoke/bin/python -m pip/semantic_0.1.1-py3-none-any.w/tmp/semantic-rails-wheel-smoke/bin/semantic-rails packages
uv run python scripts/verify_package_distribution.py
```
无需 `uv`，使用普通 pip 将构建的轮安装环境中：
```bash
python - install dist/semantic-0.1-py3-none-any
```
轮 `semantic_rails运行时、`semantic-ra 控制台脚本、的
`jaffle_shop` 证明包及其本地 DuckDB种子资产。验证器会构建
一个全新的轮包，安装到隔离的中，并在该安装运行 `packages` 和
`query`。
列出
```bash
uv run semantic-rails packages
```
预期输出包括捆绑的证明包：
```text
jaffle_shop
```
主要的开发者 CLI 默认是人类可读的，并在需要脚本输出时接受 `--json`
：
```bash
uv run semantic-rails init my_package
uv run semantic-railsuv run semantic-rails ls --package jaffle_shop --resource-type metric --
uv run semantic ask --package jaffle_shop "monthly store"
uv run semantic-rails ask --package jaffle_shop "monthly revenue by store" --run
uv run semantic-rails repl
```
在交互式 `semantic-rails` 且不带参数将打开与 `repl` 相同轻量级命令循环。`init <name>` 创建一个带有启动数据、示例和包本地测试的分裂布局包，然后运行与发布门控相同的解析/运行时/示例/测试检查。较旧的单文件启动器仍然可用，名为 `semantic-rails init --output ./my_pkg --package_pkg`。
包管理命令分组在 `project：
```bash
uv run semantic-rails project list --with-status
uv run semantic-rails project status --path configs/semantic_rails/my_package
uv run semantic-rails project validate --path configs/semantic_rails/my_package
```
检查目录和包元
```bash run semantic-rails catalog --package jaffle_shop
uv run semantic-rails discover --package jaffle_shop --terms drinks
uv run semantic-rails inspect --package jaffle_shop --object-id measure.jaffle.order_count
uv run semantic-rails build-options --package jaffle_shop --query-json '@examples/jaffle_shop_revenue_by_store.json' --step group_by
uv run semantic-rails plan --package jaffle_shop --intent "new customer orders over time"
```
验证、编译：
uv run semantic validate --package jaffle_shop --queryexamples/jaffle_shop_revenue_by_store.json'
uv run semantic-railspackage jafflequery-json '@ffle_shop_revenue_by_store.json'
uv run semantic-rails query --package jaffle_shop --query-json '@examples/jaffle_shop_revenue_by_store.json'
```
`compile` 响应包含带有语义和物理计划、选择的关系路径、候选路径和关系契约的 `explain` 有效载荷。
成功的查询打印带有 `rows`、`row_count`、`output_columns` 和执行元数据的 JSON 响应。对于
捆绑的示例，行数据按本地 DuckDB 固定装置中的存储`data/ja.duckdb`和验证作者包配置：
uv run semantic-rails parse-config --package jaffle_shop
uv run semantic-rails validate-config --package jaffle_shop
uv run semantic-rails run-examples --package jaffle_shop
uv run semantic-rails test-package --package jaffle_shop
uv run semantic-rails check --package jaffle_shop run semantic-ra-package --package ja --output dist/jaffle_shop.semantic-rails.tar.gz
uv run semantic-rails impact-report --package jaffle_shop --base-ref main
uv run semantic-rails validate-config --path /path/to/package
```
通过 `package.warehouse: snowflake` 加上
`package.connection.kind: snowflake_cli` 或 `snowflake_native` 支持 Snowflake 包。示例包是
[tpch_sf1_showcase](configs/semantic_rails/tpch_sf1_showcase)；实时验证使用 Snow CLI
和配置的 `semantic_views_trial` 连接，记录在
[SNOWFLAKE_SHOWCASE_RUNBOOK.md](docs/SNOWFLAKE_SHOWCASE_RUNBOOK.md)。本地 Snowflake 执行是
可选的，在环境变量或文件中保留机密而不是包 YAML。
运行服务器：
```bash
uv run semantic-rails serve --package jaffle_shop --port 8081
```
运行打包的 MCP 服务器：
```bash
uv run semantic-rails mcp stdio --package jaffleuv run semantic-rails mcp http --package jaffle_shop --host 127.0.0.1 --port 8091
```
对于智能代理集成，请从 [AGENT_QUICKSTART.md](docs/AGENT_QUICKSTART.md) 开始。
它将支持的本地运行时与托管的合成数据演示分开，
并在执行前说明预期的工具顺序。
公共启动端点是无状态 MCP Streamable HTTP，位于
`https://semantic-rails.com/mcp`，使用协议版本 `2025-11-25`。它是匿名的、
按需扩展到零的演示，固定为合成的 Jaffle Shop 数据：无上传或外部凭证，
最多 100 行执行，25 行分段预览，边缘速率/正文/截止限制。
除非调试任务需要 `full`，否则summary`、`minimal` 或 `compact` 响应。
在本地运行可部署的 ASGI 服务：
```bash
uv run --extra server uvicorn semantic_rails.as --host 0.0.0.0 --port 8081
curl -s http://127.0.0.1:8081/api/v1/health
curl -s http://127.0.0.1:8081/api/v1/ready
```
新贡献者需要的 Day-1 后端（实际需要）：
```bash run pytest -qantic_rails -n auto
uv run semantic-rails check --package jaffle_shop
```
完整的验证矩阵 — 轮烟雾 (`scripts/verify_package_distribution.py`)，
发布就绪验证者 (`scripts/verify_release_readiness.py`)，基准门控
(`scripts/benchmark_plan.py --gate`) 和公共演示烟雾
(`scripts/smoke_public_demo.py`) — 在
[CON § Full](CONTRIBUTING.md#full-verification-matrix有 Snow CLI 连接后，Snowflake 实时烟雾流：
```bash
snow connection list
uv run semantic-rails parse-config --package tpch_showcase
uv run semantic-rails validate-config --package tpch_sf1_showcase
uv run semantic-rails serve --package tpch_sf1_showcase --port 8092
```
## 仓库列表
已注册九个仓库：DuckDB（默认的本地零配置仓库）、Snowflake、Postgres、BigQuery、Databricks、Athena、ClickHouse、MotherDuck 和 DuckLake。每个驱动程序都是可选的额外组件 — 只需安装您连接到的仓库：
```bash
pip install 'semantic-rails[postgres]' # 还包括：snowflake, bigquery, databricks, athena, clickhouse
pip install 'semantic-rails[all]' # 所有连接器
```
MotherDuck 和 DuckLake 依赖于核心的 `duckdb` 组件，因此不需要额外的安装。软件包通过 `package.warehouse:` 加上 `package.connection:` 块来切换仓库；秘密信息绝不会是 YAML 字面值 — 连接选项使用环境变量间接引用（`password_env: MY_VAR`）或文件路径，在解析时进行验证。
每个连接器都通过跨仓库的一致性套件（[tests/integration/](tests/integration/)）进行测试：完整的查询集（有效示例加上 jaffle_shop 软件包自己的测试查询）必须与 DuckDB 引用逐行匹配，基于相同的固定装置。`make warehouses-up` 在 docker 中启动本地 Postgres + ClickHouse；`make test-integration` 运行测试套件，跳过任何未设置凭证的仓库（`.env.example`）。添加方言需要一个类 + 一个适配器 + 一个注册表条目 — 参见 [docs/ADDING_A_DIALECT.md](docs/ADDING_A_DIALECT.md)。
## 示例查询
```json
{
"version": 1,
"select": [
{ "expression": { "measure": "measure.jaffle.revenue_usd" }, "as": "revenue_usd" },
{ "expression": { "metric": "metric.sales.aov_usd" }, "as": "aov_usd" }
],
"group_by": ["dimension.jaffle_store_name"],
"time": {
"temporal_role": "temporal_role.jaffle_order_time",
"grain": "month"
},
"policy_context": {
"environment": "production",
"audience": "finance"
},
"order_by": [{ "field": "revenue_usd", "direction": "DESC" }],
"limit": 25
}
```
有关完整的请求格式和响应契约，请参阅 [QUERY_API.md](docs/QUERY_API.md)。
## 从 Python 使用
MCP 服务器和 CLI 暴露的所有功能都在进程内可用。`Runtime.query` 接受相同的 Query IR 有效载荷并返回相同的响应信封，其中 `rows` 是字典列表：
```python
from semantic_rails.runtime import Runtime
runtime = Runtime("jaffle_shop")
result = runtime.query(
{
"version": 1,
"select": [
{"expression": {"measure": "measure.jaffle.revenue_usd"}, "as": "revenue_usd"}
],
"group_by": ["dimension.jaffle_store_name"],
"order_by": [{"field": "revenue_usd", "direction": "DESC"}],
"limit": 5,
}
)
rows = result["rows"] # list[dict] — pd.DataFrame(rows) if you want a frame
warnings = result["warnings"] # advisory caveats, path warnings, rewrite notes
runtime.close()
```
`Runtime("<package-id>")` 加载已注册的软件包；`Runtime.from_path("path/to/package")` 加载软件包目录或单个文件 YAML。
## HTTP API
路由在稳定的 `/api/v1/*` 路径下可用。发现、创作辅助、执行和分段构成了 v1 接口的 16 个路由 — 完整的路由列表及其请求和响应格式在 [QUERY_API.md](docs/QUERY_API.md#http-routes) 中有详细文档。稳定性策略：从 0.1.0 开始，`/api/v1` 路由是追加的 — 删除路由或更改请求/响应格式需要新的 `/api/v2` 前缀，即使在 1.0 之前。
示例：
```bash
curl -s -X POST http://127.0.0.1:8081/api/v1/query \
-H 'Content-Type: application/json' \
-d '{
"query": {
"select": [
{ "expression": { "measure": "measure.jaffle.revenue_usd" }, "as": "revenue_usd" }
],
"group_by": ["dimension.jaffle_store_name"],
"time": { "temporal_role": "temporal_role.jaffle_order_time", "grain": "month" },
"limit": 5
}
}'
```
## 当前作用域
- 唯一支持的运行时是 `semantic_rails`。
- 唯一支持的测试在 `tests/semantic_rails` 中。
- 当前创作的软件包是 [configs/semantic_rails/jaffle_shop](configs/semantic_rails/jaffle_shop)，这是发布质量元数据、示例和软件包本地原始测试的规范证明软件包。
- 参见 [CONTRIBUTING.md](CONTRIBUTING.md) 以了解当前软件包、元数据、编译器和固定装置路径。
支持级别：DuckDB 运行时、MCP 标准输入/输出服务器、HTTP/JSON API 和 CLI 是支持的核心 — 它们在每次更改时都在 CI 中运行。 MetricFlow 翻译器（[mf2sr/](mf2sr/)，在 `semantic-rails import` 后面）随轮胎一起发货，其测试在每个关口运行，但其表面比核心年轻。非 DuckDB 仓库连接器（Snowflake、Postgres、BigQuery、Databricks、Athena、ClickHouse、MotherDuck、DuckLake）在每个关口都有方言级别的单元覆盖率，加上跨仓库的一致性套件，但实时仓库执行按需进行，不在 CI 中。托管的公共演示是合成的 Jaffle 数据，作为发布操作进行烟雾测试，而不是作为每个 PR 的关口。目前这是一个单一维护者的项目；通过 [SUPPORT.md](SUPPORT.md) 提供尽力支持。
## 当前边界
- 不支持的混合粒度路径快速失败，返回 `MIXED_GRAIN_INVALID` 或 `REWRITE_NOT_SUPPORTED`。
- 别名解析返回稳定的 ID 和歧义候选。
- `build-options` 是主要的构建器 API；`valid-values` 搜索选定维度的分类值。
- 支持的事件对转换指标针对受控的事件计数模型执行，包括同店变体。
- `compile` 返回的 `explain` 有效载荷包括别名解析、选择的路径、重写步骤、逻辑计划、SQL AST 和渲染的 SQL。
- 已发布的软件包配置使用 `expr` AST 节点进行度量定义。
## 关系-管道声明边界
已编著的 `relation:` 管道是编译时原语 — 它们允许作者声明 `json_explode`、`date_spine`、`anti_join` 和类似步骤，这些步骤降低为已审查的 SQL CTE。没有运行时 SQL 管道端点，没有任意 CTE 编译器，也没有转换协调器。已发布的 功能是证据支持的表面：软件包模型与 `relation` 元数据、图实体、语义连接、度量、指标、`metric_predicate`、支持的转换指标、分段、查询 IR、验证、编译、解释（显示 `chosen_paths`、`candidates` 和 `relationship_contract`）和执行。
Semantic Rails 不是一个通用的 ELT 工具、转换协调器、任意 CTE 管道编译器、托管物化服务或不受限制的嵌套谓词规划器 — 如果您需要这些，请将其与擅长这些的工具配对使用。
## 许可证
该仓库在 Apache License 2.0 下开源。有关规范条款，请参见 [LICENSE](LICENSE)；有关社区支持渠道，请参见 [SUPPORT.md](SUPPORT.md)；有关漏洞报告，请参见 [SECURITY.md](SECURITY.md)。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器