preview_sql

Returns the SQL query that would be executed for a given query without running it.

---

Description

Useful for debugging, understanding query structure, or when you need to execute the SQL directly. Takes the same parameters as analytics_query but returns SQL instead of data.

---

Input Schema

{
  "type": "object",
  "properties": {
    "measures": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Array of measure names"
    },
    "dimensions": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Array of dimension names"
    },
    "filters": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "member": { "type": "string" },
          "operator": { "type": "string" },
          "values": { "type": "array", "items": { "type": "string" } }
        }
      },
      "description": "Array of filter objects"
    },
    "timeDimensions": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "dimension": { "type": "string" },
          "granularity": { "type": "string" },
          "dateRange": { "type": "array", "items": { "type": "string" } }
        }
      },
      "description": "Time dimension settings"
    },
    "limit": {
      "type": "number",
      "description": "Maximum number of rows"
    },
    "order": {
      "type": "object",
      "description": "Sort order"
    }
  },
  "required": []
}

---

Use Cases

Scenario	Why Use This Tool
Debugging	Understand how the semantic layer translates your query to SQL
Performance Analysis	Examine joins and aggregations
Documentation	Include SQL in reports or documentation
Direct Execution	Run the SQL in other tools (DBeaver, DataGrip)
Learning	Understand the semantic layer mapping

---

Examples

Simple Query SQL

Request: "Show me the SQL for counting studies"

{
  "measures": ["Studies.count"]
}

Response:

{
  "sql": {
    "sql": [
      "SELECT count(*) AS \"studies__count\" FROM public.studies AS \"Studies\""
    ],
    "timeDimensionAlias": null,
    "timeDimensionField": null,
    "order": [],
    "cacheKeyQueries": [],
    "preAggregations": []
  }
}

Grouped Query SQL

Request: "What SQL runs for enrollment counts by site?"

{
  "measures": ["Enrollments.count"],
  "dimensions": ["Sites.siteName"]
}

Response:

{
  "sql": {
    "sql": [
      "SELECT \"Sites\".name AS \"sites__site_name\", count(*) AS \"enrollments__count\" FROM public.enrollments AS \"Enrollments\" LEFT JOIN public.sites AS \"Sites\" ON \"Enrollments\".site_id = \"Sites\".id GROUP BY 1"
    ]
  }
}

Filtered Query SQL

Request: "Generate SQL for active Phase 3 studies"

{
  "measures": ["Studies.count"],
  "dimensions": ["Studies.studyName"],
  "filters": [
    {
      "member": "Studies.phase",
      "operator": "equals",
      "values": ["Phase 3"]
    },
    {
      "member": "Studies.status",
      "operator": "equals",
      "values": ["Active"]
    }
  ]
}

Response:

{
  "sql": {
    "sql": [
      "SELECT \"Studies\".study_name AS \"studies__study_name\", count(*) AS \"studies__count\" FROM public.studies AS \"Studies\" WHERE (\"Studies\".phase = 'Phase 3') AND (\"Studies\".status = 'Active') GROUP BY 1"
    ]
  }
}

Time Series SQL

Request: "SQL for monthly enrollment trends"

{
  "measures": ["Enrollments.count"],
  "timeDimensions": [
    {
      "dimension": "Enrollments.enrollmentDate",
      "granularity": "month",
      "dateRange": ["2024-01-01", "2024-12-31"]
    }
  ]
}

Response:

{
  "sql": {
    "sql": [
      "SELECT date_trunc('month', \"Enrollments\".enrollment_date) AS \"enrollments__enrollment_date_month\", count(*) AS \"enrollments__count\" FROM public.enrollments AS \"Enrollments\" WHERE \"Enrollments\".enrollment_date >= '2024-01-01' AND \"Enrollments\".enrollment_date <= '2024-12-31' GROUP BY 1 ORDER BY 1"
    ],
    "timeDimensionAlias": "enrollments__enrollment_date_month",
    "timeDimensionField": "Enrollments.enrollmentDate"
  }
}

---

SQL Components Explained

Component	Description
sql	Array containing the generated SQL statement(s)
timeDimensionAlias	Alias used for time grouping column
timeDimensionField	Original time dimension field reference
order	Applied ordering clauses
cacheKeyQueries	Queries used for cache invalidation
preAggregations	Pre-aggregation tables used (if any)

---

Error Handling

Invalid Measure

{
  "error": "Cannot find measure 'Studies.invalidMeasure'"
}

Invalid Dimension

{
  "error": "Cannot find dimension 'Sites.unknownField'"
}