<!-- Code generated by internal/app/tools/agenttooldocgen; DO NOT EDIT. -->

# query_semantic_model

Query governed semantic data with typed columns, filters, pagination, and provenance

Machine-readable: [focused JSON](/docs/agent-tools/tools/query_semantic_model.json) · [complete manifest](/docs/agent-tools/manifest.json)

## Contract

| Property | Value |
| --- | --- |
| Required privilege | `QUERY_DATA` |
| Effect | `read` |
| Operation | `querySemanticModel` |
| Tags | `semantic-model`, `query` |
| Defaults | `{"limit":25}` |
| MCP annotations | read-only, idempotent, non-destructive, closed-world |

## Input schema

```json
{
  "additionalProperties": false,
  "properties": {
    "dimensions": {
      "items": {
        "additionalProperties": false,
        "properties": {
          "alias": {
            "description": "Optional output column name.",
            "type": "string"
          },
          "field": {
            "description": "Semantic field or measure ID. Use the ID returned by catalog_list or catalog_get.",
            "type": "string"
          }
        },
        "required": [
          "field"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "filters": {
      "items": {
        "additionalProperties": false,
        "properties": {
          "fact": {
            "description": "Fact table used to resolve a conformed dimension when it is otherwise ambiguous.",
            "type": "string"
          },
          "field": {
            "description": "Semantic field ID. Omit only when groups supplies nested filters.",
            "type": "string"
          },
          "groups": {
            "description": "Nested filter groups.",
            "items": {
              "additionalProperties": false,
              "properties": {
                "filters": {
                  "description": "Filters combined within this nested group.",
                  "items": {
                    "type": "object"
                  },
                  "type": "array"
                }
              },
              "required": [
                "filters"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "operator": {
            "description": "Governed comparison operator. equals is used when omitted.",
            "enum": [
              "equals",
              "in",
              "contains",
              "not_contains",
              "starts_with",
              "greater_than_or_equal",
              "less_than",
              "is_null",
              "is_not_null"
            ],
            "type": "string"
          },
          "values": {
            "description": "Comparison values. is_null and is_not_null accept no values.",
            "items": {
              "type": "string"
            },
            "type": "array"
          }
        },
        "type": "object"
      },
      "type": "array"
    },
    "limit": {
      "maximum": 50,
      "minimum": 1,
      "type": "integer"
    },
    "measures": {
      "items": {
        "additionalProperties": false,
        "properties": {
          "alias": {
            "description": "Optional output column name.",
            "type": "string"
          },
          "field": {
            "description": "Semantic field or measure ID. Use the ID returned by catalog_list or catalog_get.",
            "type": "string"
          }
        },
        "required": [
          "field"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "model": {
      "type": "string"
    },
    "pageToken": {
      "maxLength": 2048,
      "minLength": 1,
      "type": "string"
    },
    "sort": {
      "items": {
        "additionalProperties": false,
        "properties": {
          "direction": {
            "description": "Sort direction. Defaults to ascending when omitted.",
            "enum": [
              "asc",
              "desc"
            ],
            "type": "string"
          },
          "field": {
            "description": "Selected output field or alias to sort.",
            "type": "string"
          }
        },
        "required": [
          "field"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "time": {
      "additionalProperties": false,
      "properties": {
        "alias": {
          "description": "Optional output column name.",
          "type": "string"
        },
        "field": {
          "description": "Date or timestamp field ID.",
          "type": "string"
        },
        "grain": {
          "description": "Calendar grain used to group the time field.",
          "enum": [
            "day",
            "week",
            "month",
            "quarter",
            "year"
          ],
          "type": "string"
        }
      },
      "required": [
        "field"
      ],
      "type": "object"
    },
    "workspace": {
      "description": "Workspace ID to query.",
      "minLength": 1,
      "type": "string"
    }
  },
  "required": [
    "model",
    "workspace"
  ],
  "type": "object"
}
```

## Output schema

```json
{
  "additionalProperties": false,
  "properties": {
    "columns": {
      "items": {
        "additionalProperties": false,
        "properties": {
          "dataType": {
            "enum": [
              "boolean",
              "int64",
              "decimal",
              "float64",
              "string",
              "date",
              "timestamp",
              "json"
            ],
            "type": "string"
          },
          "fieldRef": {
            "additionalProperties": false,
            "properties": {
              "id": {
                "type": "string"
              },
              "type": {
                "type": "string"
              },
              "workspaceId": {
                "type": "string"
              }
            },
            "required": [
              "id",
              "type",
              "workspaceId"
            ],
            "type": "object"
          },
          "format": {
            "type": "string"
          },
          "kind": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "nullable": {
            "type": "boolean"
          },
          "unit": {
            "type": "string"
          }
        },
        "required": [
          "dataType",
          "name",
          "nullable"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "completeness": {
      "additionalProperties": false,
      "properties": {
        "hasMore": {
          "type": "boolean"
        },
        "returnedRows": {
          "type": "integer"
        }
      },
      "required": [
        "hasMore",
        "returnedRows"
      ],
      "type": "object"
    },
    "freshness": {
      "additionalProperties": false,
      "properties": {
        "lastSuccessfulRefreshAt": {
          "type": "string"
        },
        "servingStateId": {
          "type": "string"
        },
        "snapshotId": {
          "type": "string"
        },
        "source": {
          "type": "string"
        },
        "status": {
          "type": "string"
        }
      },
      "required": [
        "lastSuccessfulRefreshAt",
        "servingStateId",
        "snapshotId",
        "source",
        "status"
      ],
      "type": "object"
    },
    "hasMore": {
      "type": "boolean"
    },
    "nextCursor": {
      "type": "string"
    },
    "queryId": {
      "type": "string"
    },
    "rows": {
      "items": {
        "items": {},
        "type": "array"
      },
      "type": "array"
    },
    "servingSnapshot": {
      "type": "string"
    }
  },
  "required": [
    "columns",
    "completeness",
    "hasMore",
    "queryId",
    "rows",
    "servingSnapshot"
  ],
  "type": "object"
}
```