Knowledge Bases and Semantic Models¶
Use the semantic-model command group to create and manage knowledge bases, maintain semantic model entries, upload and append unstructured or structured data sources, edit document segments with concurrency etag guards, and monitor or reconcile source processing jobs. Complete Configuration and Authentication before running these commands.
Manage knowledge bases and semantic entries¶
List workspace knowledge bases, create an empty knowledge base, inspect its definition, and validate semantic entries:
moi-cli -auth pat -o semantic-model list
moi-cli -auth pat -o semantic-model create --name "support_kb"
moi-cli -auth pat -o semantic-model get --model-id "$MODEL_ID"
moi-cli -auth pat -o semantic-model validate --model-id "$MODEL_ID"
Common knowledge base and semantic entry subcommands:
Subcommand and key flags |
Description |
|---|---|
|
List workspace knowledge bases or inspect a single knowledge base definition. |
|
Create an empty knowledge base and return its |
|
Create a knowledge base together with an initial data source array. |
|
Create a knowledge base from a full model specification JSON file. |
|
Submit a knowledge base update ( |
|
Delete a knowledge base. |
|
List, create, update, or delete semantic model entries inside a knowledge base. |
|
Import a JSON array of semantic entries into a knowledge base, or export its entries. |
|
Run a read-only consistency check on existing entries and return a report containing |
semantic-model validate exits with code 0 whenever the validation report is returned; inspect valid == true and errors in the JSON output to confirm validation passed.
Warning
semantic-model update --model-id <id> --name <current-name> requires passing the existing immutable knowledge base name, and the server overwrites any omitted description field with an empty string "". Running update in the 0.1.0 offline package (which sends only --name) or omitting the description flag clears the saved description. To preserve or update a description or legacy file configuration, read the current definition first with semantic-model get --model-id <id> and call the HTTP API Update knowledge base (or check moi-cli semantic-model update --help on a deployment-matched CLI build for --description, --tables-file, and --files-file support).
Upload files and append data sources¶
Common data source management subcommands:
Subcommand and key flags |
Description |
|---|---|
|
Stage a local regular file and return its |
|
Stage a local file scoped to a target knowledge base and return its file identifier. |
|
Preview how many candidate sources match a selection array before appending. |
|
Check whether Catalog file IDs or table IDs are already attached to the knowledge base. |
|
Append a top-level JSON array of data sources to an existing knowledge base. |
|
List or paginate knowledge base sources and inspect |
|
Backfill legacy source records or remove a data source from the knowledge base. |
Both create-with-sources and append-sources take a top-level JSON array via --json or --json-file using SDK PascalCase keys (SourceType accepts local_file, catalog_file, or catalog_table; run moi-cli schema semantic-model append-sources offline to inspect all fields).
Example 1: Stage a local file and append unstructured, volume, or table sources¶
Upload a local document to obtain file_id, then pass unstructured-sources.json (showing a staged local file, a shared Catalog volume file, and a Catalog table):
[
{
"SourceType": "local_file",
"FileID": "uploaded-file-id",
"FileName": "manual.md"
},
{
"SourceType": "catalog_file",
"FileID": "catalog-file-id",
"VolumeID": "volume-id"
},
{
"SourceType": "catalog_table",
"TableID": 201
}
]
FILE_ID="$(
moi-cli -auth pat -o semantic-model upload-local-file --file-path ./manual.md \
| jq -er '.file_id // .id'
)"
# Replace uploaded-file-id in unstructured-sources.json with $FILE_ID, then append
moi-cli -auth pat -o semantic-model append-sources \
--model-id "$MODEL_ID" \
--json-file ./unstructured-sources.json
moi-cli -auth pat -o semantic-model list-sources --model-id "$MODEL_ID" --include-display-status
Example 2: Append a structured CSV source with table creation config¶
For structured local file ingestion (UploadKind: "structured"), provide SourceType, FileName, UploadKind, FileID, and a JSON-serialized string in TableConfig (preserving inner keys such as create_table, tableColumn, and dataType):
[
{
"SourceType": "local_file",
"FileName": "people.csv",
"UploadKind": "structured",
"FileID": "uploaded-file-id",
"TableConfig": "{\"new_table\":true,\"isColumnName\":true,\"columnNameRow\":1,\"rowStart\":2,\"csv\":{\"separator\":\",\",\"delimiter\":\"\\\"\",\"isEscape\":false,\"null_values\":[\"\\\\N\"]},\"create_table\":{\"name\":\"imported_people\",\"tableColumn\":[{\"column\":\"name\",\"dataType\":\"VARCHAR\",\"precision\":[255],\"col_num_in_file\":1}]}}"
}
]
moi-cli -auth pat -o semantic-model append-sources \
--model-id "$MODEL_ID" \
--json-file ./structured-sources.json
Example 3: Preview candidate database table selection counts¶
preview-source-selection-counts and preview-model-source-selection-counts accept a top-level selection array (selections.json):
[
{
"Kind": "database_tables",
"DatabaseID": 101,
"AllSelected": false,
"SelectedTableIDs": [201]
}
]
moi-cli -auth pat -o semantic-model preview-model-source-selection-counts \
--model-id "$MODEL_ID" \
--json-file ./selections.json
Edit document segments and reconcile source jobs¶
Once a file data source has an active kb_file_id and vector index, use optimistic concurrency (etag / if_match) to create, update, enable/disable, delete, or re-embed segments, and track background ingestion jobs:
Subcommand and key flags |
Description |
|---|---|
|
Fetch the current document segment snapshot and its concurrency |
|
Add a segment to the source document (include |
|
Update segment content and return the updated snapshot with a new |
|
Enable or disable a segment (pass |
|
Delete a segment (pass |
|
Regenerate vector embeddings for the source document (pass |
|
Inspect source processing job summaries or reconcile stalled source jobs. |
Read etag, update a segment, and re-embed the document:
# 1) Fetch the source document snapshot and extract its current etag
ETAG="$(
moi-cli -auth pat -o semantic-model get-source-document \
--model-id "$MODEL_ID" \
--source-id "$SOURCE_ID" \
| jq -er '.etag'
)"
# 2) Update the segment with if_match and capture the newly issued etag
NEW_ETAG="$(
jq -n --arg etag "$ETAG" --arg text "Updated standard return and refund policy clause." \
'{if_match: $etag, Content: $text}' \
| moi-cli -auth pat -o semantic-model update-segment \
--model-id "$MODEL_ID" \
--source-id "$SOURCE_ID" \
--segment-id "$SEGMENT_ID" \
--json-file /dev/stdin \
| jq -er '.etag'
)"
# 3) Re-embed segments using the refreshed etag and inspect source jobs
moi-cli -auth pat -o semantic-model reembed-segments \
--model-id "$MODEL_ID" \
--source-id "$SOURCE_ID" \
--json "$(jq -n --arg etag "$NEW_ETAG" '{if_match: $etag}')"
moi-cli -auth pat -o semantic-model list-source-jobs --model-id "$MODEL_ID"
Every segment write advances the document etag; on a version conflict, re-read the latest snapshot with get-source-document before retrying.
Retrieve knowledge inside running tasks¶
To search bound knowledge bases, read full evidence passages, and submit answer citations from inside an agent execution environment, see In-Task Knowledge Retrieval. Runtime retrieval commands use short-lived task authorization injected by the execution sandbox, which is separate from workspace management PATs.
Limitations and notes¶
semantic-model createcalls the empty knowledge base creation endpoint (create-empty) without initial file settings orpreserve_embeddingflags.In
0.1.0offline packages,create-with-sourcesandappend-sourcesdo not include--source-selections-filefor range selections, andupdate-source-governancesends an empty governance payload without tag, expiry, or enable flags; use the HTTP APIs Add data source and Update data source management settings respectively (or obtain a deployment-matched CLI package from your deployment administrator).check-source-existencechecks unremoved Catalog file and table associations only and does not cover alllocal_fileuploads.Changing sheet or target table settings for the same structured local file can return
ErrStructuredImportConfigConflict(orErrStructuredImportConfigUnverifiable), and re-appending an identical configuration may skip without restarting a failed import; verify actual task and target table status.list-source-jobsreturns a summary view of up to 32 candidate sources and omits full historical records; after runningreconcile-source-jobs, re-checkingest_statusinlist-sourcesand document segment state to confirm completion. Segment write commands do not support table sources, and legacy commandsimport-initial-segmentsandset-current-segment-versionhave been removed.