SQL-запросы к Snowflake

Текст

---
name: snowflake-api
description: Выполняй SQL-запросы в Snowflake — отправляй команды, опрашивай асинхронные дескрипторы, получай части результата (partitions), отменяй запросы и просматривай хранилища (warehouses), базы данных, схемы и таблицы. Используй этот скилл всякий раз, когда пользователь хочет сделать запрос к Snowflake, спрашивает «какие таблицы есть в этой схеме», хочет проверить состояние хранилища либо упоминает `snowflakecomputing.com`, `/api/v2/statements` или идентификатор аккаунта Snowflake (вроде `xy12345.us-east-1`). Всегда начинай с этого скилла, когда работаешь с этим сервисом: его готовые скрипты и рецепты — самый быстрый путь.
---

SQL API v2 Snowflake (/api/v2/statements) — это тонкий слой REST для выполнения SQL и получения результатов. Отправь POST со строкой SQL и получи дескриптор команды (statement handle) и либо сам результат (для быстрых запросов), либо ответ 202 Accepted, после которого нужно опрашивать. Большие результаты делятся на части (partitions), которые получают по одной. Отдельного эндпоинта «список таблиц» нет — просмотр каталога делается обычным SQL (SHOW TABLES, INFORMATION_SCHEMA).

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

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

Идентификатор аккаунта должен быть настоящим — это имя хоста. Это часть адреса Snowflake перед .snowflakecomputing.com — например, xy12345.us-east-1 или идентификатор вида «организация-аккаунт» myorg-myaccount.

export SNOWFLAKE_ACCOUNT="xy12345.us-east-1"           # your account identifier — must be real
export SNOWFLAKE_BASE="https://${SNOWFLAKE_ACCOUNT}.snowflakecomputing.com"
export SNOWFLAKE_TOKEN="placeholder"                   # injected by the runtime; any value works
export SNOWFLAKE_TOKEN_TYPE="${SNOWFLAKE_TOKEN_TYPE:-OAUTH}"   # leave as provided by the runtime

Вспомогательная функция и проверка подключения

Каждый запрос несёт одни и те же заголовки. Определи вспомогательную функцию один раз:

snowapi() {
  curl -sS --compressed "$@" \
    -H "Authorization: Bearer ${SNOWFLAKE_TOKEN}" \
    -H "X-Snowflake-Authorization-Token-Type: ${SNOWFLAKE_TOKEN_TYPE}" \
    -H "Content-Type: application/json" -H "Accept: application/json" \
    -H "User-Agent: curl-sql-api/1.0"
}

(User-Agent обязателен — Snowflake отклоняет запросы без него. --compressed важен для частей результата, которые приходят с Content-Encoding: gzip.)

Проверка подключения — убедись, что идентификатор аккаунта верный и рабочее пространство подключено:

snowapi -X POST "${SNOWFLAKE_BASE}/api/v2/statements" \
  -d '{"statement":"SELECT CURRENT_USER(), CURRENT_ROLE(), CURRENT_WAREHOUSE()","timeout":10}' | jq .
# Returns the configured user/role/warehouse on success.

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

1. Выполнить команду (scripts/snow_query.sh)

Выполняй SQL через входящий в комплект скрипт (путь указан относительно папки этого скилла): он отправляет команду, опрашивает дескриптор до завершения, проходит все части результата (сжатие gzip обрабатывается) и выдаёт расшифрованные строки. Используй его для любого запроса из одной команды, а также для SHOW и DESCRIBE.

scripts/snow_query.sh --warehouse MY_WH --bind TEXT:1996-01-01 \
  'SELECT o_orderdate, COUNT(*) n FROM snowflake_sample_data.tpch_sf1.orders
   WHERE o_orderdate >= ? GROUP BY 1 ORDER BY 1 LIMIT 20'

• SQL — это один аргумент в кавычках или стандартный ввод. Параметры подключения берутся из SNOWFLAKE_ACCOUNT / SNOWFLAKE_TOKEN / SNOWFLAKE_TOKEN_TYPE, см. выше (SNOWFLAKE_BASE_URL переопределяет хост).
• --warehouse / --database / --schema / --role задают контекст сессии (если опустить, каждый берётся из значения по умолчанию у пользователя Snowflake); --tag задаёт QUERY_TAG для аудита.
• --bind TYPE:VALUE (можно повторять) по порядку подставляет значения в позиционные заполнители ? — предпочитай его вставке значений прямо в строку SQL. Типы — это типы привязки из references/api.md.
• --timeout (по умолчанию 300 с) — ограничение времени выполнения на стороне сервера: команда, превысившая его, будет отменена; --max-wait (по умолчанию 600 с) — сколько скрипт опрашивает, прежде чем сдаться.
• --max-rows N ограничивает число получаемых строк (по умолчанию 10000, 0 = все); --json выдаёт по одному JSON-объекту на строку вместо TSV с заголовком. Дескриптор, число строк и ошибки выводятся в stderr.
• Ячейки выдаются в «сырой» строковой кодировке API (поэтому даты — это дни с начала эпохи, а метки времени — секунды с начала эпохи; см. подвох в разделе «Обработка ошибок»).
• Коды завершения: 0 — успех, 1 — запрос или SQL завершились ошибкой (code/sqlState/message Snowflake в stderr), 2 — скрипт сдался после --max-wait, пока команда ещё выполнялась — дескриптор выводится в stderr; получи результат или отмени команду через эндпоинты ниже.

Если скрипт выдаёт ошибку, прочитай его: это обычные curl + jq, — и разбирайся по references/api.md. Для запросов из нескольких команд, идемпотентных повторов через requestId, привязки массивов, отмены или получения результатов по уже имеющемуся дескриптору используй эндпоинты ниже напрямую.

2. Получить результаты по существующему дескриптору

GET /api/v2/statements/{handle} — путь восстановления после тайм-аута скрипта (код завершения 2) или для любого дескриптора, полученного в другом месте. 202 = ещё выполняется (повтори опрос после sleep), 200 = готово, часть 0 результатов приходит сразу, 422 = команда завершилась ошибкой.

snowapi "${SNOWFLAKE_BASE}/api/v2/statements/${HANDLE}" -o /tmp/sf.json -w '%{http_code}\n'
jq '{cols: [.resultSetMetaData.rowType[]?.name], parts: .resultSetMetaData.partitionInfo, rows: .data[:5]}' /tmp/sf.json

• Столбцы описаны в resultSetMetaData.rowType[]; строки приходят в data[] как массивы строк (таблица кодировок — в references/api.md, раздел Result metadata & partitions).
• resultSetMetaData.partitionInfo[] перечисляет все части с их rowCount. Остальные получай через ?partition=N для N от 1 до partitionInfo|length - 1. Части стабильны (можно получать параллельно или в любом порядке), после первой они сжаты gzip (--compressed во вспомогательной функции это обрабатывает) и содержат только data — без метаданных.
• Результаты хранятся 24 часа после завершения команды; позже дескриптор возвращает 404.

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

snowapi -X POST "${SNOWFLAKE_BASE}/api/v2/statements/${HANDLE}/cancel" | jq .

Отмена выполняется по мере возможности. Если команда уже завершилась, вызов ничего не делает.

4. Идемпотентная отправка через requestId

Если POST могут повторить (нестабильная сеть, тайм-аут), передай сгенерированный клиентом UUID как requestId. Повтор с тем же requestId и retry=true возвращает дескриптор исходной команды, а не запускает её заново.

RID=$(uuidgen)
snowapi -X POST "${SNOWFLAKE_BASE}/api/v2/statements?requestId=${RID}" -d '{"statement":"INSERT INTO t VALUES (1)","warehouse":"MY_WH"}'
# On timeout, retry:
snowapi -X POST "${SNOWFLAKE_BASE}/api/v2/statements?requestId=${RID}&retry=true" -d '{"statement":"INSERT INTO t VALUES (1)","warehouse":"MY_WH"}'

5. Выполнить несколько команд в одном запросе

Раздели команды знаком ; и задай MULTI_STATEMENT_COUNT равным точному их числу (или 0 для «любого количества»). Возвращается родительский дескриптор и дескрипторы для каждой дочерней команды.

snowapi -X POST "${SNOWFLAKE_BASE}/api/v2/statements" -d '{
  "statement": "CREATE TEMP TABLE tmp AS SELECT 1 AS x; SELECT * FROM tmp;",
  "warehouse": "MY_WH",
  "parameters": {"MULTI_STATEMENT_COUNT": "2"}
}' | jq '{parent: .statementHandle, children: .statementHandles, msg: .message}'

Результаты каждой дочерней команды получай по её собственному дескриптору. BEGIN/COMMIT/ROLLBACK, USE, ALTER SESSION и создание временных таблиц и областей (stage) поддерживаются только *внутри* запроса из нескольких команд — как отдельная команда они завершаются ошибкой 422. Привязки в запросах из нескольких команд не поддерживаются.

6. Просмотр каталога (базы данных, схемы, таблицы, столбцы)

REST-эндпоинтов каталога нет — используй SHOW/DESCRIBE, которые выполняются как обычные команды. Сбой (нет такого объекта, нет прав) приходит как 422 с {code, message, sqlState} и без ключа data — предусмотри эту проверку один раз, а в дальнейших вызовах считай, что .data есть:

snowapi -X POST "${SNOWFLAKE_BASE}/api/v2/statements" -d '{"statement":"SHOW DATABASES","timeout":20}' \
  | jq -r 'if .data then (.data[] | @tsv) else "error \(.code // "?"): \(.message // .)" end'

Подставь в statement любой из вариантов: SHOW SCHEMAS IN DATABASE MY_DB, SHOW TABLES IN SCHEMA MY_DB.PUBLIC, DESCRIBE TABLE MY_DB.PUBLIC.EVENTS, SHOW WAREHOUSES LIKE 'MY_WH' (столбец 2 — состояние: STARTED/SUSPENDED/RESUMING/SUSPENDING).

Чтобы набор столбцов не менялся между версиями, запрашивай INFORMATION_SCHEMA — например, SELECT table_name, row_count, bytes FROM my_db.information_schema.tables WHERE table_schema='PUBLIC' или SELECT column_name, data_type, is_nullable FROM my_db.information_schema.columns WHERE table_schema='PUBLIC' AND table_name='EVENTS' ORDER BY ordinal_position.

Чтобы подписать значения именами столбцов, объедини resultSetMetaData.rowType[].name с каждой строкой data[]: jq '[.resultSetMetaData.rowType[]?.name] as $c | .data[] | [$c,.] | transpose | map({key:.[0],value:.[1]}) | from_entries'.

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

Пагинация здесь — это части (partitions), а не курсоры. resultSetMetaData.partitionInfo — массив записей {"rowCount", "uncompressedSize"}; перебирай индексы, токена следующей страницы нет. Размер каждой части ограничен, чтобы ответы оставались удобными (примерно несколько тысяч строк или ~10 МБ без сжатия).

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

Snowflake не публикует фиксированного ограничения запросов в секунду для SQL API. Реально упираются в такие ограничения:

• Одновременные команды на хранилище (MAX_CONCURRENCY_LEVEL, по умолчанию 8) — лишние запросы встают в очередь внутри Snowflake, а не на уровне HTTP, поэтому 429 ты не получишь; они просто будут находиться в состоянии QUEUED.
• **429 Too Many Requests** случается, если слишком часто опрашивать эндпоинт. Сделай паузу и учитывай Retry-After, если он есть.
• Срок жизни учётных данных — их выдаёт и обновляет среда выполнения. Постоянная ошибка 401 означает, что настроенные учётные данные нужно исправить — сообщи об этом, а не пытайся пройти аутентификацию заново.

Опрашивай с паузой sleep, а не в тесном цикле — и держи timeout в POST достаточно большим, чтобы большинство запросов возвращались сразу, без опроса.

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

Snowflake возвращает HTTP-статус и тело JSON с полями code, sqlState, message и statementHandle. code — специфичная для Snowflake числовая строка (например, "390302").

• **200** — выполнено, результаты сразу в ответе. Читай data[]. Дополнительные страницы смотри в resultSetMetaData.partitionInfo.
• **202** — ещё выполняется (или отправлено асинхронно). Опрашивай GET .../statements/{handle}. В теле есть statementStatusUrl и message.
• **400** — некорректный запрос. Прочитай message. Частые причины: нет Content-Type, неверный JSON, неправильный индекс привязки (привязки — строки с нумерацией с 1: "1", "2", по одной на каждый ?).
• **401** — учётные данные отсутствуют или отклонены. Проверь, что SNOWFLAKE_ACCOUNT указывает на нужный аккаунт и заголовки токена и его типа переданы. Если ошибка не уходит, значит, для этого рабочего пространства учётные данные не настроены — сообщи об этом.
• **404** — дескриптор не найден. Результаты хранятся 24 часа; позже дескриптор исчезает. Либо дескриптор неверный.
• **408** — команда превысила timeout запроса и была отменена. Увеличь timeout (или убери его) и отправь заново.
• **422** — команда завершилась ошибкой (ошибка SQL, отмена). message и sqlState содержат SQL-ошибку. Не повторяй вслепую.
• **429** — сработал лимит запросов. Сделай паузу согласно Retry-After.
• **503 / 504** — временная ошибка. Повтори с нарастающей паузой. Для POST повторяй с тем же requestId + retry=true, чтобы сохранить идемпотентность.

Подвохи, о которых стоит сказать отдельно:

• По умолчанию всё в верхнем регистре. Идентификаторы без кавычек приводятся к верхнему регистру. SHOW TABLES IN schema my_db.public и MY_DB.PUBLIC — одно и то же; "my_db"."public" — нет.
• **Заполнители привязки в SQL — это ?, а привязки — объект с ключами-строками, нумерация с 1**, а не массив: {"1": {...}, "2": {...}}. Значения всегда строки, независимо от type. Список типов и форму привязки массива см. в references/api.md (Bindings).
• **Все значения в data[] — строки, а даты и метки времени не** в формате ISO: date — это число дней с начала эпохи ("18262"), timestamp_* — секунды с начала эпохи с дробной частью из 9 знаков. Разбирай их по resultSetMetaData.rowType[].type; полная таблица кодировок по типам — в references/api.md (Result metadata & partitions).
• Хранилище (warehouse) нужно для всего, что сканирует данные. Для команд, работающих только с метаданными (большинство команд SHOW, DESCRIBE), оно не нужно, а для SELECT нужно. Если хранилища нет, ошибка ясно об этом скажет. Запросы к приостановленному хранилищу автоматически запускают его (с задержкой на старт), и каждый запуск оплачивается минимум за 60 с (за каждый старт хранилища, а не за запрос) — по возможности объединяй мелкие запросы.

Подробнее

В references/api.md — более полный справочник: все поля тела запроса, структура resultSetMetaData, все параметры сессии parameters, механика запросов из нескольких команд и дочерних дескрипторов, эндпоинты мониторинга (значения статуса в /api/v2/statements/{handle}) и заметки о типах привязки и работе с VARIANT/ARRAY. Читай его, когда нужна точная структура для того, чего нет выше.

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