> ## Documentation Index > Fetch the complete documentation index at: https://docs.lightdash.com/llms.txt > Use this file to discover all available pages before exploring further. # Execute compose SQL query > Executes a DuckDB SQL query asynchronously on the pre-aggregate DuckDB engine. Requires run-queries access (interactive viewer and up) and the compose-sql-runner feature flag. The references map exposes previous async queries' results as named tables the SQL can select from ({"orders": "queryUuid"} lets the SQL run SELECT * FROM orders); each referenced query is authorized with the same access checks as Get results, so you can reference any query you can already fetch by uuid. Direct file access in the SQL is rejected. Returns a queryUuid to poll for results via Get results. ## OpenAPI ````yaml https://raw.githubusercontent.com/lightdash/lightdash/refs/heads/main/packages/backend/src/generated/swagger.json post /api/v2/projects/{projectUuid}/query/compose-sql openapi: 3.0.0 info: title: Lightdash API version: 1.193.1 description: > Open API documentation for all public Lightdash API endpoints. # Authentication Before you get started, you might need to create a Personal Access Token to authenticate via the API. You can create a token by following this guide: https://docs.lightdash.com/references/personal_tokens license: name: MIT contact: name: Lightdash Support email: support@lightdash.com url: https://docs.lightdash.com/help-and-contact/contact/contact_info/ servers: - url: / security: [] tags: - name: My Account description: These routes allow users to manage their own user account. - name: Organizations description: >- Each user is a member of a single organization. These routes allow users to manage their organization. Most actions are only available to admin users. - name: Projects description: >- Projects belong to a single organization. These routes allow users to manage their projects, browse content, and execute queries. Users inside an organization might have access to a project from an organization-level role or they might be granted access to a project directly. - name: Spaces description: >- Spaces allow you to organize charts and dashboards within a project. They also allow granular access to content by allowing you to create private spaces, which are only accessible to the creator and admins. - name: Roles & Permissions description: >- These routes allow users to manage roles and permissions for their organization. externalDocs: url: https://docs.lightdash.com/references/roles - name: Query description: >- These routes allow users to execute and manage queries against their data warehouse. This includes metric queries, SQL queries, and retrieving query results. paths: /api/v2/projects/{projectUuid}/query/compose-sql: post: tags: - v2 - Query summary: Execute compose SQL query description: >- Executes a DuckDB SQL query asynchronously on the pre-aggregate DuckDB engine. Requires run-queries access (interactive viewer and up) and the compose-sql-runner feature flag. The references map exposes previous async queries' results as named tables the SQL can select from ({"orders": "queryUuid"} lets the SQL run SELECT * FROM orders); each referenced query is authorized with the same access checks as Get results, so you can reference any query you can already fetch by uuid. Direct file access in the SQL is rejected. Returns a queryUuid to poll for results via Get results. operationId: executeAsyncComposeSqlQuery parameters: - in: path name: projectUuid required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ExecuteAsyncComposeSqlQueryRequestParams' responses: '200': description: Success content: application/json: schema: $ref: >- #/components/schemas/ApiSuccess_ApiExecuteAsyncSqlQueryResults_ default: description: Error content: application/json: schema: $ref: '#/components/schemas/ApiErrorPayload' security: [] components: schemas: ExecuteAsyncComposeSqlQueryRequestParams: allOf: - $ref: '#/components/schemas/CommonExecuteQueryRequestParams' - properties: references: $ref: '#/components/schemas/Record_string.UUID_' description: >- Results of previous async queries exposed to the SQL as tables, keyed by table name: {"orders": ""} lets the SQL run SELECT * FROM orders. Each referenced query is authorized with the same access checks as fetching its results by uuid. Typed Record (not Record) on purpose: TSOA compiles a string-valued record to an empty object literal and validation then strips every key; a ref-aliased value type keeps additionalProperties intact (and validates the uuid format). limit: type: number format: double sql: type: string required: - sql type: object ApiSuccess_ApiExecuteAsyncSqlQueryResults_: properties: results: $ref: '#/components/schemas/ApiExecuteAsyncSqlQueryResults' status: type: string enum: - ok nullable: false required: - results - status type: object ApiErrorPayload: properties: error: properties: data: $ref: '#/components/schemas/AnyType' description: Optional data containing details of the error message: type: string description: A friendly message summarising the error name: type: string description: Unique name for the type of error statusCode: type: number format: integer description: HTTP status code required: - name - statusCode type: object status: type: string enum: - error nullable: false required: - error - status type: object description: |- The Error object is returned from the api any time there is an error. The message contains CommonExecuteQueryRequestParams: properties: parameters: $ref: '#/components/schemas/ParametersValuesMap' usePreAggregateCache: type: boolean invalidateCache: type: boolean context: $ref: '#/components/schemas/QueryExecutionContext' type: object Record_string.UUID_: properties: {} additionalProperties: type: string type: object description: Construct a type with a set of properties K of type T ApiExecuteAsyncSqlQueryResults: allOf: - $ref: '#/components/schemas/ApiExecuteAsyncQueryResultsCommon' - properties: {} type: object AnyType: description: |- This AnyType is an alias for any The goal is to make it easier to identify any type in the codebase without having to eslint-disable all the time These are only used on legacy `any` types, don't use it for new types. This is added on a separate file to avoid circular dependencies. ParametersValuesMap: $ref: '#/components/schemas/Record_string.ParameterValue_' QueryExecutionContext: enum: - dashboardView - autorefreshedDashboard - exploreView - filterAutocomplete - chartView - chartHistory - sqlChartView - sqlRunner - viewUnderlyingData - alert - scheduledDelivery - csvDownload - gsheets - scheduledGsheetsChart - scheduledGsheetsDashboard - scheduledGsheetsSqlChart - scheduledChart - scheduledDashboard - calculateTotal - calculateSubtotal - embed - ai - mcp.run_metric_query - mcp.run_sql - mcp.search_field_values - api - cli - metricsExplorer - preAggregateMaterialization - composeSqlRunner - dataAppSample type: string ApiExecuteAsyncQueryResultsCommon: properties: resolvedTimezone: type: string nullable: true usedParametersValues: $ref: '#/components/schemas/ParametersValuesMap' parameterReferences: items: type: string type: array cacheMetadata: $ref: '#/components/schemas/CacheMetadata' queryUuid: type: string required: - resolvedTimezone - usedParametersValues - parameterReferences - cacheMetadata - queryUuid type: object Record_string.ParameterValue_: properties: {} additionalProperties: $ref: '#/components/schemas/ParameterValue' type: object description: Construct a type with a set of properties K of type T CacheMetadata: properties: preAggregate: properties: reason: $ref: '#/components/schemas/PreAggregateMatchMiss' name: type: string hit: type: boolean required: - hit type: object cacheHit: type: boolean cacheKey: type: string cacheExpiresAt: type: string format: date-time cacheUpdatedTime: type: string format: date-time required: - cacheHit type: object ParameterValue: anyOf: - type: string - type: number format: double - items: type: string type: array - items: type: number format: double type: array PreAggregateMatchMiss: anyOf: - properties: reason: $ref: >- #/components/schemas/PreAggregateMissReason.NO_PRE_AGGREGATES_DEFINED required: - reason type: object - properties: fieldId: $ref: '#/components/schemas/FieldId' reason: $ref: >- #/components/schemas/PreAggregateMissReason.DIMENSION_NOT_IN_PRE_AGGREGATE required: - fieldId - reason type: object - properties: fieldId: $ref: '#/components/schemas/FieldId' reason: $ref: >- #/components/schemas/PreAggregateMissReason.METRIC_NOT_IN_PRE_AGGREGATE required: - fieldId - reason type: object - properties: fieldId: $ref: '#/components/schemas/FieldId' reason: $ref: '#/components/schemas/PreAggregateMissReason.NON_ADDITIVE_METRIC' required: - fieldId - reason type: object - properties: fieldId: $ref: '#/components/schemas/FieldId' reason: $ref: >- #/components/schemas/PreAggregateMissReason.NON_ADDITIVE_METRIC_REQUIRES_EXACT_MATCH required: - fieldId - reason type: object - properties: fieldId: $ref: '#/components/schemas/FieldId' reason: $ref: '#/components/schemas/PreAggregateMissReason.CUSTOM_SQL_METRIC' required: - fieldId - reason type: object - properties: fieldId: $ref: '#/components/schemas/FieldId' reason: $ref: >- #/components/schemas/PreAggregateMissReason.FILTER_DIMENSION_NOT_IN_PRE_AGGREGATE required: - fieldId - reason type: object - properties: fieldId: $ref: '#/components/schemas/FieldId' reason: $ref: >- #/components/schemas/PreAggregateMissReason.PRE_AGGREGATE_FILTER_NOT_SATISFIED required: - fieldId - reason type: object - properties: preAggregateTimeDimension: type: string preAggregateGranularity: $ref: '#/components/schemas/TimeFrames' queryGranularity: $ref: '#/components/schemas/TimeFrames' fieldId: $ref: '#/components/schemas/FieldId' reason: $ref: '#/components/schemas/PreAggregateMissReason.GRANULARITY_TOO_FINE' required: - preAggregateTimeDimension - preAggregateGranularity - queryGranularity - fieldId - reason type: object - properties: reason: $ref: >- #/components/schemas/PreAggregateMissReason.CUSTOM_DIMENSION_PRESENT required: - reason type: object - properties: fieldId: $ref: '#/components/schemas/FieldId' reason: $ref: >- #/components/schemas/PreAggregateMissReason.CUSTOM_METRIC_PRESENT required: - fieldId - reason type: object - properties: fieldId: $ref: '#/components/schemas/FieldId' reason: $ref: >- #/components/schemas/PreAggregateMissReason.TABLE_CALCULATION_PRESENT required: - fieldId - reason type: object - properties: preAggregateName: type: string reason: $ref: '#/components/schemas/PreAggregateMissReason.USER_BYPASS' required: - preAggregateName - reason type: object - properties: reason: $ref: >- #/components/schemas/PreAggregateMissReason.EXPLORE_RESOLUTION_ERROR required: - reason type: object - properties: reason: $ref: >- #/components/schemas/PreAggregateMissReason.NO_ACTIVE_MATERIALIZATION required: - reason type: object PreAggregateMissReason.NO_PRE_AGGREGATES_DEFINED: enum: - no_pre_aggregates_defined type: string FieldId: type: string PreAggregateMissReason.DIMENSION_NOT_IN_PRE_AGGREGATE: enum: - dimension_not_in_pre_aggregate type: string PreAggregateMissReason.METRIC_NOT_IN_PRE_AGGREGATE: enum: - metric_not_in_pre_aggregate type: string PreAggregateMissReason.NON_ADDITIVE_METRIC: enum: - non_additive_metric type: string PreAggregateMissReason.NON_ADDITIVE_METRIC_REQUIRES_EXACT_MATCH: enum: - non_additive_metric_requires_exact_match type: string PreAggregateMissReason.CUSTOM_SQL_METRIC: enum: - custom_sql_metric type: string PreAggregateMissReason.FILTER_DIMENSION_NOT_IN_PRE_AGGREGATE: enum: - filter_dimension_not_in_pre_aggregate type: string PreAggregateMissReason.PRE_AGGREGATE_FILTER_NOT_SATISFIED: enum: - pre_aggregate_filter_not_satisfied type: string TimeFrames: enum: - RAW - YEAR - QUARTER - MONTH - WEEK - DAY - HOUR - MINUTE - SECOND - MILLISECOND - DAY_OF_WEEK_INDEX - DAY_OF_MONTH_NUM - DAY_OF_YEAR_NUM - WEEK_NUM - MONTH_NUM - QUARTER_NUM - YEAR_NUM - DAY_OF_WEEK_NAME - MONTH_NAME - QUARTER_NAME - HOUR_OF_DAY_NUM - MINUTE_OF_HOUR_NUM type: string PreAggregateMissReason.GRANULARITY_TOO_FINE: enum: - granularity_too_fine type: string PreAggregateMissReason.CUSTOM_DIMENSION_PRESENT: enum: - custom_dimension_present type: string PreAggregateMissReason.CUSTOM_METRIC_PRESENT: enum: - custom_metric_present type: string PreAggregateMissReason.TABLE_CALCULATION_PRESENT: enum: - table_calculation_present type: string PreAggregateMissReason.USER_BYPASS: enum: - user_bypass type: string PreAggregateMissReason.EXPLORE_RESOLUTION_ERROR: enum: - explore_resolution_error type: string PreAggregateMissReason.NO_ACTIVE_MATERIALIZATION: enum: - no_active_materialization type: string ````