Create semantic entries¶

Create semantic configuration entries to supplement data tables with definitions of fields, indicators, associations, and business rules.

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

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.

Set the operation-specific values used in the request:

$MODEL_ID: ID of the knowledge base for which the semantic entry is to be created.

Request¶

Input examples

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

Parameter reference

Path parameters

Parameters	Type	Description
`model_id`	integer	The knowledge base ID for which the semantic entry is to be created.

Request body

Field	Type	Required	Description
`kind`	string	Yes	Entry type; it determines the structure of `spec`.
`key`	string	Yes	A stable reference key within the knowledge base.
`tables`	array[string]	No	The associated table name, not the Catalog table ID.
`spec`	object	Yes	A type-specific configuration object; fields are determined by `kind`.

key must be unique in the same knowledge base; tables can be omitted when not passed. When passed in, each name must be a configured table of the knowledge base.

`spec` configuration¶

In the same entry, first select kind and then submit the corresponding spec field according to the table below.

Console Name	`kind`	`spec` Required Field	Purpose
Dimension column	`dimension`	`column` (string)	Describes the fields used for grouping and filtering.
Fact column	`fact`	`column` (string)	Describes the fact fields that can participate in the calculation.
Business indicators	`metric`	`expr` (string)	Define the indicator calculation expression.
Table association	`relationship`	`left_table` (string), `right_table` (string), `join_columns` (object[])	Define the association of two configured tables.
Column preferences	`column_preference`	`preferred` (string), `deprecated` (string)	Specify recommended and non-recommended columns.
Named filter	`named_filter`	`expr` (string)	Define a reusable filter expression.
Default constraints	`default_constraint`	`column` (string), `values` (string[])	Defines the default filter constraints for the column; only supports configuration through API.
Standard Q&A	`verified_query`	`question` (string), `sql` (string)	Save high-frequency questions and their SQL.
Terminology explanation	`glossary`	`term` (string), `definition` (string)	Define business terms and their meanings.
Rule injection	`logic_text`	`content` (string), `injection_stages` (string[])	Apply business rules at the specified stage.
SQL result set	`sql_resultset`	`sql` (string), `description` (string)	Save SQL result set definition.

[] after a type means an array. For example, string[] is an array of strings.

Type-specific constraints¶

`kind`	Field or condition	Constraint
`relationship`	`join_columns`	The array cannot be empty; each item must contain a non-empty `left` and `right` (string).
`column_preference`	`preferred`, `deprecated`	Neither value can be empty, and cannot be the same without case sensitivity.
`default_constraint`	`values`	Contains at least one non-empty string; optional `operator` is `=`, `!=`, `<>`, `IN`, or `NOT IN`.
`logic_text`	`injection_stages`	The array cannot be empty; each item can only be `planner_policy`, `sql_generation`, `sql_followup`, `sql_regenerate`, `sql_decomposition`, `executor_rule` or `renderer_rule`.
`sql_resultset`	`sql`, `description`	`sql` 16 KiB or less; `description` 1000 characters or less.

`sql_resultset` optional configuration¶

Field	Type	Required	Description
`resolve_mode`	string	No	Can only be `semantic` or `passthrough`. `expand_sql` cannot be set when set to `passthrough`.
`max_rows`	integer	No	Cannot be less than `0`.
`max_bytes`	integer	No	Cannot be less than `0`.
`timeout_seconds`	integer	No	Range is `0` to `60`.
`expand_sql`	object	No	SQL expansion configuration. Both `expand_sql.sql` and `expand_sql.params` must be submitted during setup.
`expand_sql.sql`	string	Conditionally required	No more than 16 KiB; `{{parameter_name}}` must correspond to `expand_sql.params` one-to-one.
`expand_sql.params`	array[string]	Conditionally required	Quantity is `1` to `8`. Each name begins with a letter or underscore and can only contain letters, numbers, or underscores; it cannot be repeated if it is case-insensitive, and must be used in `expand_sql.sql`.
`retrieval`	object	No	Retrieve configuration.
`retrieval.enabled`	boolean	No	When set to `true`, `retrieval.embedding_model` must also be submitted.
`retrieval.embedding_model`	string	Conditionally required	`retrieval.enabled` must be a non-empty string when it is `true`.

Successful response¶

Return 201 on success; save data.id for subsequent updates and deletions.

Response example

JSON
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "id": 501,
    "kind": "metric",
    "key": "total_rows",
    "tables": ["orders"],
    "spec": {
      "expr": "COUNT(*)"
    },
    "created_at": 1735632000,
    "updated_at": 1735632000
  }
}

Field reference

The response fields are as follows.

Field	Type	Description
`code`	string	`OK` on success.
`msg`	string	`OK` on success.
`data.id`	integer	New entry ID.
`data.kind`	string	The type of entry created.
`data.key`	string	Stable reference key within the knowledge base.
`data.tables`	array[string]	Association table name; may be omitted if not set.
`data.spec`	object	Saved type-specific configuration object; fields determined by `data.kind`.
`data.created_at`	integer	Unix timestamp.
`data.updated_at`	integer	Unix timestamp.

Error response¶

Response example

JSON
{
  "code": "ErrParamInvalid",
  "msg": "invalid semantic entry",
  "data": null
}

Field reference

Common HTTP errors¶

HTTP status code	error code	Common causes	Recommended actions
`400`	`ErrParamInvalid`	`kind`, `key` or `spec` does not comply with the entry type contract.	Fix the complete entry definition and try again.
`401`	`ErrUnauthorized`	The API Key is invalid or has expired.	Check API Key.
`403`	`ErrForbidden`	The caller does not have permission to create entries.	Check workspace and object authorization.
`404`	`ErrNotFound`	The knowledge base does not exist or is not visible.	Reconfirm `model_id`.
`409`	`ErrConflict`	A conflicting entry key already exists in the same knowledge base.	Use a different `key` or update an existing entry.
`500`	`ErrServer`	The service failed to create the entry.	Keep the desensitized response information and try again.

Follow-up operations¶

Use data.id Update semantic entries or Delete semantic entries.

Last updated on Sep 15, 2026