---
title: "Create a SQL preview."
method: POST
path: "/sql/preview"
tags: ["Preview Operations"]
---

# Create a SQL preview.

`POST /sql/preview`

## Request

- Base URL: `https://replace-with-account.api.data.decodable.co/v1alpha2`
- URL: `https://replace-with-account.api.data.decodable.co/v1alpha2/sql/preview`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/decodable/apis/decodable-data-plane/docs/sql/preview/post.ts> (a function with typed inputs; its response is checked against the schema)

Requires a bearer token for starting a data plane preview issued by the control plane API.

## Request body

- SqlPreviewCreateRequest: A preview creation request.
  - `preview_id` string, required: The id for the preview to use
  - `rewritten_sql` string, required: The sql for the preview to run.
  - `stream_metadata` object[], required
  - `output_metadata` OutputMetadata, required: A descriptor of a preview output.
    - `output_stream_type` string: The stream type of the preview output
    - `name` string: The name for the preview output
    - `schema` SchemaV2: A stream or connection schema in the V2 format.
      - `fields` union[]: Schema fields
        - union
          - PhysicalField: A field which is physically present in the data.
            - `kind` 'physical' | 'computed' | 'metadata': The type of the field.
            - `name` string: The name of the field.
            - `type` string: The field's type.
          - ComputedField: A field which is computed at runtime.
            - `kind` 'physical' | 'computed' | 'metadata': The type of the field.
            - `name` string: The name of the field.
            - `expression` unknown
          - MetadataField: A field which exposes metadata from the connector.
            - `kind` 'physical' | 'computed' | 'metadata': The type of the field.
            - `name` string: The name of the field.
            - `type` string: The field's type.
            - `key` string: The key used to retrieve the metadata from the connector.
      - `watermarks` object[]
        - `name` string: The name of the field used in the watermark.
        - `expression` string: The expression defining the watermark.
      - `constraints` object
        - `primary_key` string[]: The names of the fields used in the schema's primary key
    - `ddl_properties` unknown

## Response `201`

A preview creation response.

- Preview: A preview response.
  - `id` string, required: An opaque ID, created by Decodable, that uniquely identifies a resource.
  - `output_stream_type` 'APPEND' | 'CHANGE'
  - `results` object[]: Result rows from preview.
  - `next_token` string: A token used to fetch the next available results.

## Other responses

- `400`: An invalid request was received.
- `403`: Access denied: request is not permitted.
- `default`: An error has occurred.

---

[API](https://skmtc.dev/decodable/apis/decodable-data-plane.md) - [All operations](https://skmtc.dev/decodable/apis/decodable-data-plane/llms.txt) - [OpenAPI document](https://skmtc.dev/decodable/apis/decodable-data-plane/revisions/4303384f9994?raw)