このガイドでは、R2 SQL の利用時に直面しうるエラーと制限を説明します。R2 SQL はオープンベータであり、対応機能は今後変わります。
エラー: expected exactly 1 table in FROM clause
問題: 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 を返すか、タイムアウトします。
問題: 大きなテーブル同士の多方向 JOIN は、特に 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フィルターを追加して、中間結果のサイズを小さくします。- ファクトテーブル同士を直接結合するのではなく、ディメンションテーブル経由で結合します。
- 近似カウントには、
COUNT(DISTINCT)の代わりにapprox_distinct()を使います。 - 複雑な多方向 JOIN は、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 サブクエリが想定外の結果やエラーを返します。
問題: サブクエリの列に NULL が含まれる可能性がある場合、NOT IN サブクエリはサポートされません。
-- 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解決方法:
- 可能な範囲で相関条件を簡略化します。
EXISTSの代わりに、JOINとGROUP BYへの書き換えを検討します。EXISTSの代わりに、事前集計した結果に対するINサブクエリを使います。
エラー: unsupported binary operator または Error during planning: could not parse compound
問題: JSON 関数はまだ実装されていません。JSON パス演算子を使って、JSON オブジェクト内のフィールドをフィルタリングできません。
-- 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 フィールド全体でフィルタリングし、パースはアプリケーション側で行います。
maximum LIMIT is 10000問題: 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 の値を使います。
エラー: unsupported feature: OFFSET clause is not supported
問題: 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 条件を使ったカーソルベースのページネーションを実装します。
only read-only queries are allowed問題: 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 で管理します。
クエリが遅い場合は、次を確認します。
-
パーティション（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 -
選択的なフィルタリングを使います: 結果セットを減らす具体的な条件を含めます。
-- Good - Multiple filters reduce scanned data SELECT * FROM my_namespace.events WHERE status = 200 AND region = 'US' AND timestamp > '2024-01-01' LIMIT 100 -
必要な列だけを選びます: 少数のフィールドだけが必要な場合は
SELECT *を避けます。-- Good - Only reads the columns you need SELECT user_id, status, timestamp FROM my_namespace.events WHERE timestamp > '2024-01-01' LIMIT 100 -
EXPLAIN で実行計画を確認します: predicate pushdown とファイル pruning が働いているかを確認します。
EXPLAIN SELECT user_id, status FROM my_namespace.events WHERE timestamp > '2024-01-01' AND status = 200 -
compaction を有効にします: R2 Data Catalog で compaction を有効にすると、クエリあたりにスキャンする小さなファイルの数が減ります。