← R2 SQL / r2-sql

Руководство по устранению неполадок

В этом руководстве описаны возможные ошибки и ограничения, с которыми вы можете столкнуться при использовании R2 SQL. R2 SQL находится в открытой бета-версии, и поддерживаемая функциональность будет развиваться и меняться со временем.

Проблема: Для работы R2 SQL требуется FROM предложение в вашем запросе.

-- Invalid - Missing FROM clause
SELECT user_id WHERE status = 200;

-- Valid
SELECT user_id
FROM my_namespace.http_requests
WHERE status = 200 AND timestamp BETWEEN '2025-09-24T01:00:00Z' AND '2025-09-25T01:00:00Z';

Решение: всегда указывайте FROM с полностью квалифицированным именем таблицы (namespace_name.table_name).

Симптом: Запрос возвращает 502 Bad Gateway или завершается по тайм-ауту.

Проблема: Многосторонние соединения между большими таблицами могут превышать лимиты ресурсов, особенно с COUNT(DISTINCT) или другие ресурсоемкие по памяти агрегации.

-- May timeout: cross-joining two large fact tables
SELECT COUNT(DISTINCT h.ray_id), COUNT(DISTINCT f.event_id)
FROM my_namespace.http_requests h
INNER JOIN my_namespace.firewall_events f ON h.zone_id = f.zone_id

Решение:

• Добавить WHERE фильтры, чтобы уменьшить размер промежуточных результатов.
• Выполняйте соединение через таблицы измерений вместо прямого соединения таблиц фактов.
• Используйте approx_distinct() вместо COUNT(DISTINCT) для приближенного подсчета.
• Разбивайте сложные многосторонние соединения на более мелкие запросы с помощью CTE или последовательных запросов.

-- Better: filter both sides and use approx_distinct
SELECT z.plan,
       approx_distinct(h.ray_id) AS unique_requests
FROM my_namespace.zones z
INNER JOIN my_namespace.http_requests h ON z.zone_id = h.zone_id
WHERE z.plan = 'enterprise'
  AND h.status_code >= 400
GROUP BY z.plan

Симптом: NOT IN подзапрос возвращает неожиданные результаты или ошибки.

Проблема: NOT IN подзапросы не поддерживаются, если столбец подзапроса может содержать NULL значения.

-- Fails: nullable_col may contain NULLs
SELECT zone_id
FROM my_namespace.http_requests
WHERE zone_id NOT IN (
    SELECT nullable_col FROM my_namespace.other_table
)
LIMIT 20

Решение: Используйте NOT EXISTS с коррелированным подзапросом вместо этого.

-- Works: NOT EXISTS handles NULLs correctly
SELECT h.zone_id
FROM my_namespace.http_requests h
WHERE NOT EXISTS (
    SELECT 1 FROM my_namespace.other_table o
    WHERE o.nullable_col = h.zone_id
)
LIMIT 20

Симптом: EXISTS или NOT EXISTS подзапрос выполняется медленно.

Проблема: Коррелированные подзапросы со сложными условиями могут выполняться медленно, поскольку внутренний запрос вычисляется для каждой строки внешнего запроса.

-- Slower: multiple filter conditions in correlated subquery
SELECT z.domain
FROM my_namespace.zones z
WHERE EXISTS (
    SELECT 1 FROM my_namespace.firewall_events f
    WHERE f.zone_id = z.zone_id
      AND f.risk_score > 0.9
      AND f.colo = 'SJC'
)
LIMIT 20

Решение:

• По возможности упрощайте коррелированные условия.
• Попробуйте переписать это как JOIN с GROUP BY вместо EXISTS.
• Используйте IN подзапрос с предварительно агрегированными результатами вместо EXISTS.

Проблема: Функции JSON пока не реализованы. Фильтрация по полям внутри объектов JSON с помощью операторов JSON path не поддерживается.

-- Invalid - JSON path operators not supported
SELECT * FROM my_namespace.requests WHERE json_data->>'level' = 'error'

-- Valid - Filter on the entire JSON column
SELECT * FROM my_namespace.logs WHERE json_data IS NOT NULL LIMIT 100

Решение:

• Денормализуйте часто запрашиваемые поля JSON в отдельные столбцы.
• Фильтруйте по всему полю JSON, а разбор выполняйте на стороне приложения.

Проблема: Значения LIMIT должны быть в диапазоне от 1 до 10,000.

-- Invalid - Out of range
SELECT * FROM my_namespace.events LIMIT 50000

-- Valid
SELECT * FROM my_namespace.events LIMIT 10000

Решение: Используйте значения LIMIT от 1 до 10,000.

Проблема: OFFSET не поддерживается.

-- Invalid - Pagination not supported
SELECT * FROM my_namespace.events LIMIT 100 OFFSET 200

-- Valid - Use cursor-based pagination with ORDER BY and WHERE
-- Page 1
SELECT * FROM my_namespace.events
WHERE timestamp >= '2024-01-01'
ORDER BY timestamp
LIMIT 100

-- Page 2 - Use the last timestamp from the previous page
SELECT * FROM my_namespace.events
WHERE timestamp > '2024-01-01T10:30:00Z'
ORDER BY timestamp
LIMIT 100

Решение: Реализуйте курсорную пагинацию с использованием ORDER BY и WHERE условия.

Проблема: R2 SQL представляет собой движок запросов, работающий только на чтение. Операторы DDL и DML не поддерживаются.

-- Invalid - Schema changes not supported
ALTER TABLE my_namespace.events ADD COLUMN new_field STRING
UPDATE my_namespace.events SET status = 200 WHERE user_id = '123'
CREATE TABLE my_namespace.test (id INT)
DROP TABLE my_namespace.events

Решение: Управляйте схемой через пайплайн приёма данных и R2 Data Catalog.

Если ваши запросы выполняются медленно:

1. Всегда указывайте фильтры по партиции (timestamp): Это самая важная оптимизация.

   -- Good - Narrows data scan to one day
   SELECT * FROM my_namespace.events
   WHERE timestamp BETWEEN '2024-01-01' AND '2024-01-02'
   LIMIT 100

2. Используйте выборочную фильтрацию: Указывайте конкретные условия, чтобы уменьшить объём результирующих наборов.

   -- Good - Multiple filters reduce scanned data
   SELECT * FROM my_namespace.events
   WHERE status = 200 AND region = 'US' AND timestamp > '2024-01-01'
   LIMIT 100

3. Выбор определённых столбцов: избегайте SELECT * если вам нужно всего несколько полей.

   -- Good - Only reads the columns you need
   SELECT user_id, status, timestamp
   FROM my_namespace.events
   WHERE timestamp > '2024-01-01'
   LIMIT 100

4. Используйте EXPLAIN, чтобы посмотреть план выполнения: Убедитесь, что проброс предикатов и отсечение файлов работают.

   EXPLAIN SELECT user_id, status
   FROM my_namespace.events
   WHERE timestamp > '2024-01-01' AND status = 200

5. Включение уплотнения: Включите уплотнение в R2 Data Catalog, чтобы уменьшить количество мелких файлов, сканируемых при каждом запросе.