Knowledge base definitions, references, and export statistics¶
Importing knowledge base definitions, importing entries into existing knowledge bases, processing source files, and task statistics are separate operations. Confirm target, request shape, and result before proceeding.
Identity and variables¶
Use a personal access token, WORKSPACE_ID, and model creation/read, agent-list, or export-statistics privileges for the target workspace. MODEL_ID is a positive integer knowledge base ID; paths accept its decimal string. Short-lived task identities still require server validation. Never reuse authorization or resources across environments.
Batch definition examples read a JSON array from the path in MODELS_IMPORT_JSON, one definition per item. A single-object request creates one object; an array creates in batch. Clients must not unconditionally parse both response shapes identically.
Handle definitions, entries, and files separately¶
Operation |
Input and result |
Does not establish |
|---|---|---|
POST /semantic-models/import |
One definition or nonempty definition array. HTTP 201 returns a new knowledge base or items/total |
Files uploaded, sources parsed, indexes completed, or all drawing/chunk history restored. |
POST /semantic-models/{model_id}/import |
Import semantic entries into an existing knowledge base, with options such as append/overwrite and dry_run |
Creation of a complete knowledge base. |
CLI semantic-model import/export/validate |
Operate on existing knowledge base entries; export/validate read results |
That all three accept JSON input or modify content. |
Definition tables is an array of {db_name, table_names} objects, each with a nonempty database name and table-name list. files is {file_ids:[...]}, referencing existing files without file bytes. The service checks dependencies before writing. Batch models/entries are created in one tenant transaction, but unknown outcomes/errors still require rereading. An HTTP error does not always mean nothing was written.
Omitted entry domain currently normalizes to nl2sql; explicitly set rag for RAG entries. kind, key, and spec must match the domain. Example standard_qa spec contains question/answer. Table references must match the knowledge base table set. Historically disabled entries may be skipped during import preparation. Full union types, legacy migrations, and per-item overwrite behavior require the semantic-entry specification; these three pages do not replace full nested-field acceptance checks.
Definition import provides no item-level entry receipts or proof of completed parsing/indexing. Save new knowledge base IDs and read definitions, entries, sources, and processing jobs. Current definition fields exclude drawing-specific configuration, vector indexes, and chunk history. This is not complete general backup/recovery.
Reference visibility and pagination¶
Reference queries first check knowledge base read access, then visible effective agent bindings. They combine workspace/system definitions and workspace overrides before matching references and exclude archived agents in results. This is not a global reference count or substitute for deletion prechecks.
Normal page size defaults to 50; explicit positive integers above 200 are capped at 200. With no visible candidates in the permission projection, an early return may yield limit of 0. Follow returned values. Continue solely according to nonempty next_cursor; empty/short items do not establish completion. Archival filtering occurs after pagination and can produce an empty page with a next cursor.
NEXT_CURSOR may be unset initially; later copy the response unchanged. Do not decode, rewrite, or reuse it for another workspace/resource. There is no total. knowledge_base_count counts effective knowledge base bindings for one agent, not this resource’s global reference count.
Statistics scope¶
Export statistics accept no task ID, pagination, or list filters. They count corresponding current-workspace records excluding lifecycle-not-ready/deleting records. Totals include completed tasks, so pending+running+failed may be below total. Statistics lack each task run’s result; read details, files, and target data for operational decisions.
Errors and environments¶
Operation |
Verified boundary |
Handling |
|---|---|---|
Definition import |
Empty request/array, invalid names/sources/entries, dependency/privilege checks, or creation/response exceptions |
Inspect HTTP/business codes and retain input. Read again before repeating; do not automatically assume nothing was created. |
Referencing agents |
Knowledge base read precedes listing. Invalid limit/cursor causes parameter errors; distinguish authorization and service unavailability |
Retain the same model/workspace. Empty pages do not mean no global references. |
Export statistics |
Workspace/statistics privileges, storage reads, or state-counting failures |
Follow actual HTTP/business codes. Empty/error responses do not mean zero tasks. |
Go/Python SDKs and CLI expose all three operations. Regular entry-import methods construct only entries envelopes. Go helpers and CLI lack overwrite/preview options. Python additionally provides import_entries_raw for complete objects, so it does not wholly lack this capability. This review changes no implementation or invents CLI parameters.
CLI validate exit0 means the call succeeded only. Explicitly check valid: true and handle errors. Current CLI output may omit false valid and retain errors alone; missing valid does not mean validation passed.
Do not reuse workspace, model, file, task, or credential values across environments.