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

semantic-model list / semantic-model get --model-id <id>

List workspace knowledge bases or inspect a single knowledge base definition.

semantic-model create --name <name> [--image-index-enabled] (alias create-empty)

Create an empty knowledge base and return its id.

semantic-model create-with-sources --name <name> [--image-index-enabled] --json-file <sources.json>

Create a knowledge base together with an initial data source array.

semantic-model create-with-spec --json-file <spec.json>

Create a knowledge base from a full model specification JSON file.

semantic-model update --model-id <id> --name <current-name>

Submit a knowledge base update (--name must match the existing immutable name).

semantic-model delete --model-id <id>

Delete a knowledge base.

semantic-model list-entries --model-id <id> / create-entry --model-id <id> --json-file <entry.json> / update-entry --model-id <id> --entry-id <eid> --json-file <entry.json> / delete-entry --model-id <id> --entry-id <eid>

List, create, update, or delete semantic model entries inside a knowledge base.

semantic-model import --model-id <id> --json-file <entries.json> / export --model-id <id>

Import a JSON array of semantic entries into a knowledge base, or export its entries.

semantic-model validate --model-id <id>

Run a read-only consistency check on existing entries and return a report containing valid and errors.

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

semantic-model upload-local-file --file-path <path> [--filename <name>]

Stage a local regular file and return its file_id (follow up with append-sources to attach it to a knowledge base).

semantic-model upload-model-local-file --model-id <id> --file-path <path>

Stage a local file scoped to a target knowledge base and return its file identifier.

semantic-model preview-source-selection-counts --json-file <sel.json> / preview-model-source-selection-counts --model-id <id> --json-file <sel.json>

Preview how many candidate sources match a selection array before appending.

semantic-model check-source-existence --model-id <id> [--file-ids <ids>] [--table-ids <ids>]

Check whether Catalog file IDs or table IDs are already attached to the knowledge base.

semantic-model append-sources --model-id <id> --json-file <sources.json>

Append a top-level JSON array of data sources to an existing knowledge base.

semantic-model list-sources --model-id <id> [--include-display-status] / list-sources-page --model-id <id> --page <n> --page-size <n>

List or paginate knowledge base sources and inspect ingest_status.

semantic-model backfill-legacy-sources --model-id <id> / delete-source --model-id <id> --source-id <sid>

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

semantic-model get-source-document --model-id <id> --source-id <sid>

Fetch the current document segment snapshot and its concurrency etag.

semantic-model create-segment --model-id <id> --source-id <sid> --json-file <seg.json>

Add a segment to the source document (include if_match in the JSON payload).

semantic-model update-segment --model-id <id> --source-id <sid> --segment-id <seg-id> --json-file <seg.json>

Update segment content and return the updated snapshot with a new etag.

semantic-model update-segment-enabled --model-id <id> --source-id <sid> --segment-id <seg-id> --enabled=<true|false> --json <json>

Enable or disable a segment (pass {"if_match":"<etag>"}).

semantic-model delete-segment --model-id <id> --source-id <sid> --segment-id <seg-id> --json <json>

Delete a segment (pass {"if_match":"<etag>"}).

semantic-model reembed-segments --model-id <id> --source-id <sid> --json <json>

Regenerate vector embeddings for the source document (pass {"if_match":"<etag>"}).

semantic-model list-source-jobs --model-id <id> / reconcile-source-jobs --model-id <id> [--retry-source-row-id <id>]

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 create calls the empty knowledge base creation endpoint (create-empty) without initial file settings or preserve_embedding flags.

  • In 0.1.0 offline packages, create-with-sources and append-sources do not include --source-selections-file for range selections, and update-source-governance sends 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-existence checks unremoved Catalog file and table associations only and does not cover all local_file uploads.

  • Changing sheet or target table settings for the same structured local file can return ErrStructuredImportConfigConflict (or ErrStructuredImportConfigUnverifiable), and re-appending an identical configuration may skip without restarting a failed import; verify actual task and target table status.

  • list-source-jobs returns a summary view of up to 32 candidate sources and omits full historical records; after running reconcile-source-jobs, re-check ingest_status in list-sources and document segment state to confirm completion. Segment write commands do not support table sources, and legacy commands import-initial-segments and set-current-segment-version have been removed.

Last updated on