ScyllaDB Column Family REST API 完全指南从元数据查询到运维控制与监控指标【免费下载链接】scylladbNoSQL data store using the Seastar framework, compatible with Apache Cassandra and Amazon DynamoDB项目地址: https://gitcode.com/GitHub_Trending/sc/scylladbScyllaDB 在兼容 Apache Cassandra 协议之外还内置了一套基于 Seastar HTTP Server 的 RESTful 管理 API其中Column Family列族相关接口是日常运维、监控与调优的核心入口。本文以仓库中的 API 规范文档 docs/reference/api/column-family.rst 及其引用的 Swagger 规范 api/api-doc/column_family.json 为骨架结合路由实现 api/column_family.cc系统梳理该组接口的端点、参数、实现原理与典型用法帮助你快速上手用 REST 方式管理 ScyllaDB 的表Table即传统 Cassandra 语境中的 Column Family。说明本文涉及的端点、参数与行为均以当前仓库中的 Swagger 规范与源码实现为准不同 ScyllaDB 版本之间接口细节可能存在差异请以你所部署版本为准。一、认识 Column Family API文档如何被渲染出来1.1 文档占位符与 Swagger 规范column-family.rst 本体只有短短几行通过 Sphinx 自定义指令.. scylladb_swagger::将完整的 Swagger 1.2 规范 api/api-doc/column_family.json 渲染为可读的 API 文档页:exclude-doctools: Column Family .. scylladb_swagger_inc:: .. scylladb_swagger:: :spec: api/api-doc/column_family.json也就是说这份文档的真身是约 3000 行的column_family.json它按 Swagger 1.2 格式定义了resourcePath: /column_family下的全部操作operation、路径参数path parameter与查询参数query parameter以及 4 个响应模型mapper、column_family_info、toppartitions_record、toppartitions_query_results。所有端点统一produces: application/jsonbasePath由{{Protocol}}://{{Host}}占位。1.2 路由注册与生命周期REST 端点由 api/column_family.cc 中的set_column_family(http_context ctx, routes r, shardedreplica::database db)统一注册约 第400行并在unset_column_family()中对称注销约 第1227行。每个端点背后都操作replica::database大量统计类端点通过map_reduce_cf/map_reduce_cf_raw在 Seastar 多 shard 之间并行聚合数据后返回这解释了为什么单表指标能够反映整个集群视图。1.3 名称格式keyspace:name 与 %3A 转义几乎所有端点都要求路径参数name采用keyspace:column_family全限定格式。源码 parse_fully_qualified_cf_name() 的解析逻辑非常关键优先查找 URL 编码的冒号%3A作为分隔符兼容将ks:cf直接拼进 URL 路径的场景若未找到%3A再查找原始冒号:两者都找不到则抛出bad_param_exception错误信息为 Column family name should be in keyspace:column_family format。因此调用时既可写/column_family/.../mykeyspace%3Amycf也可写mykeyspace:mycf但务必保证冒号被正确传递。二、表枚举与元数据查询端点以下端点无需任何参数用于发现集群中存在哪些表端点方法返回说明/column_family/GETarraycolumn_family_info返回所有表的ks、cf、type恒为ColumnFamilies/column_family/nameGETarraystring返回所有表的keyspace:name字符串列表/column_family/name/keyspaceGETarraystring返回全部 keyspace 名称列表实现上三个端点都直接遍历db.local().get_tables_metadata()或get_all_keyspaces()见 get_column_family_name / get_column_family / get_column_family_name_keyspace 的注册代码属于轻量级查询适合脚本化巡检。三、运维控制端点压缩、GC 与数据加载这一组端点直接对表执行运维动作是 Column Family API 的控制面。3.1 强制 Major CompactionPOST /column_family/major_compaction/{name}参数参数类型必填默认说明namepath是—keyspace:name格式flush_memtablesquery否true压缩前是否先 flush memtable设为false可跳过自动 flush例如已显式 flush 过表consider_only_existing_dataquery否false设为true时 flush 全部 memtable并强制 tombstone GC 只检查参与压缩的 sstables不检查 memtable、commitlog 与未参与压缩的 sstablessplit_outputquery否—若为 true则 major compaction 输出被拆分为多个 sstable实现细节force_major_compaction 路由当同时满足!flush !consider_only_existing_data时会以compaction::flush_mode::skip跳过 flush请求会创建并等待一个compaction::major_keyspace_compaction_task_impl任务完成属于异步长任务在压缩完成前请求不会返回当前版本中split_output一旦被设置会直接fail(unimplemented::cause::API)说明该参数在规范中已声明但实现尚未支持。3.2 压缩阈值Compaction Threshold三个相关端点均以keyspace:name为路径参数端点方法参数说明/column_family/minimum_compaction/{name}POSTvaluelong必填设置触发压缩所需的最小 sstable 排队数/column_family/minimum_compaction/{name}GET—读取该最小值/column_family/maximum_compaction/{name}POSTvaluelong必填设置触发压缩所需的最大 sstable 排队数/column_family/maximum_compaction/{name}GET—读取该最大值/column_family/compaction/{name}POSTmaximum、minimumlong必填一次同时设置最大与最小阈值3.3 压缩策略Compaction StrategyPOST /column_family/compaction_strategy/{name} 参数 class_name必填 GET /column_family/compaction_strategy/{name}GET 返回当前压缩策略的类名。POST 将表的压缩策略切换为指定类名实现上调用cf.set_compaction_strategy(compaction::compaction_strategy::type(strategy))见 set_compaction_strategy_class并在所有 shard 上同步生效。可用的策略类型定义在 compaction/compaction_strategy_type.hh 中size_tiered、leveled、time_window、in_memory、incremental另有null内部占位。例如class_nameSizeTieredCompactionStrategy对应size_tiered类型。3.4 压缩参数、CRC 与压缩比端点方法参数说明/column_family/compression_parameters/{name}GET—读取压缩参数当前实现返回空 map见 get_compression_parameters/column_family/compression_parameters/{name}POSTopts必填设置压缩参数当前为unimplemented()占位/column_family/crc_check_chance/{name}POSTcheck_chancedouble必填设置 CRC 检查概率当前为unimplemented()占位/column_family/metrics/compression_ratio/{name}GET—返回压缩比对所有 sstable 的压缩比求平均未压缩的表返回 0实现见 get_compression_ratio从源码可见压缩参数与 CRC 检查概率的写接口在规范中已定义但实现尚为占位直接调用会命中unimplemented()读取压缩比则是真实可用的。3.5 自动压缩开关AutocompactionGET /column_family/autocompaction/{name} POST /column_family/autocompaction/{name} # 启用 DELETE /column_family/autocompaction/{name} # 禁用GET 通过!cf.is_auto_compaction_disabled_by_user()判断是否启用见 get_auto_compaction。启停操作在 shard 0 上通过autocompaction_toggle_guardapi/column_family.cc#L94-L110加互斥保护防止并发开关互相覆盖然后对所有 shard 上的表逐个调用enable_auto_compaction()/disable_auto_compaction()。storage_service API 中还有对应的 keyspace 级批量开关POST /storage_service/auto_compaction等端点复用同一套set_tables_autocompaction逻辑。3.6 Tombstone GC 开关GET /column_family/tombstone_gc/{name} # 查询是否启用 POST /column_family/tombstone_gc/{name} # 启用 DELETE /column_family/tombstone_gc/{name} # 禁用实现与 autocompaction 类似get_tombstone_gc 等路由通过t.tombstone_gc_enabled()查询、t.set_tombstone_gc_enabled(bool)设置并在所有 shard 上生效。3.7 键估值与内置索引端点方法说明/column_family/estimate_keys/{name}GET返回估算的键数量long/column_family/built_indexes/{name}GET返回当前存储中已构建的列索引名称列表/column_family/droppable_ratio/{name}GET返回可丢弃 tombstone 与真实列含不可丢弃 tombstone的比值double用于评估压缩时 tombstone 清理收益3.8 SSTable 定位与层级信息GET /column_family/sstables/by_key/{name}?key... GET /column_family/sstables/unleveled/{name} GET /column_family/sstables/per_level/{name} GET /column_family/load/sstable/{name} # POSTby_key查询参数key为分区键复合键场景下用:分隔各列。实现调用get_sstables_by_partition_key(key)后返回包含该键的 sstable 文件名集合见 get_sstables_for_key并在所有 shard 上合并去重可用于诊断某个热点分区落在哪些 sstable 中。unleveled返回 L0 层 sstable 数量未启用 Leveled 压缩时恒为 0规范原文 Always return 0 if Leveled compaction is not enabled。per_level返回每个层级level的 sstable 数量数组非 Leveled 压缩时空数组。load/sstablePOST 扫描该表的 data 目录判定哪些 sstable 应被加载并加载它们常用于外部数据灌入场景。3.9 Toppartitions 查询GET /column_family/toppartitions/{name}?durationmslist_sizencapacityn用于统计指定时长内读写最热的分区类似nodetool toppartitions的 REST 版本参数类型必填默认值说明namepath是—keyspace:namedurationquery是—监控时长毫秒list_sizequery否10列出多少个 Top 分区capacityquery否256Stream Summary 容量决定查询处理时使用的资源量注意该路径版本duration在规范中标记为必填而 storage_service 上还有通用的/storage_service/toppartitions端点其duration默认1000ms、capacity默认256、list_size默认10见 rest_toppartitions_generic并额外支持table_filters与keyspace_filters逗号分隔过滤。返回模型toppartition_query_results包含read_cardinality、read、write_cardinality、write四个字段其中每个 record 包含partition分区键、count读写操作次数与error计数误差指示来自 Stream Summary 的近似统计。四、Memtable 监控端点Memtable 是写入路径的第一站ScyllaDB 为每个 shard 维护各自的 memtable因此这些端点分为单表带{name}与全部表不带{name}聚合所有 shard两类端点单表 / 全部返回说明/column_family/metrics/memtable_columns_count[/{name}]long活动 memtable 中的分区数量实现使用partition_count/column_family/metrics/memtable_on_heap_size[/{name}]long活动 memtable 的堆内大小当前实现返回 0/column_family/metrics/memtable_off_heap_size[/{name}]long活动 memtable 的堆外off-heap占用/column_family/metrics/memtable_live_data_size[/{name}]long活动 memtable 的有效数据大小/column_family/metrics/all_memtables_on_heap_size[/{name}]long活动与非活动 memtable 的堆内大小当前实现返回 0/column_family/metrics/all_memtables_off_heap_size[/{name}]long全部 memtable 的堆外占用/column_family/metrics/all_memtables_live_data_size[/{name}]long全部 memtable 的有效数据大小/column_family/metrics/memtable_switch_count[/{name}]longmemtable 切换flush 换新次数实现要点api/column_family.cc#L427-L525堆外大小通过active_memtable.region().occupancy().total_space()统计有效数据大小通过used_space()统计分区数量通过partition_count累加全部表版本用map_reduce_cf跨 shard 求和。代码注释FIXME也指出部分端点如estimated_row_size_histogram实际统计的是分区partition而非行row阅读数据时需留意这一口径差异。五、读写统计与延迟直方图端点5.1 读写计数端点方法返回说明/column_family/metrics/read/{name}GETlong该表的读操作次数/column_family/metrics/read/GETarray所有表各 shard 的读次数per shard 数组/column_family/metrics/write/{name}GETlong该表的写操作次数/column_family/metrics/write/GETarray所有表各 shard 的写次数5.2 延迟统计延迟相关端点较为丰富覆盖累计值、直方图与滑动平均直方图端点返回类型说明/column_family/metrics/read_latency/{name}long读延迟累计值/column_family/metrics/read_latencylong全部表读延迟累计/column_family/metrics/write_latency/{name}、/column_family/metrics/write_latencylong写延迟累计值/column_family/metrics/range_latency/{name}、/column_family/metrics/range_latencylong范围扫描延迟累计/column_family/metrics/read_latency/histogram/{name}、/column_family/metrics/read_latency/histogram/histogram/ array读延迟直方图规范中标记为 deprecated 名称get_read_latency_histogram_depricated/column_family/metrics/write_latency/histogram/{name}、.../histogram/histogram/ array写延迟直方图/column_family/metrics/read_latency/moving_average_histogram/{name}、.../moving_average_histogram/rate_moving_average_and_histogram/ array读延迟滑动平均直方图含速率/column_family/metrics/write_latency/moving_average_histogram/{name}、.../moving_average_histogram/rate_moving_average_and_histogram/ array写延迟滑动平均直方图/column_family/metrics/read_latency/estimated_histogram/{name}estimated_histogram读延迟估计直方图/column_family/metrics/read_latency/estimated_recent_histogram/{name}estimated_histogram读延迟近期估计直方图/column_family/metrics/write_latency/estimated_histogram/{name}、.../estimated_recent_histogram/{name}estimated_histogram写延迟估计/近期直方图/column_family/metrics/range_latency/estimated_histogram/{name}、.../estimated_recent_histogram/{name}estimated_histogram范围延迟估计/近期直方图累计值计算方式值得注意源码 get_cf_stats_sum 用count / 1000.0 * mean估算总和并注释说明直方图只是实际负载的采样估算结果以微秒为单位gather in nano second, but reported in micro。5.3 CASCompare-And-Swap延迟轻量级事务LWT的三阶段延迟分别对应三个端点每类都提供普通直方图与估计直方图变体/column_family/metrics/cas_prepare/{name}、.../cas_prepare/estimated_histogram/{name}、.../cas_prepare/estimated_recent_histogram/{name}/column_family/metrics/cas_propose/{name}及 estimated 变体/column_family/metrics/cas_commit/{name}及 estimated 变体实现分别取stats.cas_prepare、stats.cas_accept、stats.cas_learn的直方图api/column_family.cc#L900-L916。5.4 扫描与等待统计端点说明/column_family/metrics/tombstone_scanned_histogram/{name}读路径扫描到的 tombstone 数量直方图/column_family/metrics/live_scanned_histogram/{name}读路径扫描到的存活数据直方图/column_family/metrics/sstables_per_read_histogram/{name}单次读涉及的 sstable 数量估计直方图/column_family/metrics/col_update_time_delta_histogram/{name}列更新时间差直方图当前为unimplemented()占位/column_family/metrics/waiting_on_free_memtable等待空闲 memtable 空间的直方图协调器级/column_family/metrics/coordinator/read协调器读延迟直方图集群级/column_family/metrics/coordinator/scan协调器扫描延迟直方图集群级六、存储、缓存与过滤结构指标端点6.1 磁盘空间与 sstable 计数端点返回说明/column_family/metrics/live_ss_table_count/{name}、.../live_ss_table_countlong存活 sstable 数量/column_family/metrics/live_disk_space_used/{name}、.../live_disk_space_usedlong存活 sstable 占用的磁盘空间/column_family/metrics/total_disk_space_used/{name}、.../total_disk_space_usedlong总磁盘占用含已压缩未删除的 sstable实现使用get_sstables_including_compacted_undeleted()见 count_bytes_on_disk/column_family/metrics/pending_flushes/{name}、.../pending_flusheslong待处理的 flush 数/column_family/metrics/pending_compactions/{name}、.../pending_compactionslong待处理的压缩数实现调用cf.estimate_pending_compactions()/column_family/metrics/snapshots_size/{name}、.../true_snapshots_sizelong快照真实大小6.2 分区大小统计min / max / mean row size/column_family/metrics/min_row_size/{name}、.../min_row_size/column_family/metrics/max_row_size/{name}、.../max_row_size/column_family/metrics/mean_row_size/{name}、.../mean_row_size代码注释明确这些统计基于 sstable 元数据中的estimated_partition_size因此统计对象是分区而非行均值与 Cassandra 3.x 一致按整数截断api/column_family.cc#L238-L262。另有/column_family/metrics/estimated_row_size_histogram/{name}分区大小估计直方图/column_family/metrics/estimated_row_count/{name}估计行分区数/column_family/metrics/estimated_column_count_histogram/{name}估计列数直方图6.3 Bloom Filter 指标端点说明/column_family/metrics/bloom_filter_false_positives/{name}、.../bloom_filter_false_positives误报累计次数/column_family/metrics/recent_bloom_filter_false_positives/{name}、...近期误报次数/column_family/metrics/bloom_filter_false_ratio/{name}、...误报率double/column_family/metrics/recent_bloom_filter_false_ratio/{name}、...近期误报率/column_family/metrics/bloom_filter_disk_space_used/{name}、...Bloom Filter 磁盘占用/column_family/metrics/bloom_filter_off_heap_memory_used/{name}、...Bloom Filter 堆外内存占用误报率通过filter_get_false_positive() / (false_positive true_positive)计算filter_false_positive_as_ratio_holder。6.4 索引与缓存指标端点说明/column_family/metrics/index_summary_off_heap_memory_used/{name}、...索引摘要index summary堆外内存占用实现取sst-get_summary().memory_footprint()/column_family/metrics/compression_metadata_off_heap_memory_used/{name}、...压缩元数据堆外内存占用当前实现返回 0源码注明缺少 off-heap 计算/column_family/metrics/key_cache_hit_rate/{name}、...键缓存命中率当前为unimplemented()占位/column_family/metrics/row_cache_hit/{name}、.../row_cache_hit行缓存命中率滑动平均速率/column_family/metrics/row_cache_miss/{name}、.../row_cache_miss行缓存未命中率/column_family/metrics/row_cache_hit_out_of_range/{name}、...行缓存越界命中当前为占位/column_family/metrics/speculative_retries/{name}、...推测性重试计数当前为占位七、实战用 curl 调用 Column Family APIScyllaDB 的 REST API 默认监听在api_port: 10000、api_address: 127.0.0.1见 conf/scylla.yaml 第 224、227 行可通过启动参数覆盖。以下示例假设 API 地址为127.0.0.1:10000# 1. 列出所有表 curl -s http://127.0.0.1:10000/column_family/ # 2. 列出所有 keyspace:name curl -s http://127.0.0.1:10000/column_family/name # 3. 查询指定表是否开启自动压缩 curl -s http://127.0.0.1:10000/column_family/autocompaction/myks%3Amycf # 4. 临时关闭某表的自动压缩大流量导入/迁移前 curl -s -X DELETE http://127.0.0.1:10000/column_family/autocompaction/myks%3Amycf # 5. 重新开启自动压缩 curl -s -X POST http://127.0.0.1:10000/column_family/autocompaction/myks%3Amycf # 6. 强制 major compaction等待完成 curl -s -X POST http://127.0.0.1:10000/column_family/major_compaction/myks%3Amycf # 7. 跳过 memtable flush 的 major compaction curl -s -X POST http://127.0.0.1:10000/column_family/major_compaction/myks%3Amycf?flush_memtablesfalse # 8. 查看表当前压缩策略 curl -s http://127.0.0.1:10000/column_family/compaction_strategy/myks%3Amycf # 9. 切换为 Leveled 压缩策略 curl -s -X POST http://127.0.0.1:10000/column_family/compaction_strategy/myks%3Amycf?class_nameLeveledCompactionStrategy # 10. 查看读写计数与磁盘占用 curl -s http://127.0.0.1:10000/column_family/metrics/read/myks%3Amycf curl -s http://127.0.0.1:10000/column_family/metrics/write/myks%3Amycf curl -s http://127.0.0.1:10000/column_family/metrics/live_disk_space_used/myks%3Amycf curl -s http://127.0.0.1:10000/column_family/metrics/total_disk_space_used/myks%3Amycf # 11. 查看 Bloom Filter 误报率 curl -s http://127.0.0.1:10000/column_family/metrics/bloom_filter_false_ratio/myks%3Amycf # 12. 定位包含某分区键的 sstable 文件 curl -s http://127.0.0.1:10000/column_family/sstables/by_key/myks%3Amycf?keysome_partition_key # 13. 运行 5 秒 toppartitions 查询列出前 20 个热点分区 curl -s http://127.0.0.1:10000/column_family/toppartitions/myks%3Amycf?duration5000list_size20几点使用提醒URL 编码keyspace:name中的冒号建议编码为%3A避免与 URL 路径语义冲突长任务major_compaction是同步等待的异步任务压缩耗时较长时 curl 会长时间挂起生产环境建议在运维窗口执行或配合超时使用占位端点compression_parametersPOST、crc_check_chance、key_cache_hit_rate、speculative_retries、col_update_time_delta_histogram、split_output等在当前版本中仍是unimplemented()占位调用前应先在目标版本上验证口径差异estimated_row_count、min/max/mean_row_size等实际统计的是分区read_latency累计值是基于直方图采样的估算值解读指标时需结合代码注释理解。八、与 storage_service 端点的关系api/column_family.cc 中同时注册了部分storage_service命名空间的端点它们复用了相同的底层实现但作用域不同POST/DELETE /storage_service/auto_compaction按 keyspace可选指定表列表批量启停自动压缩POST/DELETE /storage_service/tombstone_gc按 keyspace 批量启停 tombstone GCGET /storage_service/toppartitions支持table_filters、keyspace_filters过滤的通用 toppartitions 查询GET /storage_service/load与/storage_service/metrics/load基于live_disk_space_used.on_disk的集群负载统计GET /storage_service/keyspaces按typeuser / non_local_strategy / 全部与replicationall / tablets过滤 keyspace 列表POST /storage_service/flush、POST /storage_service/keyspace_flush全库 / 指定 keyspace 的 flushPOST /system/drop_sstable_caches全库丢弃 sstable 缓存。这些端点与/column_family/前缀的接口互为补充前者面向 keyspace/集群维度批量操作后者面向单表精细控制。九、总结与速查Column Family REST API 可以归纳为四类能力发现/column_family/、/column_family/name、/column_family/name/keyspace快速枚举表与 keyspace控制major compaction、压缩阈值、压缩策略、autocompaction、tombstone GC、sstable 加载覆盖日常运维动作诊断sstables by_key、per_level、unleveled、droppable_ratio、toppartitions定位热点与存储布局问题监控memtable、读写计数、延迟直方图、CAS 三阶段延迟、磁盘占用、Bloom Filter、行缓存等数十个指标端点。其文档骨架是 docs/reference/api/column-family.rst 指向的 api/api-doc/column_family.json Swagger 规范行为实现在 api/column_family.cc。理解规范中声明的参数与源码中实际实现状态的差异尤其是标记为unimplemented()或返回 0 的占位端点是正确使用这套 API 的关键前提。通过 REST 方式你可以把 ScyllaDB 的表级运维与监控无缝接入现有的自动化脚本、监控大盘与巡检系统中。【免费下载链接】scylladbNoSQL data store using the Seastar framework, compatible with Apache Cassandra and Amazon DynamoDB项目地址: https://gitcode.com/GitHub_Trending/sc/scylladb创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考