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

# query_visual

Create one read-only visual from LeapView semantic model fields. Data is queried from semantic models; do not provide inline data.

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

## Contract

| Property | Value |
| --- | --- |
| Required privilege | `QUERY_DATA` |
| Effect | `read` |
| Operation | `manual` |
| Tags | `analytics`, `visualization` |
| Defaults | `{"limit":50}` |
| MCP annotations | read-only, idempotent, non-destructive, closed-world |

## Input schema

```json
{
  "additionalProperties": false,
  "properties": {
    "columns": {
      "description": "Optional table column display configuration.",
      "items": {
        "additionalProperties": false,
        "properties": {
          "align": {
            "type": "string"
          },
          "columnValue": {
            "type": "string"
          },
          "format": {
            "type": "string"
          },
          "formatting": {
            "items": {
              "additionalProperties": false,
              "properties": {
                "background": {
                  "type": "string"
                },
                "color": {
                  "type": "string"
                },
                "highColor": {
                  "type": "string"
                },
                "kind": {
                  "type": "string"
                },
                "lowColor": {
                  "type": "string"
                },
                "max": {
                  "type": "number"
                },
                "min": {
                  "type": "number"
                },
                "values": {
                  "additionalProperties": {
                    "type": "string"
                  },
                  "type": "object"
                }
              },
              "required": [
                "kind"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "group": {
            "type": "string"
          },
          "key": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "measure": {
            "type": "string"
          },
          "role": {
            "type": "string"
          },
          "width": {
            "type": "integer"
          }
        },
        "required": [
          "key",
          "label"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "dataset": {
      "description": "Semantic dataset/table ID.",
      "minLength": 1,
      "type": "string"
    },
    "dimensions": {
      "description": "Dimension fields for chart grouping.",
      "items": {
        "additionalProperties": false,
        "properties": {
          "alias": {
            "description": "Optional output alias.",
            "type": "string"
          },
          "field": {
            "description": "Semantic field ID.",
            "minLength": 1,
            "type": "string"
          }
        },
        "required": [
          "field"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "fields": {
      "description": "Fields for table output.",
      "items": {
        "additionalProperties": false,
        "properties": {
          "alias": {
            "description": "Optional output alias.",
            "type": "string"
          },
          "field": {
            "description": "Semantic field ID.",
            "minLength": 1,
            "type": "string"
          }
        },
        "required": [
          "field"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "filters": {
      "description": "Governed semantic filters applied before visualization. Inline data and arbitrary expressions are not accepted.",
      "items": {
        "additionalProperties": false,
        "properties": {
          "fact": {
            "description": "Fact table used to resolve an otherwise ambiguous conformed dimension.",
            "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": "Nested governed filters. The next recursive level is validated by the tool provider.",
                  "items": {
                    "additionalProperties": {},
                    "type": "object"
                  },
                  "type": "array"
                }
              },
              "required": [
                "filters"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "operator": {
            "description": "Governed comparison operator. Defaults to equals.",
            "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": {
      "description": "Maximum result rows.",
      "maximum": 50,
      "minimum": 1,
      "type": "integer"
    },
    "measures": {
      "description": "Measure fields for chart values.",
      "items": {
        "additionalProperties": false,
        "properties": {
          "alias": {
            "description": "Optional output alias.",
            "type": "string"
          },
          "field": {
            "description": "Semantic field ID.",
            "minLength": 1,
            "type": "string"
          }
        },
        "required": [
          "field"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "model": {
      "description": "Semantic model ID.",
      "minLength": 1,
      "type": "string"
    },
    "presentation": {
      "additionalProperties": false,
      "properties": {
        "align": {
          "type": "string"
        },
        "area": {
          "type": "boolean"
        },
        "basemap": {
          "type": "string"
        },
        "breadcrumb": {
          "type": "boolean"
        },
        "centerLabel": {
          "type": "string"
        },
        "curveness": {
          "maximum": 1,
          "minimum": 0,
          "type": "number"
        },
        "dataZoom": {
          "type": "boolean"
        },
        "dualAxis": {
          "type": "boolean"
        },
        "focus": {
          "type": "string"
        },
        "histogramBins": {
          "maximum": 60,
          "minimum": 5,
          "type": "integer"
        },
        "initialDepth": {
          "minimum": 0,
          "type": "integer"
        },
        "innerRadius": {
          "minimum": 0,
          "type": "number"
        },
        "labelPosition": {
          "enum": [
            "inside",
            "outside",
            "top",
            "right",
            "bottom",
            "left",
            "center"
          ],
          "type": "string"
        },
        "layout": {
          "type": "string"
        },
        "legend": {
          "enum": [
            "none",
            "top",
            "right",
            "bottom",
            "left"
          ],
          "type": "string"
        },
        "maximum": {
          "type": "number"
        },
        "minimum": {
          "type": "number"
        },
        "nodeGap": {
          "minimum": 0,
          "type": "number"
        },
        "note": {
          "type": "string"
        },
        "orientation": {
          "enum": [
            "horizontal",
            "vertical"
          ],
          "type": "string"
        },
        "outerRadius": {
          "minimum": 0,
          "type": "number"
        },
        "progressWidth": {
          "minimum": 0,
          "type": "number"
        },
        "roam": {
          "type": "boolean"
        },
        "rose": {
          "type": "boolean"
        },
        "seriesTypes": {
          "additionalProperties": {
            "enum": [
              "line",
              "area",
              "bar",
              "column"
            ],
            "type": "string"
          },
          "type": "object"
        },
        "showLabels": {
          "type": "boolean"
        },
        "showSymbols": {
          "type": "boolean"
        },
        "smooth": {
          "type": "boolean"
        },
        "sort": {
          "type": "string"
        },
        "stacked": {
          "type": "boolean"
        },
        "step": {
          "type": "boolean"
        },
        "symbolSize": {
          "minimum": 0,
          "type": "number"
        },
        "thresholds": {
          "items": {
            "additionalProperties": false,
            "properties": {
              "tone": {
                "type": "string"
              },
              "value": {
                "type": "number"
              }
            },
            "required": [
              "tone",
              "value"
            ],
            "type": "object"
          },
          "type": "array"
        },
        "tone": {
          "type": "string"
        }
      },
      "type": "object"
    },
    "rows": {
      "description": "Row fields for matrix-style table output.",
      "items": {
        "additionalProperties": false,
        "properties": {
          "alias": {
            "description": "Optional output alias.",
            "type": "string"
          },
          "field": {
            "description": "Semantic field ID.",
            "minLength": 1,
            "type": "string"
          }
        },
        "required": [
          "field"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "series": {
      "additionalProperties": false,
      "properties": {
        "alias": {
          "description": "Optional output alias.",
          "type": "string"
        },
        "field": {
          "description": "Semantic field ID.",
          "minLength": 1,
          "type": "string"
        }
      },
      "required": [
        "field"
      ],
      "type": "object"
    },
    "sort": {
      "description": "Sort fields applied to the query result.",
      "items": {
        "additionalProperties": false,
        "properties": {
          "direction": {
            "description": "Sort direction.",
            "enum": [
              "asc",
              "desc"
            ],
            "type": "string"
          },
          "field": {
            "description": "Semantic field ID.",
            "minLength": 1,
            "type": "string"
          }
        },
        "required": [
          "field"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "title": {
      "description": "Optional display title.",
      "type": "string"
    },
    "type": {
      "enum": [
        "line",
        "area",
        "bar",
        "column",
        "pie",
        "donut",
        "scatter",
        "funnel",
        "treemap",
        "gauge",
        "heatmap",
        "sankey",
        "graph",
        "map",
        "candlestick",
        "boxplot",
        "combo",
        "waterfall",
        "histogram",
        "radar",
        "tree",
        "sunburst",
        "kpi",
        "table",
        "matrix",
        "pivot"
      ],
      "type": "string"
    },
    "workspace": {
      "minLength": 1,
      "type": "string"
    }
  },
  "required": [
    "dataset",
    "model",
    "type",
    "workspace"
  ],
  "type": "object"
}
```

## Output schema

```json
{
  "additionalProperties": false,
  "properties": {
    "completeness": {
      "additionalProperties": false,
      "properties": {
        "limit": {
          "type": "integer"
        },
        "returnedRows": {
          "type": "integer"
        },
        "status": {
          "enum": [
            "complete",
            "limit_reached",
            "empty"
          ],
          "type": "string"
        }
      },
      "required": [
        "limit",
        "returnedRows",
        "status"
      ],
      "type": "object"
    },
    "datasetRef": {
      "additionalProperties": false,
      "properties": {
        "id": {
          "minLength": 1,
          "type": "string"
        },
        "type": {
          "enum": [
            "workspace",
            "dashboard",
            "page",
            "visual",
            "filter",
            "semantic_model",
            "semantic_table",
            "field",
            "measure"
          ],
          "type": "string"
        },
        "workspaceId": {
          "minLength": 1,
          "type": "string"
        }
      },
      "required": [
        "id",
        "type",
        "workspaceId"
      ],
      "type": "object"
    },
    "diagnostics": {
      "items": {
        "additionalProperties": false,
        "properties": {
          "code": {
            "type": "string"
          },
          "fieldId": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "severity": {
            "enum": [
              "info",
              "warning",
              "error"
            ],
            "type": "string"
          }
        },
        "required": [
          "code",
          "message",
          "severity"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "fields": {
      "items": {
        "additionalProperties": false,
        "properties": {
          "alias": {
            "type": "string"
          },
          "dataType": {
            "type": "string"
          },
          "format": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "ref": {
            "additionalProperties": false,
            "properties": {
              "id": {
                "minLength": 1,
                "type": "string"
              },
              "type": {
                "enum": [
                  "workspace",
                  "dashboard",
                  "page",
                  "visual",
                  "filter",
                  "semantic_model",
                  "semantic_table",
                  "field",
                  "measure"
                ],
                "type": "string"
              },
              "workspaceId": {
                "minLength": 1,
                "type": "string"
              }
            },
            "required": [
              "id",
              "type",
              "workspaceId"
            ],
            "type": "object"
          },
          "role": {
            "enum": [
              "dimension",
              "series",
              "measure",
              "table_field",
              "table_row"
            ],
            "type": "string"
          },
          "unit": {
            "type": "string"
          }
        },
        "required": [
          "label",
          "ref",
          "role"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "filters": {
      "items": {
        "additionalProperties": false,
        "properties": {
          "operator": {
            "enum": [
              "equals",
              "in",
              "contains",
              "not_contains",
              "starts_with",
              "greater_than_or_equal",
              "less_than",
              "is_null",
              "is_not_null"
            ],
            "type": "string"
          },
          "path": {
            "description": "Zero-based nested group path. Omitted for a root-level filter.",
            "items": {
              "type": "integer"
            },
            "type": "array"
          },
          "ref": {
            "additionalProperties": false,
            "properties": {
              "id": {
                "minLength": 1,
                "type": "string"
              },
              "type": {
                "enum": [
                  "workspace",
                  "dashboard",
                  "page",
                  "visual",
                  "filter",
                  "semantic_model",
                  "semantic_table",
                  "field",
                  "measure"
                ],
                "type": "string"
              },
              "workspaceId": {
                "minLength": 1,
                "type": "string"
              }
            },
            "required": [
              "id",
              "type",
              "workspaceId"
            ],
            "type": "object"
          },
          "resolvedFactRef": {
            "additionalProperties": false,
            "properties": {
              "id": {
                "minLength": 1,
                "type": "string"
              },
              "type": {
                "enum": [
                  "workspace",
                  "dashboard",
                  "page",
                  "visual",
                  "filter",
                  "semantic_model",
                  "semantic_table",
                  "field",
                  "measure"
                ],
                "type": "string"
              },
              "workspaceId": {
                "minLength": 1,
                "type": "string"
              }
            },
            "required": [
              "id",
              "type",
              "workspaceId"
            ],
            "type": "object"
          },
          "values": {
            "description": "Comparison values. Omitted for unary operators.",
            "items": {
              "type": "string"
            },
            "type": "array"
          }
        },
        "required": [
          "operator",
          "ref"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "freshness": {
      "additionalProperties": false,
      "properties": {
        "lastSuccessfulRefreshAt": {
          "description": "Completion time of the last successful publish or refresh. This is not an upstream event-time watermark.",
          "type": "string"
        },
        "servingStateId": {
          "description": "Serving state that produced the successful data version.",
          "type": "string"
        },
        "snapshotId": {
          "description": "DuckLake snapshot ID recorded for the successful data version.",
          "type": "string"
        },
        "source": {
          "description": "Whether the data version came from publish or refresh.",
          "enum": [
            "publish",
            "refresh"
          ],
          "type": "string"
        },
        "status": {
          "description": "current when the successful data version belongs to the queried serving snapshot; stale otherwise.",
          "enum": [
            "current",
            "stale"
          ],
          "type": "string"
        }
      },
      "required": [
        "lastSuccessfulRefreshAt",
        "servingStateId",
        "snapshotId",
        "source",
        "status"
      ],
      "type": "object"
    },
    "id": {
      "type": "string"
    },
    "modelRef": {
      "additionalProperties": false,
      "properties": {
        "id": {
          "minLength": 1,
          "type": "string"
        },
        "type": {
          "enum": [
            "workspace",
            "dashboard",
            "page",
            "visual",
            "filter",
            "semantic_model",
            "semantic_table",
            "field",
            "measure"
          ],
          "type": "string"
        },
        "workspaceId": {
          "minLength": 1,
          "type": "string"
        }
      },
      "required": [
        "id",
        "type",
        "workspaceId"
      ],
      "type": "object"
    },
    "ok": {
      "type": "boolean"
    },
    "queryId": {
      "type": "string"
    },
    "servingSnapshot": {
      "type": "string"
    },
    "signal": {
      "type": "string"
    },
    "status": {
      "additionalProperties": false,
      "properties": {
        "kind": {
          "enum": [
            "idle",
            "loading",
            "ready",
            "no_data",
            "partial",
            "error"
          ],
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      },
      "required": [
        "kind"
      ],
      "type": "object"
    },
    "summary": {
      "type": "string"
    },
    "title": {
      "type": "string"
    },
    "type": {
      "type": "string"
    }
  },
  "required": [
    "completeness",
    "datasetRef",
    "diagnostics",
    "fields",
    "filters",
    "id",
    "modelRef",
    "ok",
    "queryId",
    "servingSnapshot",
    "signal",
    "status",
    "summary",
    "title",
    "type"
  ],
  "type": "object"
}
```