run-raw-query
Execute arbitrary metric queries against Lightdash explores for ad-hoc analysis, debugging, or dashboard-only charts.
Instructions
Execute a raw metric query against a Lightdash explore.
This tool allows you to run arbitrary queries by specifying dimensions, metrics, filters, and sorts directly. It is useful for:
Running ad-hoc analysis without creating a saved chart
Executing queries for dashboard-only charts (which don't have a saved chart UUID)
Debugging data issues by running simplified queries
Input:
explore_name: The name of the explore (table) to query.metric_query: The query definition (dimensions, metrics, filters, etc.).limit: Optional row limit.
═══════════════════════════════════════════════════════════════════ COMPLETE WORKING EXAMPLE: ═══════════════════════════════════════════════════════════════════
metric_query: { "dimensions": ["my_table_date_day"], "metrics": [], "filters": { "dimensions": { "id": "root", "and": [ { "id": "filter_1", "target": {"fieldId": "my_table_country"}, "operator": "equals", "values": ["US"] }, { "id": "filter_2", "target": {"fieldId": "my_table_date_day"}, "values": [30], "operator": "inThePast", "required": false, "settings": { "completed": false, "unitOfTime": "days" } } ] } }, "sorts": [{"fieldId": "my_table_date_day", "descending": true}], "limit": 500, "tableCalculations": [], "additionalMetrics": [ { "name": "dau", "label": "Daily Active Users", "description": "Count of unique users", "type": "count_distinct", "sql": "${TABLE}.user_id", "table": "my_table", "baseDimensionName": "user_id", "formatOptions": {"type": "default", "separator": "default"} } ] }
Key Rules:
Field IDs: Use
table_fieldformat (e.g.,orders_amount). Useget-explore-schemato find correct IDs.Filters:
Simple:
{"operator": "equals", "values": ["value"]}Time:
{"operator": "inThePast", "values": [7], "settings": {"unitOfTime": "days", "completed": false}}
Additional Metrics: Use this to create ad-hoc metrics (like count distinct) that aren't in the dbt model.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| explore_name | Yes | Name of the explore (table) to query (e.g., 'orders', 'customers') | |
| metric_query | Yes | JSON string of the metric query configuration. Must include 'dimensions', 'metrics', etc. See description for example. | |
| limit | No | Optional: Limit number of rows returned. Default is 500. |