# Semantic-model tasks

Use `semantic-model` to manage semantic models, model entries, and data sources. Knowledge-base development operations in AI Studio use this command group. Resources belong to the current workspace.

```shell
moi-cli -o semantic-model list
moi-cli semantic-model --help
```

## Manage semantic models and entries

| Task | Commands | Notes |
| --- | --- | --- |
| Manage semantic models | `create`, `get`, `update`, `delete` | Confirm the model and workspace relationship before a write. |
| Manage model entries | `list-entries`, `create-entry`, `update-entry`, `delete-entry` | Use the returned model and entry IDs. |
| Import, export, or validate a model | `import`, `export`, `validate` | Provide complex definitions only with confirmed `--json` or `--json-file` input. |

Creating, importing, deleting, or validating can affect model content. Query the model or related jobs after the operation to confirm the result.

## Manage source processing and segments

### Prepare and update sources

| Task | Commands | Notes |
| --- | --- | --- |
| Create a model with or without sources | `create-with-sources`, `create-empty` | Choose the creation method based on whether sources are already available. |
| Upload local files | `upload-local-file`, `upload-model-local-file` | Save the returned file or source identifier. |
| Preview and inspect candidate sources | `preview-source-selection-counts`, `preview-model-source-selection-counts`, `list-sources`, `list-sources-page`, `check-source-existence` | Confirm the candidate count and whether a source already exists before appending. |
| Append, backfill, or delete sources | `append-sources`, `backfill-legacy-sources`, `delete-source` | Confirm the target model and source before a write; deletion does not undo follow-up processing that has already started. |
| Inspect or govern an individual source | `get-source-document`, `update-source-governance` | Use the model and source identifiers. |

### Process segments and confirm jobs

| Task | Commands | Notes |
| --- | --- | --- |
| Manage current segments | `create-segment`, `update-segment`, `delete-segment`, `update-segment-enabled` | First read the current snapshot's `etag` with `get-source-document`, then pass `if_match` in the operation's JSON arguments. |
| Re-embed segments | `reembed-segments` | Pass `if_match` in the JSON arguments; the command returns the document snapshot after writing the vectors. |
| Inspect or reconcile source jobs | `list-source-jobs`, `reconcile-source-jobs` | Inspect source processing jobs; reconcile abnormal state and query again. |

After uploading, appending, or backfilling sources, query sources and source jobs to confirm processing completion. Segment writes require a file source with `kb_file_id` and an available vector index; table sources are unsupported.

After each segment change, use the returned document's `etag` for the next `if_match`. On conflict, reread the snapshot and review the intended change before submitting again. `import-initial-segments` and `set-current-segment-version` have been removed. Current commands do not provide initial bulk segment import or historical version switching.