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

request_id

string

Yes

Unique operation ID, 1–256 bytes, without leading/trailing whitespace or an audit: prefix. Retain it when replaying identical input.

sql

string

Yes

Read-only SELECT over tables allowed in the current task.

max_rows

integer

No

Omission/0 uses 200; above 1000 uses 1000. Negative values invalid.

semantic_claims

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

code

string

OK on success.

msg

string

Response description.

data.call_id

string

Corresponding original request_id.

data.failed

boolean

true indicates business failure; false may be omitted.

data.output

object

Current operation result.

data.artifacts

object (array of objects)

Original artifacts and evidence from the same task.

data.metadata

object

Operation metadata, when present.

data.output.artifact_id

string

Raw value returned by the current operation; retain according to common objects.

data.output.sql

string

Raw value returned by the current operation; retain according to common objects.

data.output.db_name

string

Raw value returned by the current operation; retain according to common objects.

data.output.columns

array

Query result column names.

data.output.rows

array

Query result rows.

data.output.row_count

integer

Row or hit count for the current operation.

data.output.max_rows

integer

Raw value returned by the current operation; retain according to common objects.

data.output.table_names

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.

Last updated on