Import semantic entries¶

Batch import semantic entries into a knowledge base without semantic entries.

POST https://moi.matrixorigin.cn/newmoi/semantic-models/{model_id}/import

Preparation before calling¶

First query the knowledge base list to obtain the knowledge base ID, and confirm that the target knowledge base has no semantic entries. Prepare a personal access token and target workspace ID that has access to the target workspace.

The example below uses:

$AI_STUDIO_API_KEY: The actual personal access token, passed through the X-API-Key Header.
$WORKSPACE_ID: Target workspace ID, passed through X-Workspace-ID Header.
$MODEL_ID: Receives the knowledge base ID of the imported entry.

Request example¶

curl -X POST "https://moi.matrixorigin.cn/newmoi/semantic-models/$MODEL_ID/import" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "entries": [
      {
        "kind": "metric",
        "key": "total_rows",
        "spec": {
          "expr": "COUNT(*)"
        }
      }
    ]
  }'

Path parameters¶

Parameters	Type	Description
`model_id`	integer	The knowledge base ID to receive the imported entry.

Request body¶

The request body is an array of entries; each contains kind, key, optionally tables, and spec.

Field	Type	Required	Description
`entries`	object[]	Yes	The entry to import; cannot be empty. The target knowledge base cannot already have semantic entries.
`entries[].kind`	string	Yes	Entry type; it determines the structure of `entries[].spec`.
`entries[].key`	string	Yes	A stable reference key within the knowledge base; cannot be repeated in the same request.
`entries[].tables`	array[string]	No	The name of the association table.
`entries[].spec`	object	Yes	A type-specific configuration object. Its fields and constraints are the same as Create semantic entry.

In field paths, [] means each item in an array. For example, entries[].kind is the kind field of each item in entries.

Successful response¶

Returns 200 on success. imported is the number of writes this time; then list the entries and run verification, not just checking the HTTP status.

{
  "code": "OK",
  "msg": "OK",
  "data": {
    "imported": 1,
    "model_id": 401
  }
}

The response fields are as follows.

Field	Type	Description
`code`	string	`OK` on success.
`msg`	string	`OK` on success.
`data.imported`	integer	The number of entries imported and written this time.
`data.model_id`	integer	Receives the imported knowledge base ID.

Error response¶

{
  "code": "ErrConflict",
  "msg": "duplicate semantic entry key",
  "data": null
}

Common HTTP errors¶

HTTP status code	error code	Common causes	Recommended actions
`400`	`ErrParamInvalid`	`entries` is empty, one of the items does not conform to the type contract, or the target knowledge base already has a semantic entry.	Resubmit the entire batch after correcting each entry; if the target already has entries, use a knowledge base without semantic entries instead.
`401`	`ErrUnauthorized`	The API Key is invalid or has expired.	Check API Key.
`403`	`ErrForbidden`	The caller does not have import permissions.	Check workspace and object authorization.
`404`	`ErrNotFound`	The knowledge base does not exist or is not visible.	Reconfirm `model_id`.
`409`	`ErrConflict`	There is a duplicate `key` in the same request, or the service refuses the conflicting write.	Resubmit after removing duplicates.
`500`	`ErrServer`	The service failed to import the entry.	Keep the desensitized response information and try again.

Follow-up operations¶

Query semantic entries and Verify semantic entries to confirm the import results.

Last updated on Sep 3, 2026