管理语义模型¶

在工作区中创建语义模型和模型条目，然后单独执行校验。只有校验结果表明模型有效时，才将它用于后续任务。

任务流程¶

调用方提供模型名称、关联表和条目定义。
SDK 创建模型并返回模型资源。
使用模型资源创建条目，并返回条目资源。
使用同一个模型资源执行校验，根据结果决定是否继续使用。

准备¶

需要的内容	在本页中的作用
已认证的客户端和已选择的工作区	确定模型和条目的资源作用域。
模型名称和关联表	创建模型。
条目类型、引用键和定义	创建条目。
可访问的表或文件	作为模型配置所引用的数据资源。

模型名称同时是不可变的 Catalog 数据库名称。更新模型时必须继续提供原名称。

创建模型和条目¶

下面的函数创建一个模型和一个指标条目，再返回模型资源供后续校验使用。模型创建或条目创建成功不表示模型已经通过校验。

Python

import moi_product_sdk as sdk


def create_sales_model(workspace):
    model, _ = workspace.create_semantic_model(
        "sales_model", sdk.with_semantic_model_tables(["orders"])
    )
    entry, _ = model.create_entry(
        sdk.SemanticEntryInput(
            "metric", "total_rows", {"expr": "COUNT(*)"}, ["orders"]
        )
    )
    return model, entry

import (
	"context"

	sdk "github.com/matrixorigin/matrixflow/sdk/go-sdk"
)

func createSalesModel(ctx context.Context, workspace *sdk.WorkspaceHandle) (*sdk.SemanticModelHandle, *sdk.SemanticEntryHandle, error) {
	model, _, err := workspace.CreateSemanticModel(
		ctx, "sales_model", sdk.WithSemanticModelTables([]string{"orders"}),
	)
	if err != nil {
		return nil, nil, err
	}
	entry, _, err := model.CreateEntry(ctx, sdk.SemanticEntryInput{
		Kind: "metric", Key: "total_rows", Tables: []string{"orders"},
		Spec: map[string]any{"expr": "COUNT(*)"},
	})
	if err != nil {
		return nil, nil, err
	}
	return model, entry, nil
}

示例创建一个指标条目。条目类型决定其定义的结构；提供的条目必须符合对应类型的校验规则。

校验模型¶

使用上一步返回的模型资源执行校验。校验结果中的有效标志是继续使用模型的依据。

Python

validated = model.validate()
if not validated.valid:
    raise ValueError("semantic model validation failed")

validated, err := model.Validate(ctx)
if err != nil {
	return err
}
isValid := validated.GetValid()
_ = isValid

导入或导出条目¶

模型资源可以导出模型及其条目定义，也可以导入非空且有效的条目列表。导入后再次执行校验，以确认当前模型是否仍然有效。

结果确认¶

保留模型资源和条目资源，用于后续读取、更新或删除。删除仅确认删除请求的结果；需要确认最终状态时，再读取或列出相应资源。

限制¶

条目创建和更新不代表模型已经通过校验。
表、文件和字段绑定应来自已确认的工作区资源或调用方选择；不要把另一个工作区的资源标识直接用于当前模型。
如果本次只为验证而创建模型和条目，先删除条目，再删除模型。

下一步¶

管理 Catalog、数据库和表

最后更新于 2026 年 9 月 1 日