scylladb-data-modeling

ScyllaDB のデータモデリング

このスキルの範囲を超えるタスクでは、ScyllaDB の概要とその他の ScyllaDB スキルの一覧について、親の scylladb スキルを使用してください。インストールされていない場合は、https://raw.githubusercontent.com/scylladb/agent-skills/main/skills/scylladb/SKILL.md から取得してください。

ScyllaDB の CQL データモデリングのパターンとアンチパターンを説明します。ScyllaDB のパフォーマンス問題の大半は、不適切なスキーマが根本原因です。クラスターをどれだけスケールしても、根本的に誤ったデータモデルは修正できません。

このスキルを使用する場面

• ScyllaDB の新しいスキーマを一から設計するとき
• SQL／リレーショナルデータベース、MongoDB、Cassandra から ScyllaDB に移行するとき
• パフォーマンスの問題について、既存のテーブル設計をレビューするとき
• クエリの遅延、タイムアウト、ホットノードのトラブルシューティングを行うとき
• 主キー（パーティションキーとクラスタリングカラム）の構成を決めるとき
• 時系列データ、IoT データ、イベントデータをモデリングするとき
• ログに大きなパーティションに関する警告が表示されたとき
• クエリやコードレビューで ALLOW FILTERING が見つかったとき
• セカンダリインデックスやマテリアライズドビューを追加するとき
• コンパクション戦略を選択するとき、またはテーブルの TTL や保持期間を設定するとき
• 削除済みデータ、期限切れデータ、トゥームストーンの警告によって読み取りが遅くなったとき
• 条件付きステートメント（IF NOT EXISTS、IF EXISTS、IF <condition>）を書くとき、または直列一貫性を選択するとき

関連するトピックについては、代わりに次の兄弟スキルを使用してください。

• ドライバーの接続、選択、ステートメントの準備：scylladb-cloud-setup
• ベクターカラム、ベクターインデックス、ANN クエリ：scylladb-vector-search
• DynamoDB API を通じて作成されたテーブル：scylladb-alternator。このスキルのパーティションキールールは、それらのテーブルにも適用されます。
• ラック構成やレプリケーション係数のレイアウトを含む、Kubernetes でのクラスターのデプロイ：scylladb-kubernetes

重要な原則

「エンティティではなく、クエリから始める。」

これが ScyllaDB のデータモデリングにおける基本的な考え方です。エンティティを正規化してからクエリを書くリレーショナルデータベースとは異なり、ScyllaDB では次のようにします。

1. アプリケーションのクエリを列挙する — アプリケーションが実行するすべての SELECT、UPDATE、DELETE
2. クエリパターンごとにテーブルを設計する — 各テーブルの主キーは、特定のクエリを効率的に処理できるように作成します
3. 非正規化を受け入れる — 同じデータが複数のテーブルに存在する場合があります。それぞれのテーブルを、異なるアクセスパターンに最適化します

ScyllaDB では、パーティションキーによってデータを保持するノードが決まり、クラスタリングカラムによってパーティション内のソート順が決まります。主キーがアクセスパターンそのものです。

主キーの構造

PRIMARY KEY ((partition_key_col1, partition_key_col2), clustering_col1, clustering_col2)
            |___________________________________|   |__________________________________|
                     Partition key                         Clustering columns
                 (determines node/shard)             (determines sort order within
                                                      the partition)

ルール

1. パーティションキーは、すべての WHERE 句に必ず含める必要があります — パーティションキー全体を指定しないクエリには、ALLOW FILTERING（全件スキャン）またはセカンダリインデックスが必要です
2. クラスタリングカラムがソート順を定義します — デフォルトは ASC で、WITH CLUSTERING ORDER BY で設定できます
3. パーティションキーがデータの分散先を決定します — 同じパーティションキーを持つすべての行は、同じノード／シャードに格納されます

SQL / MongoDB との比較

概念	SQL	MongoDB	ScyllaDB
スキーマ設計	エンティティ優先（正規化）	ドキュメント優先（埋め込み）	クエリ優先（クエリごとに非正規化）
データ単位	テーブル内の行	コレクション内のドキュメント	パーティション内の行
結合	JOIN 句	$lookup 集約	サポートされていません — 代わりに非正規化します
集約	任意の列、任意の GROUP BY	集約パイプライン	COUNT、SUM、AVG、MIN、MAX。GROUP BY は主キーのプレフィックスでのみ使用できます
柔軟なスキーマ	いいえ（厳密な DDL）	はい（スキーマは任意）	いいえ（厳密な CQL DDL）
クエリに必要なインデックス	多くの場合は任意	推奨	すべてのクエリでパーティションキーが必要
一意制約	UNIQUE	unique: true インデックス	主キーのみ。INSERT ... IF NOT EXISTS（LWT）は重複を拒否します。キー以外の列では、その列をキーとするルックアップテーブルに挿入します
トランザクション	完全な ACID	複数ドキュメントの ACID	単一パーティションの線形化可能な操作には軽量トランザクション（LWT）

キースペースの作成（ScyllaDB 2025.4 以降）

ScyllaDB 2025.4 以降では、WITH replication は省略できます。通常は簡易形式を使用してください。

CREATE KEYSPACE myapp;

NetworkTopologyStrategy と replication_factor を明示的に指定する方法も引き続き有効ですが、必須ではありません。

SimpleStrategy は使用しないでください。タブレットがサポートするのは NetworkTopologyStrategy のみです。また、多くの Cassandra チュートリアルでは、今も SimpleStrategy が紹介されています。

新しいキースペースでは、デフォルトでタブレットが使用されます（tablets_mode_for_new_keyspaces で制御）。タブレットキースペースでこれらの機能を使用する前に、ScyllaDB のバージョンを確認してください。

• マテリアライズドビューとセカンダリインデックス：ScyllaDB 2025.4 以降、タブレットでサポートされています。キースペースは、その存続期間を通じて RF-rack-valid を維持する必要があります。
• カウンター：ScyllaDB 2026.1 以降、タブレットでサポートされています。それより古いバージョンでは、カウンターテーブルを vnodes キースペースに配置してください。

CREATE KEYSPACE myapp_counters
  WITH replication = {'class': 'NetworkTopologyStrategy', 'replication_factor': 3}
  AND tablets = {'enabled': false};

クイックリファレンス

各リファレンスでは、そのルールが重要な理由を説明し、誤った CQL と正しい CQL を示したうえで、ルールが適用されない場合を列挙します。

1. アンチパターン — 5 つのルール

• antipattern-allow-filtering — ALLOW FILTERING は全件スキャンを強制します。クエリにこれが含まれている場合や、クエリに完全なパーティションキーが含まれていない場合は、このリファレンスを参照してください。
• antipattern-large-partitions — 上限なく増大するパーティションは、ホットシャード、読み取りの遅延、修復とストリーミングの遅延を引き起こします。時系列テーブルや、パーティションキーごとに行が蓄積されるテーブルを設計する際に参照してください。
• antipattern-hot-partitions — パーティションキーの分布に偏りがあると、一部のノード／シャードに負荷が集中し、ほかのノード／シャードがアイドル状態になります。書き込み負荷の高いワークロード向けにパーティションキーを選ぶ際に参照してください。
• antipattern-unpaged-queries — ページングされていない SELECT は、メモリ使用量の無制限な増加とクラスターの不安定化を引き起こします。クエリが 1 ページを超える行を返す可能性がある場合や、生の実行メソッドまたはページングされていない実行メソッドを呼び出すコードをレビューする際に参照してください。
• antipattern-multi-partition-batch — 複数のパーティションにまたがる BATCH 文には、実質的な原子性のメリットがなく、コーディネーターのホットスポットを発生させます。トランザクションを模倣するために BATCH を使うコードをレビューする際や、SQL のトランザクションロジックを CQL に移行する際に参照してください。

2. 基本 — 3 つのルール

• query-first-design — エンティティではなく、クエリを基準にテーブルを設計します。アプリケーションのアクセスパターンを CQL のテーブル定義に変換する方法を説明します。新しいスキーマの作成を始める際や、リレーショナルモデルまたはドキュメントモデルをテーブルに変換する際に参照してください。
• partition-key-design — データを均等に分散し、クエリをサポートするパーティションキーの選び方を説明します。複合パーティションキーも含みます。パーティションキーを選択またはレビューする際や、単一のカラムではカーディナリティが十分でない場合に参照してください。
• clustering-columns — クラスタリングカラムがパーティション内のソート順をどのように制御するか、また、範囲クエリや時系列データにどう使用するかを説明します。クエリでソート済みの結果、範囲条件、または WITH CLUSTERING ORDER BY が必要な場合に参照してください。

3. パターン — 3 つのルール

• pattern-bucketing — 上限のないパーティションを、上限のある時間バケット（例：日または時間ごとに 1 つのパーティション）に分割します。時系列データや IoT データには欠かせません。パーティションキーごとに行が無制限に蓄積される場合に参照してください。
• secondary-indexes-and-mv — セカンダリインデックス、ローカルセカンダリインデックス、マテリアライズドビューを使用するタイミングと、代わりに非正規化テーブルを優先すべき場合について説明します。クエリが主キー以外のカラムでフィルタリングする場合や、CREATE INDEX または CREATE MATERIALIZED VIEW を追加する前に参照してください。
• lwt — 条件付き文、Paxos のコスト、シリアル整合性、アトミックな算術演算（ScyllaDB 2026.3+）、および Cassandra の LWT との違いについて説明します。文に IF 句が含まれる場合、SERIAL または LOCAL_SERIAL を選ぶ場合、条件付き書き込みがタイムアウトする場合、または結果セットを読み取る Cassandra LWT コードを移植する場合に参照してください。

4. データライフサイクル — 3 つのルール

• compaction-strategies — ワークロードごとに ICS、LCS、TWCS を選ぶ方法、TWCS のルール、コンパクションオプションを安全に変更する方法を説明します。テーブルの作成時、compaction = {...} 句を記述するとき、またはディスク使用量や書き込み増幅が大きいときに参照してください。
• ttl — セルごとの TTL のセマンティクス、default_time_to_live、行ごとの TTL（ScyllaDB 2026.2+）、期限切れデータがディスクから削除される仕組みを説明します。データに保持期間があるとき、USING TTL を使用するとき、または行の一部だけが期限切れになるときに参照してください。
• tombstones — トゥームストーンが作成される仕組み、tombstone_gc のモードとデフォルト値、ScyllaDB の空ページの動作、キューのアンチパターンを説明します。削除を設計するとき、削除後に読み取りが遅くなったとき、空のページが返されるとき、または gc_grace_seconds を変更する前に参照してください。