SQL-запросы к Amazon Redshift

Текст

---
name: redshift-api
description: Выполняй SQL-запросы в Amazon Redshift — отправляй команды, проверяй статус, листай результаты и просматривай базы данных, схемы и таблицы. Используй этот скилл всякий раз, когда пользователь хочет сделать запрос к Redshift (кластер с выделенными ресурсами или Serverless), спрашивает «какие таблицы есть в этой схеме», хочет проверить статус запроса либо упоминает `redshift-data`, идентификатор кластера Redshift или имя рабочей группы (workgroup), либо адрес `redshift-data.{region}.amazonaws.com`. Всегда начинай с этого скилла, когда работаешь с этим сервисом: его готовые скрипты и рецепты — самый быстрый путь.
---

В Amazon Redshift Data API каждый вызов — это POST на https://redshift-data.<region>.amazonaws.com/ с Content-Type: application/x-amz-json-1.1 и X-Amz-Target: RedshiftData.<Action> — путей в стиле REST здесь нет. API полностью асинхронный: отправляешь команду, получаешь Id, опрашиваешь DescribeStatement, пока команда не завершится, затем листаешь результаты через GetStatementResult — scripts/rs_query.sh (операция 1) проходит весь этот цикл за тебя. Те же вызовы работают и с кластерами с выделенными ресурсами, и с Serverless; отличается только поле с целью подключения.

Настройка запросов

Аутентификацию обеспечивает среда выполнения — запросы к этому API подписываются учётными данными, настроенными для рабочего пространства, так что настраивать ничего не нужно. Не пытайся получить ключи AWS или подписывать запросы самостоятельно. Постоянная ошибка AccessDeniedException означает, что для этого рабочего пространства учётные данные не настроены — сообщи об этом, а не разбирайся с авторизацией.

Две настройки реальны и обязательны:

1. Регион — он входит в имя хоста эндпоинта:

export AWS_DEFAULT_REGION="us-east-1"        # the region your cluster / workgroup is in

2. Цель подключения — к какому кластеру или рабочей группе и к какой базе данных подключается Data API. Выбери один вариант и положи соответствующие поля JSON в RS_TARGET; рецепты ниже подмешивают его в тело каждого запроса:

• Serverless — передай WorkgroupName. Настроенная учётная запись сопоставляется с пользователем базы данных. Самый простой вариант.
• Выделенный кластер, временные учётные данные — передай ClusterIdentifier и DbUser. Data API сам получает учётные данные базы данных.
• Выделенный кластер или Serverless, Secrets Manager — передай SecretArn, указывающий на секрет с логином в базу данных.

Задай подходящий вариант один раз:

export RS_DATABASE="dev"
# Serverless:
export RS_TARGET='{"WorkgroupName": "my-workgroup"}'
# — or provisioned + temp creds:
# export RS_TARGET='{"ClusterIdentifier": "my-cluster", "DbUser": "my_user"}'
# — or either + Secrets Manager:
# export RS_TARGET='{"ClusterIdentifier": "my-cluster", "SecretArn": "arn:aws:secretsmanager:us-east-1:123456789012:secret:rs-creds-AbCdEf"}'

Используемая ниже вспомогательная функция. Одна функция оборачивает эндпоинт, заголовки и имя действия. Заголовок Authorization — заглушка: среда выполнения заменяет её настоящей подписью.

rsapi() {
  local action="$1"
  curl -sS "https://redshift-data.${AWS_DEFAULT_REGION}.amazonaws.com/" \
    -H "Content-Type: application/x-amz-json-1.1" \
    -H "X-Amz-Target: RedshiftData.${action}" \
    -H "Authorization: placeholder" \
    -d "${2:?rsapi needs a JSON body as the second argument}"
}

Проверка подключения — выведи список баз данных. Ответ 200 с массивом Databases подтверждает, что рабочее пространство подключено, а цель подключения указана верно. Если произойдёт ошибка, в ней будет названо, на каком уровне сбой.

rsapi ListDatabases "$(jq -n --argjson t "$RS_TARGET" --arg db "$RS_DATABASE" \
  '$t + {Database: $db}')" | jq .

Основные операции

Любое действие, которое подключается к базе данных, принимает одно и то же тело с подмешанной целью — $t + {Database: $db, ...}. Ошибки приходят в виде {"__type": "<Exception>", "message": "..."} вместо ожидаемой структуры; если в ответе на любой вызов нет верхнеуровневого поля (Id, Status, Records и т. д.), значит, получена оболочка с ошибкой — выведи её и остановись.

1. Выполнить запрос (scripts/rs_query.sh)

Выполняй SQL через входящий в комплект скрипт (путь указан относительно папки этого скилла): он отправляет команду через ExecuteStatement, опрашивает DescribeStatement до конечного состояния, листает GetStatementResult по NextToken и расшифровывает типизированные объекты ячеек с одним ключом.

scripts/rs_query.sh \
  'SELECT event_name, COUNT(*) AS n FROM public.events
   WHERE event_date >= :start GROUP BY 1 ORDER BY 2 DESC LIMIT 20' \
  --param start=2024-01-01 --name top-events

• SQL — это один аргумент (или стандартный ввод). Параметры подключения берутся из AWS_DEFAULT_REGION / RS_TARGET / RS_DATABASE, см. выше; --database переопределяет базу данных.
• --param NAME=VALUE (можно повторять) подставляет значения в заполнители :NAME — значения всегда строки; приведением типов занимается база данных. --name задаёт StatementName, чтобы запрос был виден в ListStatements.
• --max-rows N ограничивает число получаемых строк (по умолчанию 10000, 0 = все); --json выдаёт по одному JSON-объекту на строку вместо TSV с заголовком. Id команды, статус, длительность и число строк выводятся в stderr.
• Коды завершения: 0 — успех, 1 — отправка не удалась или SQL завершился как FAILED/ABORTED (собственное сообщение API выводится в stderr), 2 — скрипт перестал ждать через --max-wait секунд (по умолчанию 600) — id команды выводится в stderr; продолжи по нему операцией 2.

Если скрипт выдаёт ошибку, прочитай его: это обычные curl + jq, — и разбирайся по references/api.md. Для BatchExecuteStatement и результатов подкоманд, повторного использования сессии (SessionKeepAliveSeconds / SessionId), ResultFormat: CSV, отмены или просмотра каталога используй действия ниже.

2. Продолжить команду по id (DescribeStatement → GetStatementResult)

Если скрипт завершился с кодом 2 (тайм-аут) или у тебя есть id команды из другого источника, опроси и получи результат напрямую:

rsapi DescribeStatement "$(jq -n --arg id "$ID" '{Id: $id}')" \
  | jq '{Status, Duration, ResultRows, HasResultSet, Error}'
rsapi GetStatementResult "$(jq -n --arg id "$ID" '{Id: $id}')" \
  | jq -r '.Records[]? | [.[] | if .isNull then null else to_entries[0].value end] | @tsv'

• Status ∈ SUBMITTED, PICKED, STARTED, FINISHED, FAILED, ABORTED. Строки есть только у FINISHED с HasResultSet: true; FAILED несёт SQL-ошибку в .Error. Duration указывается в наносекундах.
• Ячейки результата — типизированные объекты с одним ключом (см. подвох в разделе «Обработка ошибок»); названия и типы столбцов находятся в .ColumnMetadata на первой странице. Следующие страницы листаются по NextToken — параметра размера страницы нет; DescribeStatement.ResultRows сразу показывает общее число строк.

3. Отменить выполняющуюся команду (CancelStatement)

rsapi CancelStatement "$(jq -n --arg id "$ID" '{Id: $id}')" | jq .
# {"Status": true} on success — best-effort, check DescribeStatement to confirm.

4. Выполнить несколько команд одним вызовом (BatchExecuteStatement)

Все команды выполняются в одной транзакции — либо фиксируются все, либо откатываются все.

rsapi BatchExecuteStatement "$(jq -n --argjson t "$RS_TARGET" --arg db "$RS_DATABASE" '$t + {
    Database: $db,
    Sqls: ["CREATE TEMP TABLE tmp AS SELECT 1 AS x", "SELECT * FROM tmp"]
  }')" | jq '{Id}'

DescribeStatement для родительского Id возвращает массив SubStatements[]. У каждой подкоманды свой Id (родительский ID с суффиксом :1, :2 и т. д.), Status и HasResultSet — результаты каждой подкоманды получай отдельным вызовом GetStatementResult.

5. Список недавних команд (ListStatements)

rsapi ListStatements '{"MaxResults": 20, "Status": "ALL"}' \
  | jq '.Statements[] | {Id, StatementName, Status, QueryString: (.QueryString[0:80]), CreatedAt}'

Фильтр Status: SUBMITTED, PICKED, STARTED, FINISHED, FAILED, ABORTED, ALL — если его опустить, в списке будут только завершённые команды. MaxResults — от 0 до 100. RoleLevel по умолчанию равен true (включает команды всех, кто использует ту же роль IAM); поставь false, чтобы видеть только команды этой сессии.

6. Просмотр каталога (ListDatabases / ListSchemas / ListTables / DescribeTable)

Все четыре принимают тело с подмешанной целью. Шаблоны используют подстановочные знаки SQL LIKE (%, _).

• **ListDatabases** — Databases[] (строки)
• **ListSchemas** — SchemaPattern (необязательный) — Schemas[] (строки)
• **ListTables** — SchemaPattern, TablePattern — Tables[] {schema, name, type} — type ∈ TABLE/VIEW/SYSTEM TABLE/GLOBAL TEMPORARY/LOCAL TEMPORARY/ALIAS/SYNONYM
• **DescribeTable** — Schema, Table — ColumnList[] {name, typeName, nullable, length, precision}

rsapi ListTables "$(jq -n --argjson t "$RS_TARGET" --arg db "$RS_DATABASE" \
  '$t + {Database: $db, SchemaPattern: "public", TablePattern: "ev%"}')" | jq '.Tables'

Имена полей JSON пишутся в PascalCase (WorkgroupName, а не workgroup-name). Все четыре действия постраничные (NextToken). Структуру тела каждого действия см. в references/api.md.

Постраничная выдача

GetStatementResult, ListStatements, ListDatabases, ListSchemas, ListTables и DescribeTable работают по одной схеме: если данных больше, в ответе есть NextToken; передай его обратно как NextToken в теле следующего запроса. Останавливайся, когда его нет.

Лимиты запросов

• Активные команды — до 500 активных (SUBMITTED/STARTED) на кластер или рабочую группу. Лишние отправки завершаются ошибкой ActiveStatementsExceededException.
• Размер результата — 500 МБ на команду (после gzip) и 64 КБ на строку. Более крупные результаты вызывают ошибку; добавь LIMIT или используй UNLOAD ... TO 's3://...'.
• Хранение результата — 24 часа; после этого GetStatementResult возвращает ResourceNotFoundException.
• Длительность команды — не более 24 часов. Строка запроса — не более 100 КБ.
• Частота вызовов API — фиксированные, не настраиваемые квоты TPS на аккаунт и регион: DescribeStatement 100, ExecuteStatement 30, GetStatementResult 20, BatchExecuteStatement 20, и только 3 TPS для CancelStatement, ListStatements, ListDatabases, ListSchemas, ListTables, DescribeTable. При превышении любой из них возвращается ThrottlingException (HTTP 400) — делай паузу и не опрашивай в тесном цикле.

Обработка ошибок

Ошибки приходят в виде {"__type": "<Exception>", "message": "..."} (HTTP 400/403/500). Различать их помогает поле __type.

• **ValidationException (400)** — неверные параметры. Частые причины: переданы и ClusterIdentifier, и WorkgroupName либо ни один из них; нет Database; неверный регистр названия поля.
• **ActiveStatementsExceededException (400)** — слишком много команд в работе. ListStatements с {"Status":"STARTED"} покажет, что выполняется.
• **ActiveSessionsExceededException (400)** — открыто более 500 сессий. Перестань передавать SessionKeepAliveSeconds или дождись, пока простаивающие сессии истекут.
• **ExecuteStatementException (500)** — отправка сорвалась до того, как команду увидела база данных: неверное имя кластера или рабочей группы, кластер недоступен, неверный DbUser. Проверь RS_TARGET.
• **ResourceNotFoundException (400)** — ID команды неизвестен или ей больше 24 часов.
• **BatchExecuteStatementException (500)** — одна из команд пакета не выполнилась; вся транзакция откатена. Посмотри SubStatements[].Error.
• **DatabaseConnectionException / QueryTimeoutException** — вызов каталога не смог подключиться к базе данных или превысил время ожидания. Проверь, что цель работает; повтори.
• **AccessDeniedException (403)** — учётным данным нужно право redshift-data:* на ARN кластера или рабочей группы, а также, в зависимости от режима подключения, redshift:GetClusterCredentials / redshift-serverless:GetCredentials / secretsmanager:GetSecretValue. Сообщи, какого права не хватает.
• **InternalServerException (500)** — ExecuteStatement не идемпотентен, если не передать ClientToken — перед повтором записи проверь ListStatements.
• **Status: FAILED в DescribeStatement** — SQL завершился ошибкой после отправки. Сообщение SQL смотри в .Error.

Два подвоха:

• **Ответ 200 на ExecuteStatement ≠ запрос выполнился успешно.** SQL-ошибки проявляются позже, как Status: FAILED в DescribeStatement. Всегда опрашивай статус, прежде чем получать результаты.
• Значения ячеек — типизированные объекты с одним ключом, а не голые значения. longValue — это число JSON, isNull: true — отдельная форма. Простое чтение .value ничего не вернёт, а цепочка jq // по типизированным ключам ломается на false/0. Используй to_entries[0].value.

Подробнее

В references/api.md — полный каталог: структура запроса и ответа каждого действия в PascalCase для «сырого» HTTP, формат привязки SqlParameter, поля ColumnMetadata, SubStatementData для пакетов, повторное использование сессии (SessionKeepAliveSeconds / SessionId) и таблица квот. Читай его, когда нужно действие, которого нет выше, или точная структура тела для «сырого» HTTP.

Перевод: iiuniversitet. Оригинал: https://github.com/anthropics/claude-tag-plugins/tree/main/redshift/skills/redshift-api, лицензия Apache-2.0. Изменения: перевод на русский язык.