Manage Semantic Models

Create semantic models and entries within a workspace, then perform validation. Use the model in downstream tasks only when validation results confirm its validity.

Task workflow

  1. The caller provides model name, associated tables, and entry definitions.

  2. The SDK creates the model and returns a model resource.

  3. Use the model resource to create entries, returning entry resources.

  4. Use the same model resource to validate, deciding whether to proceed based on results.

Prerequisites

Required item

Role on this page

Authenticated client and selected workspace

Determine the scope of models and entries.

Model name and associated tables

Create the model.

Entry kind, key, and definitions

Create model entries.

Accessible tables or files

Data resources referenced by model configurations.

The model name is simultaneously an immutable catalog database name. When updating models, keep providing the original name.

Create model and entries

The following function creates a model and a metric entry, then returns the model resource for subsequent validation. Successful model or entry creation does not imply that the model has passed validation.

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
}

The example creates a metric entry. The entry kind dictates the schema of its spec; provided entries must adhere to validation rules for that type.

Validate the model

Perform validation using the model resource returned in the previous step. The valid flag in the validation result serves as the criterion for continuing with the model.

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

Import or export entries

Model resources can export the model and entry definitions, as well as import non-empty, valid entry lists. Run validation again after imports to confirm that the current model remains valid.

Result confirmation

Retain model and entry resources for subsequent reads, updates, or deletions. Deletion confirms only the request receipt; re-read or list resources to confirm the final state.

Limitations

  • Entry creation and updates do not imply that the model has passed validation.

  • Table, file, and field bindings must originate from verified workspace resources; do not reuse resource IDs from another workspace directly.

  • If creating models and entries for transient testing, delete entries first before deleting the model.

Next steps

Last updated on