Update semantic entries¶

Updates a semantic entry with the complete entry definition.

HTTP
PUT $CLOUDSIGMA_API_BASE/semantic-models/{model_id}/entries/{entry_id}

Before you call this API¶

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

First query the semantic entry to read the original entry and obtain the entry ID and existing definition to avoid missing existing fields.

Set the operation-specific values used in the request:

$MODEL_ID: Knowledge Base ID.
$ENTRY_ID: ID of the semantic entry to be updated.

Request¶

Input examples

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

Parameter reference

Path parameters

Parameters	Type	Description
`model_id`	integer	Knowledge base ID.
`entry_id`	integer	ID of the semantic entry to be updated.

Request body

Updates use full replacement semantics. Resubmit kind, key, and spec; also resubmit tables when you need to preserve the association table. The kind of the created entry cannot be changed.

Field	Type	Required	Description
`kind`	string	Yes	Entry type; must be consistent with the type of an existing entry and determines the structure of `spec`.
`key`	string	Yes	A stable reference key within the knowledge base.
`tables`	array[string]	No	Association table name; resubmit if needed.
`spec`	object	Yes	A type-specific configuration object. See Create semantic entry for the complete fields and constraints.

Successful response¶

Returns 200 on success. The interface returns a confirmation mark; if you need to read the latest entry definition, please query the entry list again.

Response example

JSON
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "updated": true
  }
}

Field reference

The response fields are as follows.

Field	Type	Description
`code`	string	`OK` on success.
`msg`	string	`OK` on success.
`data.updated`	boolean	`true` indicates that the update has been completed.

Error response¶

Response example

JSON
{
  "code": "ErrNotFound",
  "msg": "resource not found",
  "data": null
}

Field reference

Common HTTP errors¶

HTTP status code	error code	Common causes	Recommended actions
`400`	`ErrParamInvalid`	The path ID or full entry definition is invalid, or `kind` in the request is inconsistent with an existing entry.	After re-reading the entries, submit the complete `key`, `tables` and `spec` using the original `kind`.
`401`	`ErrUnauthorized`	The API Key is invalid or has expired.	Check API Key.
`403`	`ErrForbidden`	The caller does not have update permissions.	Check workspace and object authorization.
`404`	`ErrNotFound`	The knowledge base or entry does not exist or is not visible to the current caller.	Reconfirm ID.
`409`	`ErrConflict`	Entry key conflicts with existing definition.	Adjust `key` or update conflicting entries.
`500`	`ErrServer`	The service failed to update the entry.	Keep the desensitized response information and try again.

Follow-up operations¶

Query semantic entries reads the latest updated entry definition.

Last updated on Sep 15, 2026