Query structured knowledge within a task¶
Execute a read-only structured query within the current task’s authorized scope.
POST https://api.moi.matrixorigin.cn/v5/semantic-models/runtime/query
Before you call this API¶
Use only the injected service address, technical credentials, workspace, and short-lived authorization in the current task environment. Preserve the original authorization header. An ordinary PAT neither replaces task identity nor establishes authorization. Examples use jq. See common information for variables, objects, and states.
Request body¶
curl -X POST "${MOI_ENDPOINT%/}/semantic-models/runtime/query" \
-H "X-API-Key: $MOI_API_KEY" \
-H "X-Workspace-ID: $MOI_WORKSPACE_ID" \
-H "X-MOI-Runtime-Authorization: $MOI_RUNTIME_AUTHORIZATION" \
-H 'Content-Type: application/json' \
--data-binary "$(jq -n --arg REQUEST_ID "$REQUEST_ID" --rawfile KNOWLEDGE_SQL_FILE "$KNOWLEDGE_SQL_FILE" '
{
"request_id": $REQUEST_ID,
"sql": $KNOWLEDGE_SQL_FILE,
"max_rows": 100
}
')"
Generate the SQL file from the preceding table structure and current question. Do not access out-of-scope tables or write. Inspect truncated, row counts, actual sources, and applied constraints. Save a sql_result artifact before reading and citing it.
Field |
Type |
Required |
Description |
|---|---|---|---|
|
string |
Yes |
Unique operation ID, 1–256 bytes, without leading/trailing whitespace or an audit: prefix. Retain it when replaying identical input. |
|
string |
Yes |
Read-only SELECT over tables allowed in the current task. |
|
integer |
No |
Omission/0 uses 200; above 1000 uses 1000. Negative values invalid. |
|
string (array of strings) |
No |
Semantic entry identifiers actually used. Omission cannot bypass mandatory semantic constraints. |
Successful response¶
{
"code": "OK",
"msg": "OK",
"data": {
"call_id": "request_example",
"output": {
"artifact_id": "sql_result_example",
"sql": "SELECT 1 AS value",
"db_name": "example",
"columns": [
"value"
],
"rows": [
[
1
]
],
"row_count": 1,
"max_rows": 100,
"table_names": []
}
}
}
Field |
Type |
Description |
|---|---|---|
|
string |
OK on success. |
|
string |
Response description. |
|
string |
Corresponding original request_id. |
|
boolean |
true indicates business failure; false may be omitted. |
|
object |
Current operation result. |
|
object (array of objects) |
Original artifacts and evidence from the same task. |
|
object |
Operation metadata, when present. |
|
string |
Raw value returned by the current operation; retain according to common objects. |
|
string |
Raw value returned by the current operation; retain according to common objects. |
|
string |
Raw value returned by the current operation; retain according to common objects. |
|
array |
Query result column names. |
|
array |
Query result rows. |
|
integer |
Row or hit count for the current operation. |
|
integer |
Raw value returned by the current operation; retain according to common objects. |
|
array |
Raw value returned by the current operation; retain according to common objects. |
Error responses¶
Handle HTTP status, business results, and error fields. See errors and environments. On source/version conflicts, read current state rather than automatically replacing identities, resources, or request IDs and retrying.