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。Tablet 仅支持 NetworkTopologyStrategy，而许多 Cassandra 教程仍然会展示 SimpleStrategy。

新键空间默认使用 Tablet（由 tablets_mode_for_new_keyspaces 控制）。在 Tablet 键空间中使用这些功能之前，请检查 ScyllaDB 版本：

• 物化视图和二级索引：从 ScyllaDB 2025.4 开始支持 Tablet。键空间在其整个生命周期内都必须保持 RF-rack-valid。
• 计数器：从 ScyllaDB 2026.1 开始支持 Tablet。在较旧版本中，请将计数器表放入 Vnode 键空间：

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

快速参考

每篇参考资料都会解释规则的重要性，展示错误和正确的 CQL，并列出规则不适用的情况。

1. 反模式 — 5 条规则

• antipattern-allow-filtering — ALLOW FILTERING 会强制执行全表扫描。每当在查询中看到它，或查询未包含完整分区键时，请查阅此参考。
• antipattern-large-partitions — 无界增长的分区会导致分片过热、读取缓慢，以及修复和流式传输缓慢。设计时序表或任何按分区键不断累积行的表时，请查阅此参考。
• antipattern-hot-partitions — 分区键分布不均会导致部分节点／分片负载过重，而其他节点／分片处于空闲状态。为高写入负载选择分区键时，请查阅此参考。
• antipattern-unpaged-queries — 不分页的 SELECT 会导致内存无限增长和集群不稳定。当查询可能返回超过单页的数据，或审查调用原始／不分页执行方法的代码时，请查阅此参考。
• 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 — 将无界分区拆分为有界的时间桶（例如，每天／每小时一个分区）。这对时序数据和 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 之前查阅。