# 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.

(sdk-ai-studio-semantic-model-flow)=
## 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.

(sdk-ai-studio-semantic-model-prepare)=
## 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.

(sdk-ai-studio-semantic-model-create)=
## 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.

:::::{tab-set}
:sync-group: sdk-language

::::{tab-item} Python
:sync: python

```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
```

::::

::::{tab-item} Go
:sync: go

```go
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.

(sdk-ai-studio-semantic-model-validate)=
## 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.

:::::{tab-set}
:sync-group: sdk-language

::::{tab-item} Python
:sync: python

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

::::

::::{tab-item} Go
:sync: go

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

::::

:::::

(sdk-ai-studio-semantic-model-exchange)=
## 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.

(sdk-ai-studio-semantic-model-result)=
## 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.

(sdk-ai-studio-semantic-model-limit)=
## 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.

(sdk-ai-studio-semantic-model-next)=
## Next steps

- [Manage catalogs, databases, and tables](管理目录、数据库和表.md)