> ## Documentation Index
> Fetch the complete documentation index at: https://deepline.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Redshift: Actions/run Semantic Query

> Query Redshift by metrics, dimensions and filters from your saved semantic layer, without writing SQL. Includes SDK V2 examples, schemas, and cost.

Query Redshift by metrics, dimensions and filters from your saved semantic layer, without writing SQL.

> [!NOTE]
>
> Tool ID: `redshift_run_semantic_query`

## Run this action

Use the TypeScript SDK for one call. Use `ctx.tools.execute(...)` inside a Play for durable calls, scheduled calls, or CSV processing.

```ts theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
import { Deepline } from 'deepline';

const deepline = await Deepline.connect();
const result = await deepline.tools.execute(
  'redshift_run_semantic_query',
  {
    "credentials": {
      "host": "api.example.com",
      "database": "example"
    },
    "name": "Example",
    "output_df_name": "Example"
  },
);

console.log(result.toolResponse.raw);
```

### CLI

```bash theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
deepline tools execute redshift_run_semantic_query --input '{
  "credentials": {
    "host": "api.example.com",
    "database": "example"
  },
  "name": "Example",
  "output_df_name": "Example"
}' --json
```

## Example response

The SDK returns this shape at `result.toolResponse.raw`. The example values illustrate the response.

```json theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
{
  "data": {
    "rows": [
      {}
    ],
    "rowCount": 123,
    "limited": true,
    "columns": [
      "example"
    ],
    "queryId": "query_123",
    "sql": "SELECT * FROM companies LIMIT 10"
  }
}
```

Use `deepline describe redshift_run_semantic_query --json` for the latest machine-readable contract.

## Input reference

Render a stored Redshift semantic layer query and execute it.

| Name | Type | Required | Default | Details |
| - | - | - | - | - |
| `payload.credentials` | `object` | No | — | — |
| `payload.name` | `string` | No | — | — |
| `payload.output_df_name` | `string` | No | — | — |
| `payload.renderer_version` | `"v2"` | No | — | — |
| `payload.type` | `"metrics" \| "funnel" \| null` | No | — | — |
| `payload.params` | `object \| null` | No | — | — |
| `payload.table_name` | `string` | No | — | Legacy semantic table name. |
| `payload.metrics` | `array` | No | — | — |
| `payload.dimensions` | `array` | No | — | — |
| `payload.custom_dimensions` | `array` | No | — | — |
| `payload.facts` | `array` | No | — | — |
| `payload.filters` | `array` | No | — | — |
| `payload.custom_filter_expressions` | `array` | No | — | — |
| `payload.rowLimit` | `integer` | No | `5000` | Maximum number of rows to return. Default 5000. |
| `payload.timeoutMs` | `integer` | No | `120000` | Redshift statement timeout in milliseconds. Default 120000. |

<details>
  <summary>Show raw input schema</summary>

  ### Input JSON Schema

  ```json theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
  {
    "type": "object",
    "description": "Render a stored Redshift semantic layer query and execute it.",
    "properties": {
      "credentials": {
        "type": "object",
        "properties": {
          "auth_type": {
            "type": "string",
            "enum": [
              "password",
              "iam"
            ]
          },
          "host": {
            "type": "string",
            "description": "Public or already-routed Redshift endpoint hostname."
          },
          "port": {
            "type": "integer",
            "default": 5439
          },
          "database": {
            "type": "string",
            "description": "Default database."
          },
          "schema": {
            "type": "string",
            "description": "Default schema. Defaults to public."
          },
          "user": {
            "type": "string",
            "description": "Database user. Required for password and provisioned-cluster IAM auth."
          },
          "password": {
            "type": "string",
            "description": "Password auth secret."
          },
          "region": {
            "type": "string",
            "description": "AWS region for IAM database credential exchange."
          },
          "access_key_id": {
            "type": "string",
            "description": "AWS access key ID for IAM auth."
          },
          "secret_access_key": {
            "type": "string",
            "description": "AWS secret access key for IAM auth."
          },
          "session_token": {
            "type": "string",
            "description": "Optional AWS session token."
          },
          "cluster_identifier": {
            "type": "string",
            "description": "Provisioned cluster identifier. Mutually exclusive with workgroup_name."
          },
          "workgroup_name": {
            "type": "string",
            "description": "Serverless workgroup name. Mutually exclusive with cluster_identifier."
          }
        },
        "required": [
          "host",
          "database"
        ],
        "additionalProperties": false
      },
      "name": {
        "type": [
          "string",
          "null"
        ]
      },
      "output_df_name": {
        "type": [
          "string",
          "null"
        ]
      },
      "renderer_version": {
        "type": "string",
        "const": "v2"
      },
      "type": {
        "anyOf": [
          {
            "type": "string",
            "const": "metrics"
          },
          {
            "type": "string",
            "const": "funnel"
          },
          {
            "type": "null"
          }
        ]
      },
      "params": {
        "anyOf": [
          {
            "type": "object",
            "properties": {
              "table_name": {
                "type": "string",
                "description": "Semantic table name."
              },
              "metrics": {
                "type": [
                  "array",
                  "null"
                ],
                "items": {
                  "type": "string"
                }
              },
              "dimensions": {
                "type": [
                  "array",
                  "null"
                ],
                "items": {
                  "type": "string"
                }
              },
              "custom_dimensions": {
                "type": [
                  "array",
                  "null"
                ],
                "items": {
                  "type": "string"
                }
              },
              "facts": {
                "type": [
                  "array",
                  "null"
                ],
                "items": {
                  "type": "string"
                }
              },
              "filters": {
                "type": [
                  "array",
                  "null"
                ],
                "items": {
                  "type": "string"
                }
              },
              "custom_filter_expressions": {
                "type": [
                  "array",
                  "null"
                ],
                "items": {
                  "type": "string"
                }
              },
              "output_format": {
                "type": "string",
                "enum": [
                  "csv",
                  "parquet"
                ]
              }
            },
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "table_name": {
                "type": "string",
                "description": "Semantic table name."
              },
              "steps": {
                "type": "array",
                "items": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "source_table": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "ts_expr": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "time_dimension": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "filter_expr": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "events_sql": {
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      },
                      "additionalProperties": false
                    }
                  ]
                }
              },
              "cohort_by": {
                "type": [
                  "array",
                  "null"
                ],
                "items": {
                  "type": "string"
                }
              },
              "enforce_order": {
                "type": "boolean"
              },
              "time_window_days": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "filters": {
                "type": [
                  "array",
                  "null"
                ],
                "items": {
                  "type": "string"
                }
              },
              "custom_filter_expressions": {
                "type": [
                  "array",
                  "null"
                ],
                "items": {
                  "type": "string"
                }
              },
              "output_format": {
                "type": "string",
                "enum": [
                  "csv",
                  "parquet"
                ]
              }
            },
            "additionalProperties": false
          },
          {
            "type": "null"
          }
        ]
      },
      "table_name": {
        "type": "string",
        "description": "Legacy semantic table name."
      },
      "metrics": {
        "type": [
          "array",
          "null"
        ],
        "items": {
          "type": "string"
        }
      },
      "dimensions": {
        "type": [
          "array",
          "null"
        ],
        "items": {
          "type": "string"
        }
      },
      "custom_dimensions": {
        "type": [
          "array",
          "null"
        ],
        "items": {
          "type": "string"
        }
      },
      "facts": {
        "type": [
          "array",
          "null"
        ],
        "items": {
          "type": "string"
        }
      },
      "filters": {
        "type": [
          "array",
          "null"
        ],
        "items": {
          "type": "string"
        }
      },
      "custom_filter_expressions": {
        "type": [
          "array",
          "null"
        ],
        "items": {
          "type": "string"
        }
      },
      "rowLimit": {
        "type": "integer",
        "description": "Maximum number of rows to return. Default 5000.",
        "default": 5000
      },
      "timeoutMs": {
        "type": "integer",
        "description": "Redshift statement timeout in milliseconds. Default 120000.",
        "default": 120000
      }
    },
    "additionalProperties": false
  }
  ```
</details>

## Output reference

Redshift semantic query result.

| Name | Type | Required | Default | Details |
| - | - | - | - | - |
| `result.data` | `object` | Yes | — | Semantic query response payload. |
| `result.data.rows` | `array` | Yes | — | — |
| `result.data.rowCount` | `integer` | Yes | — | — |
| `result.data.limited` | `boolean` | Yes | — | — |
| `result.data.columns` | `array` | Yes | — | — |
| `result.data.queryId` | `string \| null` | Yes | — | — |
| `result.data.sql` | `string` | Yes | — | — |
| `result.data.dataset` | `object` | No | — | — |
| `result.data.dataset.kind` | `"redshift_query"` | Yes | — | — |
| `result.data.dataset.total_rows` | `integer` | Yes | — | — |
| `result.data.dataset.returned_limit` | `integer` | Yes | — | — |
| `result.data.dataset.offset` | `integer` | Yes | — | — |
| `result.data.dataset.page_size` | `integer` | Yes | — | — |
| `result.meta` | `object` | No | — | — |
| `result.meta.database` | `string` | Yes | — | — |
| `result.meta.schema` | `string` | Yes | — | — |
| `result.meta.host` | `string` | Yes | — | — |
| `result.meta.rowLimit` | `integer` | Yes | — | — |
| `result.meta.timeoutMs` | `integer` | Yes | — | — |
| `result.meta.rendererVersion` | `"v2"` | Yes | — | — |
| `result.meta.semanticLayerHash` | `string` | Yes | — | — |
| `result.meta.dataset` | `object` | No | — | — |
| `result.meta.dataset.limit` | `integer` | Yes | — | — |
| `result.meta.dataset.offset` | `integer` | Yes | — | — |
| `result.meta.dataset.pageSize` | `integer` | Yes | — | — |

<details>
  <summary>Show raw output schema</summary>

  ### Output JSON Schema

  ```json theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
  {
    "type": "object",
    "description": "Redshift semantic query result.",
    "properties": {
      "data": {
        "type": "object",
        "description": "Semantic query response payload.",
        "properties": {
          "rows": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": {}
            }
          },
          "rowCount": {
            "type": "integer"
          },
          "limited": {
            "type": "boolean"
          },
          "columns": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "queryId": {
            "type": [
              "string",
              "null"
            ]
          },
          "sql": {
            "type": "string"
          },
          "dataset": {
            "type": "object",
            "properties": {
              "kind": {
                "type": "string",
                "const": "redshift_query"
              },
              "total_rows": {
                "type": "integer"
              },
              "returned_limit": {
                "type": "integer"
              },
              "offset": {
                "type": "integer"
              },
              "page_size": {
                "type": "integer"
              }
            },
            "required": [
              "kind",
              "total_rows",
              "returned_limit",
              "offset",
              "page_size"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "rows",
          "rowCount",
          "limited",
          "columns",
          "queryId",
          "sql"
        ],
        "additionalProperties": false
      },
      "meta": {
        "type": "object",
        "properties": {
          "database": {
            "type": "string"
          },
          "schema": {
            "type": "string"
          },
          "host": {
            "type": "string"
          },
          "rowLimit": {
            "type": "integer"
          },
          "timeoutMs": {
            "type": "integer"
          },
          "rendererVersion": {
            "type": "string",
            "const": "v2"
          },
          "semanticLayerHash": {
            "type": "string"
          },
          "dataset": {
            "type": "object",
            "properties": {
              "limit": {
                "type": "integer"
              },
              "offset": {
                "type": "integer"
              },
              "pageSize": {
                "type": "integer"
              }
            },
            "required": [
              "limit",
              "offset",
              "pageSize"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "database",
          "schema",
          "host",
          "rowLimit",
          "timeoutMs",
          "rendererVersion",
          "semanticLayerHash"
        ],
        "additionalProperties": false
      }
    },
    "required": [
      "data"
    ],
    "additionalProperties": false
  }
  ```
</details>

## Deepline cost

* Pricing model: `fixed` (per call).
* Estimated Deepline credits: `0` per pricing unit.
* Provider-native pricing may still exist outside Deepline credit billing.

## Related documentation

* [Redshift provider guide](https://deepline.com/docs/providers/redshift/guide.md)
* [SDK V2 quickstart](https://deepline.com/docs/sdk-v2/quickstart.md)
* [SDK reference](https://deepline.com/docs/sdk-v2/sdk-reference.md)
* [Run tools across a CSV](https://deepline.com/docs/sdk-v2/batch-csv.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.