Import semantic entries¶

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

HTTP
POST $CLOUDSIGMA_API_BASE/semantic-models/{model_id}/import

Before you call this API¶

Configure the regional API endpoint and authentication, and select the target workspace.

First query the knowledge base list to obtain the knowledge base ID, and confirm that the target knowledge base has no semantic entries.

Set the operation-specific values used in the request:

$MODEL_ID: Receives the knowledge base ID of the imported entry.

Request¶

Input examples

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

Parameter reference

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.

Response example

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

Field reference

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¶

Response example

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

Field reference

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 15, 2026