Create semantic entries

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

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

Preparation before calling

First query the knowledge base list to obtain the knowledge base ID. 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: ID of the knowledge base for which the semantic entry is to be created.

Request example

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

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.

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

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

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

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