{
  "schemaVersion": 1,
  "operation": {
    "operationId": "querySemanticModel",
    "method": "POST",
    "path": "/api/v1/workspaces/{workspace}/semantic-models/{model}/query",
    "summary": "Query governed semantic data with typed columns, filters, pagination, and provenance",
    "description": "",
    "tags": [
      "BI"
    ],
    "effect": "read",
    "confirmation": "never",
    "authorization": {
      "mode": "privilege",
      "privilege": "QUERY_DATA"
    },
    "tool": {
      "name": "query_semantic_model",
      "effect": "read",
      "confirmation": "never"
    },
    "parameters": [
      {
        "name": "workspace",
        "in": "path",
        "required": true,
        "description": "",
        "schema": {
          "minLength": 1,
          "type": "string"
        }
      },
      {
        "name": "model",
        "in": "path",
        "required": true,
        "description": "",
        "schema": {
          "type": "string"
        }
      },
      {
        "name": "accept",
        "in": "header",
        "required": false,
        "description": "",
        "schema": {
          "type": "string"
        }
      }
    ],
    "requestBody": {
      "required": false,
      "description": "",
      "content": [
        {
          "contentType": "application/json",
          "schema": {
            "$ref": "#/components/schemas/SemanticQueryRequest"
          }
        }
      ]
    },
    "responses": [
      {
        "status": "200",
        "description": "The request has succeeded.",
        "content": [
          {
            "contentType": "application/json",
            "schema": {
              "$ref": "#/components/schemas/SemanticQueryResponse"
            }
          },
          {
            "contentType": "application/vnd.apache.arrow.stream",
            "schema": {
              "format": "binary",
              "type": "string"
            }
          }
        ]
      },
      {
        "status": "400",
        "description": "The server could not understand the request due to invalid syntax.",
        "content": [
          {
            "contentType": "application/problem+json",
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        ]
      },
      {
        "status": "401",
        "description": "Access is unauthorized.",
        "content": [
          {
            "contentType": "application/problem+json",
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        ]
      },
      {
        "status": "403",
        "description": "Access is forbidden.",
        "content": [
          {
            "contentType": "application/problem+json",
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        ]
      },
      {
        "status": "404",
        "description": "The server cannot find the requested resource.",
        "content": [
          {
            "contentType": "application/problem+json",
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        ]
      },
      {
        "status": "409",
        "description": "The request conflicts with the current state of the server.",
        "content": [
          {
            "contentType": "application/problem+json",
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        ]
      },
      {
        "status": "412",
        "description": "Precondition failed.",
        "content": [
          {
            "contentType": "application/problem+json",
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        ]
      },
      {
        "status": "413",
        "description": "Client error",
        "content": [
          {
            "contentType": "application/problem+json",
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        ]
      },
      {
        "status": "415",
        "description": "Client error",
        "content": [
          {
            "contentType": "application/problem+json",
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        ]
      },
      {
        "status": "422",
        "description": "Client error",
        "content": [
          {
            "contentType": "application/problem+json",
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        ]
      },
      {
        "status": "429",
        "description": "Client error",
        "content": [
          {
            "contentType": "application/problem+json",
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        ]
      },
      {
        "status": "500",
        "description": "Server error",
        "content": [
          {
            "contentType": "application/problem+json",
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        ]
      },
      {
        "status": "502",
        "description": "Server error",
        "content": [
          {
            "contentType": "application/problem+json",
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        ]
      },
      {
        "status": "503",
        "description": "Service unavailable.",
        "content": [
          {
            "contentType": "application/problem+json",
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        ]
      }
    ]
  },
  "schemas": {
    "PageInfo": {
      "example": {
        "nextCursor": "example"
      },
      "properties": {
        "nextCursor": {
          "example": "example",
          "type": "string"
        }
      },
      "type": "object"
    },
    "ProblemDetails": {
      "example": {
        "code": "example",
        "detail": "example",
        "errors": [
          {
            "code": "example",
            "detail": "example",
            "field": "example"
          }
        ],
        "instance": "example",
        "requestId": "example",
        "status": 1,
        "title": "example",
        "type": "example"
      },
      "properties": {
        "code": {
          "example": "example",
          "type": "string"
        },
        "detail": {
          "example": "example",
          "type": "string"
        },
        "errors": {
          "example": [
            {
              "code": "example",
              "detail": "example",
              "field": "example"
            }
          ],
          "items": {
            "$ref": "#/components/schemas/ProblemFieldError"
          },
          "type": "array"
        },
        "instance": {
          "example": "example",
          "type": "string"
        },
        "requestId": {
          "example": "example",
          "type": "string"
        },
        "status": {
          "example": 1,
          "format": "int32",
          "type": "integer"
        },
        "title": {
          "example": "example",
          "type": "string"
        },
        "type": {
          "example": "example",
          "type": "string"
        }
      },
      "required": [
        "type",
        "title",
        "status",
        "detail",
        "instance",
        "code",
        "requestId",
        "errors"
      ],
      "type": "object"
    },
    "ProblemFieldError": {
      "example": {
        "code": "example",
        "detail": "example",
        "field": "example"
      },
      "properties": {
        "code": {
          "example": "example",
          "type": "string"
        },
        "detail": {
          "example": "example",
          "type": "string"
        },
        "field": {
          "example": "example",
          "type": "string"
        }
      },
      "required": [
        "field",
        "code",
        "detail"
      ],
      "type": "object"
    },
    "QueryColumn": {
      "example": {
        "fieldRef": {
          "id": "example",
          "type": "example",
          "workspaceId": "example"
        },
        "format": "example",
        "kind": "example",
        "label": "example",
        "name": "example",
        "nullable": true,
        "type": "boolean",
        "unit": "example"
      },
      "properties": {
        "fieldRef": {
          "$ref": "#/components/schemas/QueryFieldRef",
          "description": "Governed catalog ref for the selected field, measure, or metric."
        },
        "format": {
          "description": "Formatting contract declared by the semantic measure or metric.",
          "example": "example",
          "type": "string"
        },
        "kind": {
          "description": "Semantic role of the selected member.",
          "enum": [
            "dimension",
            "measure",
            "metric"
          ],
          "example": "example",
          "type": "string"
        },
        "label": {
          "description": "Business-facing semantic label.",
          "example": "example",
          "type": "string"
        },
        "name": {
          "description": "Output column name used to match positional row cells.",
          "example": "example",
          "type": "string"
        },
        "nullable": {
          "description": "Whether the governed semantic definition can produce SQL NULL.",
          "example": true,
          "type": "boolean"
        },
        "type": {
          "$ref": "#/components/schemas/QueryColumnType",
          "description": "Precision-safe wire data type. Agent tools expose this property as dataType."
        },
        "unit": {
          "description": "Business unit declared by the semantic measure or metric.",
          "example": "example",
          "type": "string"
        }
      },
      "required": [
        "name",
        "type",
        "nullable"
      ],
      "type": "object"
    },
    "QueryColumnType": {
      "enum": [
        "boolean",
        "int64",
        "decimal",
        "float64",
        "string",
        "date",
        "timestamp",
        "json"
      ],
      "example": "boolean",
      "type": "string"
    },
    "QueryCompleteness": {
      "example": {
        "hasMore": true,
        "returnedRows": 1
      },
      "properties": {
        "hasMore": {
          "description": "Whether another governed page is available.",
          "example": true,
          "type": "boolean"
        },
        "returnedRows": {
          "description": "Number of rows present in this response page.",
          "example": 1,
          "format": "int32",
          "type": "integer"
        }
      },
      "required": [
        "returnedRows",
        "hasMore"
      ],
      "type": "object"
    },
    "QueryFieldRef": {
      "example": {
        "id": "example",
        "type": "example",
        "workspaceId": "example"
      },
      "properties": {
        "id": {
          "description": "Workspace-local catalog ID.",
          "example": "example",
          "type": "string"
        },
        "type": {
          "description": "Catalog type of the semantic member.",
          "enum": [
            "field",
            "measure"
          ],
          "example": "example",
          "type": "string"
        },
        "workspaceId": {
          "description": "Workspace containing the semantic member.",
          "example": "example",
          "type": "string"
        }
      },
      "required": [
        "workspaceId",
        "type",
        "id"
      ],
      "type": "object"
    },
    "QueryFreshness": {
      "example": {
        "lastSuccessfulRefreshAt": "2026-01-02T15:04:05Z",
        "servingStateId": "example",
        "snapshotId": "example",
        "source": "example",
        "status": "example"
      },
      "properties": {
        "lastSuccessfulRefreshAt": {
          "description": "Completion time of the last successful publish or refresh. This is not an upstream event-time watermark.",
          "example": "2026-01-02T15:04:05Z",
          "format": "date-time",
          "type": "string"
        },
        "servingStateId": {
          "description": "Serving state that produced the successful data version.",
          "example": "example",
          "type": "string"
        },
        "snapshotId": {
          "description": "DuckLake snapshot ID recorded for the successful data version.",
          "example": "example",
          "type": "string"
        },
        "source": {
          "description": "Whether the data version came from publish or refresh.",
          "enum": [
            "publish",
            "refresh"
          ],
          "example": "example",
          "type": "string"
        },
        "status": {
          "description": "current when the successful data version belongs to the queried serving snapshot; stale otherwise.",
          "enum": [
            "current",
            "stale"
          ],
          "example": "example",
          "type": "string"
        }
      },
      "required": [
        "lastSuccessfulRefreshAt",
        "snapshotId",
        "servingStateId",
        "source",
        "status"
      ],
      "type": "object"
    },
    "SemanticFieldRef": {
      "example": {
        "alias": "example",
        "field": "example"
      },
      "properties": {
        "alias": {
          "description": "Optional output column name.",
          "example": "example",
          "type": "string"
        },
        "field": {
          "description": "Semantic field or measure ID. Use the ID returned by catalog_list or catalog_get.",
          "example": "example",
          "type": "string"
        }
      },
      "required": [
        "field"
      ],
      "type": "object"
    },
    "SemanticFilter": {
      "example": {
        "fact": "example",
        "field": "example",
        "groups": [
          {
            "filters": []
          }
        ],
        "operator": "equals",
        "values": [
          "example"
        ]
      },
      "properties": {
        "fact": {
          "description": "Fact table used to resolve a conformed dimension when it is otherwise ambiguous.",
          "example": "example",
          "type": "string"
        },
        "field": {
          "description": "Semantic field ID. Omit only when groups supplies nested filters.",
          "example": "example",
          "type": "string"
        },
        "groups": {
          "description": "Nested filter groups.",
          "example": [
            {
              "filters": []
            }
          ],
          "items": {
            "$ref": "#/components/schemas/SemanticFilterGroup"
          },
          "type": "array"
        },
        "operator": {
          "$ref": "#/components/schemas/SemanticFilterOperator",
          "description": "Governed comparison operator. equals is used when omitted."
        },
        "values": {
          "description": "Comparison values. is_null and is_not_null accept no values.",
          "example": [
            "example"
          ],
          "items": {
            "type": "string"
          },
          "type": "array"
        }
      },
      "type": "object"
    },
    "SemanticFilterGroup": {
      "example": {
        "filters": []
      },
      "properties": {
        "filters": {
          "description": "Filters combined within this nested group.",
          "example": [
            {
              "fact": "example",
              "field": "example",
              "groups": [
                {
                  "filters": []
                }
              ],
              "operator": "equals",
              "values": [
                "example"
              ]
            }
          ],
          "items": {
            "$ref": "#/components/schemas/SemanticFilter"
          },
          "type": "array"
        }
      },
      "required": [
        "filters"
      ],
      "type": "object"
    },
    "SemanticFilterOperator": {
      "enum": [
        "equals",
        "in",
        "contains",
        "not_contains",
        "starts_with",
        "greater_than_or_equal",
        "less_than",
        "is_null",
        "is_not_null"
      ],
      "example": "equals",
      "type": "string"
    },
    "SemanticQueryRequest": {
      "example": {
        "dimensions": [
          {
            "alias": "example",
            "field": "example"
          }
        ],
        "filters": [
          {
            "fact": "example",
            "field": "example",
            "groups": [
              {
                "filters": []
              }
            ],
            "operator": "equals",
            "values": [
              "example"
            ]
          }
        ],
        "limit": 1,
        "measures": [
          {
            "alias": "example",
            "field": "example"
          }
        ],
        "pageToken": "example",
        "sort": [
          {
            "direction": "asc",
            "field": "example"
          }
        ],
        "time": {
          "alias": "example",
          "field": "example",
          "grain": "day"
        }
      },
      "properties": {
        "dimensions": {
          "example": [
            {
              "alias": "example",
              "field": "example"
            }
          ],
          "items": {
            "$ref": "#/components/schemas/SemanticFieldRef"
          },
          "type": "array"
        },
        "filters": {
          "example": [
            {
              "fact": "example",
              "field": "example",
              "groups": [
                {
                  "filters": []
                }
              ],
              "operator": "equals",
              "values": [
                "example"
              ]
            }
          ],
          "items": {
            "$ref": "#/components/schemas/SemanticFilter"
          },
          "type": "array"
        },
        "limit": {
          "example": 1,
          "format": "int32",
          "maximum": 1000,
          "minimum": 1,
          "type": "integer"
        },
        "measures": {
          "example": [
            {
              "alias": "example",
              "field": "example"
            }
          ],
          "items": {
            "$ref": "#/components/schemas/SemanticFieldRef"
          },
          "type": "array"
        },
        "pageToken": {
          "example": "example",
          "maxLength": 2048,
          "minLength": 1,
          "type": "string"
        },
        "sort": {
          "example": [
            {
              "direction": "asc",
              "field": "example"
            }
          ],
          "items": {
            "$ref": "#/components/schemas/SemanticSort"
          },
          "type": "array"
        },
        "time": {
          "$ref": "#/components/schemas/SemanticTimeRef"
        }
      },
      "type": "object"
    },
    "SemanticQueryResponse": {
      "example": {
        "columns": [
          {
            "fieldRef": {
              "id": "example",
              "type": "example",
              "workspaceId": "example"
            },
            "format": "example",
            "kind": "example",
            "label": "example",
            "name": "example",
            "nullable": true,
            "type": "boolean",
            "unit": "example"
          }
        ],
        "completeness": {
          "hasMore": true,
          "returnedRows": 1
        },
        "freshness": {
          "lastSuccessfulRefreshAt": "2026-01-02T15:04:05Z",
          "servingStateId": "example",
          "snapshotId": "example",
          "source": "example",
          "status": "example"
        },
        "page": {
          "nextCursor": "example"
        },
        "queryId": "example",
        "rows": [
          [
            "example"
          ]
        ],
        "servingSnapshot": "example"
      },
      "properties": {
        "columns": {
          "example": [
            {
              "fieldRef": {
                "id": "example",
                "type": "example",
                "workspaceId": "example"
              },
              "format": "example",
              "kind": "example",
              "label": "example",
              "name": "example",
              "nullable": true,
              "type": "boolean",
              "unit": "example"
            }
          ],
          "items": {
            "$ref": "#/components/schemas/QueryColumn"
          },
          "type": "array"
        },
        "completeness": {
          "$ref": "#/components/schemas/QueryCompleteness",
          "description": "Completeness of the exact row page returned."
        },
        "freshness": {
          "$ref": "#/components/schemas/QueryFreshness",
          "description": "Last successful data-version metadata when the model has a recorded publish or refresh."
        },
        "page": {
          "$ref": "#/components/schemas/PageInfo"
        },
        "queryId": {
          "description": "Stable identifier for this query execution.",
          "example": "example",
          "type": "string"
        },
        "rows": {
          "example": [
            [
              "example"
            ]
          ],
          "items": {
            "items": {},
            "type": "array"
          },
          "type": "array"
        },
        "servingSnapshot": {
          "description": "Immutable serving state used by the query and its continuation cursor.",
          "example": "example",
          "type": "string"
        }
      },
      "required": [
        "queryId",
        "servingSnapshot",
        "completeness",
        "columns",
        "rows",
        "page"
      ],
      "type": "object"
    },
    "SemanticSort": {
      "example": {
        "direction": "asc",
        "field": "example"
      },
      "properties": {
        "direction": {
          "$ref": "#/components/schemas/SemanticSortDirection",
          "description": "Sort direction. Defaults to ascending when omitted."
        },
        "field": {
          "description": "Selected output field or alias to sort.",
          "example": "example",
          "type": "string"
        }
      },
      "required": [
        "field"
      ],
      "type": "object"
    },
    "SemanticSortDirection": {
      "enum": [
        "asc",
        "desc"
      ],
      "example": "asc",
      "type": "string"
    },
    "SemanticTimeGrain": {
      "enum": [
        "day",
        "week",
        "month",
        "quarter",
        "year"
      ],
      "example": "day",
      "type": "string"
    },
    "SemanticTimeRef": {
      "example": {
        "alias": "example",
        "field": "example",
        "grain": "day"
      },
      "properties": {
        "alias": {
          "description": "Optional output column name.",
          "example": "example",
          "type": "string"
        },
        "field": {
          "description": "Date or timestamp field ID.",
          "example": "example",
          "type": "string"
        },
        "grain": {
          "$ref": "#/components/schemas/SemanticTimeGrain",
          "description": "Calendar grain used to group the time field."
        }
      },
      "required": [
        "field"
      ],
      "type": "object"
    }
  }
}