SelectDB Cloud POC 最佳实践
概念验证（Proof of Concept，POC）用于判断 SelectDB Cloud 是否满足目标业务的技术与运行要求。在导入数据前明确验证范围和验收标准，才能让测试结果可复现，并为部署决策提供依据。
一次完整的 POC 应覆盖以下目标：
- 使用具有代表性的数据、SQL、并发和数据新鲜度要求，验证优先级最高的业务场景。
- 确认表模型、排序键、分区、分桶和索引设计符合数据写入与查询模式。
- 对照验收标准，测量导入吞吐、查询延迟、资源消耗和费用。
- 与源系统或已有基准比对查询结果，验证数据正确性。
- 检查连接、认证、监控、诊断和工作负载隔离等运行要求。
- 识别正式上线前仍需完成的配置调整、模型优化和业务改造。
建议按照“准备评估 → 建表设计 → 数据导入 → 查询调优 → 数据湖查询 → 记录与复测”的顺序开展。只需熟悉基本操作时，可先完成快速开始。
准备评估
明确数据与验收标准
选择能够反映生产特征的数据与查询，覆盖大表、常见过滤条件、多表关联、更新模式和并发负载。小型示例数据可以用于验证功能，但不能代表生产环境中的查询或导入性能。
| 验证维度 | 建议提前明确的内容 |
|---|---|
| 数据正确性 | 行数、主键唯一性、汇总金额、去重口径、更新和删除后的预期结果。 |
| 数据接入 | 全量数据规模、增量速率、批次大小、更新比例、容许的数据延迟及失败重试方式。 |
| 查询性能 | 代表性 SQL、查询参数、并发数、P50/P95/P99 响应时间、超时与错误率。 |
| 资源与成本 | 计算和缓存配置、存储规模、测试时长，以及达到目标吞吐或并发所需的费用。 |
| 运行要求 | 网络接入、权限、监控、故障排查、集群伸缩和工作负载隔离。 |
先确认结果正确，再评估性能。对于 CDC、Upsert 和预聚合场景，不能只用导入前后的行数是否相同判断正确性，还需要比对业务主键、最新状态和指标口径。
准备 SelectDB Cloud 环境
- 登录 SelectDB Cloud 控制台，选择目标组织和仓库。按企业要求使用 SaaS 或 BYOC 部署方式，云厂商与地域以控制台可选项为准，建议尽量靠近数据源和测试客户端。
- 在计算集群中确认目标集群为运行中，记录集群名称、vCPU、内存、缓存容量和伸缩策略。仓库可以包含多个计算集群，测试时应确认 SQL 实际使用的集群。
- 通过 SQL 编辑器或兼容客户端访问仓库。外部客户端使用连接页面提供的地址、端口和加密参数，并完成公网 IP 白名单或私网接入配置。数据库用户与控制台账号相互独立。
- 确认测试数据所需的数据库权限、外部数据源授权及网络可达性，避免将连接或鉴权失败误判为数据库性能问题。
- 记录内核版本、部署方式、云厂商、地域和计费方式，确认测试预算。资源和连接操作参见计算集群管理和连接方式。
试用仓库适合功能体验，试用资格和限制以控制台提示为准。SaaS 免费试用仓库不支持新建集群，免费试用集群不支持伸缩；正式验证多集群隔离或目标生产规模前，应准备满足测试要求的资源。
基线测试期间，保持资源配置和后台负载一致。自动伸缩、自动暂停后的恢复以及缓存变化都应作为测试条件记录；需要验证这些能力时，单独设计相应测试。
快速检查清单
- 每张表的模型是否符合追加、更新或聚合语义？
- 排序键、分区、分桶和索引是否与代表性查询匹配？
- 分桶数是否与分区数据量、查询并行度及目标集群规模相适应？
- 导入结果是否已完成行数、状态和业务指标校验？
- 是否分别测试冷缓存和热缓存，并记录资源配置及并发？
- 是否保存执行计划、查询 Profile、导入状态和数据分布信息？
- 是否与预先约定的准确性、性能、数据新鲜度及成本标准逐项对比？
建表设计
建表时需要同时考虑数据模型、排序键、分区和分桶。这些决策会影响数据语义、导入成本、扫描量和查询并行度。
数据模型
按数据写入方式选择模型，不要只根据表名或某一次查询的速度决定。
| 数据特征 | 推荐模型 | 需要验证的行为 |
|---|---|---|
| 仅追加的日志、事件、事实明细 | 明细模型（Duplicate Key） | 保留写入的明细行；重复导入会增加记录。 |
| 按主键更新的订单、用户资料、CDC 数据 | 主键模型（Unique Key） | 同一主键维护一条记录；同时验证更新顺序、删除及重试语义。 |
| 按固定维度预聚合的指标 | 聚合模型（Aggregate Key） | 按 Key 和指定聚合函数合并数据，确认汇总口径正确。 |
明细模型适合保留原始记录并开展灵活分析；需要去重、更新或预聚合时，应选择相应模型。UV 等去重指标不能通过简单相加或取最大值合并任意批次，应按业务口径设计 Bitmap、HLL 等聚合方式。详见数据模型概述。
Sort Key（排序键）
SelectDB Cloud 根据排序键组织数据，并在排序键前缀上自动构建前缀索引。前缀索引长度最多为 36 字节，遇到 VARCHAR 列时会截断，后续列不再进入前缀索引。
- **结合高频过滤条件确定顺序。**关注经常用于等值或范围过滤的列及其组合，而不是把所有过滤列都加入 Key。
- **注意前缀长度与类型。**在符合查询模式的前提下，将
INT、BIGINT、DATE等定长列放在VARCHAR前，避免过早截断。 - **按需补充倒排索引。**对前缀索引难以覆盖的过滤列或文本检索列，可以使用倒排索引，同时评估写入和存储开销。
不要将“超出前缀范围”等同于列无法参与过滤。应结合实际扫描量和 Profile 判断访问路径是否有效。
分区
时间序列数据通常可以按日期或时间范围分区，以便裁剪查询范围及管理数据保留周期。使用 AUTO PARTITION BY RANGE(date_trunc(time_col, 'day')) 时，系统按写入数据自动创建相应分区；是否能裁剪分区，仍取决于查询条件。
让代表性 SQL 包含能够匹配分区列的时间范围，并使用 EXPLAIN 检查实际扫描分区。根据单日数据量、保留周期和常见查询跨度选择日、月等分区粒度，避免分区过多或过大。详见自动分区。
分桶
分桶决定一个分区内数据如何划分为 Tablet（数据分片），同时影响扫描并行度与调度开销。
- Random 分桶适合没有固定过滤键、希望减少数据倾斜的明细模型；它不支持按分桶键裁剪，且不适用于主键或聚合模型。
- Hash 分桶适合频繁按特定列过滤或关联的场景。选择分布较均匀的列，主键和聚合模型的分桶列还需满足 Key 列限制。
选择分桶数时，建议以以下原则作为初始参考，再通过业务负载验证：
| 原则 | 说明 |
|---|---|
| 优先考虑单 Tablet 数据量 | 通常以压缩后约 1–20 GB 为参考，主键模型建议不超过约 10 GB；小规模验证不必为达到下限额外放大数据。 |
| 平衡并行度与调度开销 | 分桶过少可能限制并行度，过多则增加小 Tablet、元数据和调度成本。 |
| 结合目标计算集群 | 节点数量可作为分布与并行度的参考，但不应将某次节点数的整数倍作为唯一选桶依据；云上集群可能伸缩，同一仓库也可能有多个集群。 |
| 同时考虑分区数 | 单分区通常不需要超过 128 个桶。关注被查询分区的总 Tablet 数，以及每个分区的数据量。 |
| 通过实测调整 | 使用 SHOW TABLETS FROM table_name 查看大小分布，结合查询扫描量、CPU 利用率和耗时判断。 |
示例中的固定桶数只是起点，不是所有仓库规模的推荐值。修改集群规格不会自动重新定义已有分区的桶数，分桶设计与后续调整方式参见数据分桶。
建表模板
以下模板用于日志、CDC 和指标聚合的起步验证。先创建独立的测试数据库，再按顺序执行 SQL。已有同名对象时，使用新的名称并同步替换后续语句。
CREATE DATABASE poc_demo;
USE poc_demo;
模板统一使用 10 个桶作为示例，请根据前述原则调整；不要直接将这一配置作为生产结论。后续查询应在 poc_demo 数据库中执行。
日志与事件分析
适合追加写入的应用日志、行为事件和传感器数据。保留明细行，按天自动分区，并为消息内容创建文本倒排索引。
CREATE TABLE app_logs (
log_time DATETIME NOT NULL,
log_level VARCHAR(10),
service_name VARCHAR(50),
trace_id VARCHAR(64),
message STRING,
INDEX idx_message (message) USING INVERTED
PROPERTIES("parser" = "unicode")
)
DUPLICATE KEY(log_time)
AUTO PARTITION BY RANGE(date_trunc(`log_time`, 'day'))
()
DISTRIBUTED BY RANDOM BUCKETS 10;
导入具有代表性的日志后，检查分区和数据分布，并使用实际关键词验证检索结果。自动分区需要在写入数据后检查。
SHOW PARTITIONS FROM app_logs;
SHOW TABLETS FROM app_logs;
实时看板与主键更新（CDC）
适合用户资料、订单最新状态等按主键更新的数据。先确认业务主键，再验证同一主键多次变更、乱序到达和重试时的结果。
CREATE TABLE user_profiles (
user_id BIGINT NOT NULL,
username VARCHAR(50),
email VARCHAR(100),
status TINYINT,
updated_at DATETIME
)
UNIQUE KEY(user_id)
DISTRIBUTED BY HASH(user_id) BUCKETS 10;
导入测试数据后，以下查询应不返回重复主键；还需要将各用户的最终状态与源系统比对。updated_at 只是普通列，不会仅因出现在表中就自动决定更新顺序。
SELECT user_id, COUNT(*) AS cnt
FROM user_profiles
GROUP BY user_id
HAVING COUNT(*) > 1;
SHOW TABLETS FROM user_profiles;
指标聚合
适合按日期、站点等固定维度汇总可累加的指标。以下示例统计访问量和错误数，重复导入同一批数据会重复累加，需要由导入链路保证正确的重试语义。
CREATE TABLE site_metrics (
dt DATE NOT NULL,
site_id INT NOT NULL,
pv BIGINT SUM DEFAULT '0',
error_count BIGINT SUM DEFAULT '0'
)
AGGREGATE KEY(dt, site_id)
AUTO PARTITION BY RANGE(date_trunc(`dt`, 'day'))
()
DISTRIBUTED BY HASH(site_id) BUCKETS 10;
导入包含相同日期和站点的多条记录后，比对源数据的汇总值，并检查带时间条件的查询计划。
SELECT dt, site_id, SUM(pv) AS pv, SUM(error_count) AS error_count
FROM site_metrics
GROUP BY dt, site_id
ORDER BY dt DESC, site_id
LIMIT 10;
EXPLAIN SELECT * FROM site_metrics WHERE dt = '2026-10-01';
将日期替换为已导入数据的实际日期，避免用扫描空分区的结果评估性能。
数据导入
选择符合生产接入方式的导入路径，同时记录吞吐、数据可见延迟和正确性，不能只以客户端提交成功判断整批数据已可查询。
- **批量文件优先使用批量导入方式。**本地文件可使用 Stream Load，对象存储文件可按场景使用 Broker Load或
INSERT INTO SELECT。少量INSERT INTO ... VALUES适合功能验证，不适合作为大批量文件导入的性能基准。 - **先在客户端合并高频小批次。**频繁的小批量写入容易造成版本堆积和 Compaction 压力；适用时评估 Group Commit，并确认同步与异步模式的可见性及重试语义。
- **合理拆分大任务。**按文件或数据范围组织可重试批次，记录批次标识和完成状态，降低长任务失败后的重试代价。
- **按生产方式验证增量链路。**Kafka 持续接入可使用 Routine Load；数据库 CDC 可结合 Flink 等同步工具，验证更新、删除、积压与恢复。
- Random 分桶的明细表可评估单 Tablet 导入。
load_to_single_tablet可减少小批量写入的写放大，但需要结合批次规模、并发和数据分布验证效果。
导入检查应与所用方式一致：Broker Load 等异步任务查看对应作业状态，Stream Load 检查返回状态与总行数、成功行数和过滤行数，Routine Load 检查任务状态及消费进度。不要把 SHOW LOAD 当作所有导入方式的统一状态入口。
查询调优
先建立可重复的基线
使用固定的数据范围、SQL 参数、集群资源和并发运行代表性查询。分别测量单条查询与混合并发负载，并记录后台导入任务；“空闲集群上的单次最快耗时”不能代表持续导入时的服务表现。
同时记录客户端端到端耗时和服务端执行耗时，尤其是在跨地域访问或返回大量结果时。使用 SQL 编辑器测试时，注意默认结果行数限制；如果生产任务需要完整结果，应使用一致的结果获取方式。
检查分区、分桶与数据倾斜
先通过 EXPLAIN 确认过滤条件和扫描范围，再用 Tablet 大小分布及 Profile 判断是否存在倾斜或扫描过量。以已导入日志为例：
EXPLAIN
SELECT service_name, COUNT(*) AS error_count
FROM app_logs
WHERE log_time >= '2026-10-01 00:00:00'
AND log_time < '2026-10-02 00:00:00'
AND log_level = 'ERROR'
GROUP BY service_name;
SHOW TABLETS FROM app_logs;
将时间范围替换为实际测试数据的范围。分桶过少可能限制并行度，分桶过多则增加调度开销；Hash 分桶出现明显倾斜时，应重新评估分桶键。明细模型可以比较 Random 分桶，主键和聚合模型则需在符合模型要求的 Key 列中选择。
验证索引的实际效果
排序键前缀、倒排索引和分区分桶裁剪解决的问题不同。结合高频查询选择优化方式，不要仅因建立了索引就认定查询已获益。
EXPLAIN 用于检查计划、谓词和扫描范围，索引过滤效果还应结合实际 Profile 中的扫描行数、过滤行数和耗时判断。新增索引后，确认历史数据的索引构建状态，并评估对写入吞吐和存储的影响。
使用查询 Profile 定位瓶颈
在用于诊断的会话中启用 Profile，然后运行实际待分析的查询：
SET enable_profile = true;
使用 SQL 编辑器时，可从查询记录或详情中打开查询 Profile并下载结果。重点检查扫描、过滤、关联、聚合、数据交换和等待时间，同时对照集群 CPU、内存和缓存指标。需要时结合查询 Profile 分析指南理解算子指标，控制台操作参见 SQL 编辑器。
Profile 采集也有开销。诊断时保持采集设置一致，容量压测与问题诊断可以分开进行，避免采集设置变化干扰对比。
数据湖查询
POC 涉及通过外部 Catalog 查询 Hive、Iceberg、Paimon 等数据时，需要额外记录远端存储、元数据服务、文件布局、网络路径和缓存状态。这些条件都可能影响结果。
确保分区裁剪生效
在 WHERE 条件中包含与分区列匹配的过滤条件，并通过 EXPLAIN 检查实际扫描分区及文件范围。不同 Catalog 和内核版本的计划字段可能不同，应结合对应说明和 Profile 判断，不要仅凭某个数字或字段名称推断裁剪结果。
如果扫描范围远大于业务要求，检查分区字段类型、条件转换和时间范围是否一致。用一个实际包含数据的分区先验证结果，再扩大测试范围。
分别评估冷缓存与热缓存
远端文件的读取可能受对象存储或 HDFS 的 I/O 和网络延迟影响。数据缓存可以在本地磁盘保留热点数据，重复查询可能从中受益，但第二次运行并不一定已经完整命中缓存。
- 记录测试集群的缓存容量、查询是否启用文件缓存、是否做过预热，以及执行前后的缓存命中指标。
- 在支持且底层缓存已配置的环境中，可通过会话变量
enable_file_cache评估外表文件缓存，具体参见数据缓存。SelectDB Cloud 的底层配置由服务管理，不需要按自建部署步骤直接修改be.conf或重启节点；涉及服务端配置时联系技术支持确认。 - 分别保存首次读取与重复读取的结果，使用 Profile 中的
BytesScannedFromCache、BytesScannedFromRemote等指标确认实际读取来源。 - 对经常查询新数据或跨大范围历史数据的业务，保留冷缓存或混合命中结果，不要只用热缓存结果作结论。
集群扩缩容、切换执行集群及数据淘汰都可能改变缓存状态。控制台缓存预热与外表 WARM UP SELECT 的适用范围、版本要求并不完全相同，应按所选功能文档确认，不能将任一预热操作等同于所有湖表数据已缓存。
治理小文件
大量小文件可能产生过多 Split（扫描任务分片），增加元数据访问、查询规划和内存开销。先观察文件大小分布与 Split 数量，再定位瓶颈。
优先在源端执行适合表格式的文件合并或 Compaction。文件目标大小需结合格式、压缩、分区粒度和查询模式确定，可从百 MB 级文件进行评估，不要把所有文件都大于 128 MB 作为硬性要求。
对于内核支持的 max_file_split_num 等扫描参数，按数据湖查询调优确认含义后评估。参数调整不能代替源端文件治理，也不能保证消除所有内存溢出问题。
使用 Profile 区分 I/O 与计算开销
湖上查询可能受文件读取、元数据规划或算子计算影响。重点观察：
| 指标或现象 | 排查方向 |
|---|---|
| 扫描文件、Split 和数据量偏大 | 分区裁剪、小文件、查询范围与文件布局。 |
| 远端读取量大、缓存命中低 | 热点范围是否超出缓存、是否启用缓存、是否更换集群或发生淘汰。 |
MergedBytes 明显大于 RequestBytes | 可能存在 I/O 合并导致的读放大，结合查询读取模式评估。 |
| 关联、聚合或数据交换耗时高 | 数据倾斜、关联策略、计算资源和算子内存。 |
一次只调整一个参数或设计因素，使用相同查询和缓存条件复测。更多说明参见数据湖查询调优。
记录与比较结果
为每条代表性 SQL 和每条导入链路保存足够信息，使其他人能够复测，并区分数据设计与资源变化带来的收益。
| 类别 | 建议记录 |
|---|---|
| 环境 | 内核版本、SaaS/BYOC、云厂商、地域、仓库与集群标识、vCPU、内存、缓存容量、计费方式及伸缩策略。 |
| 数据 | 数据量与压缩后大小、表结构、分区和桶数、索引、数据分布、外部文件与元数据情况。 |
| 导入 | 工具与版本、批次大小、并发、任务标识、吞吐、过滤或失败行数、可见延迟及重试结果。 |
| 查询 | SQL 与参数、客户端、并发、后台负载、端到端与服务端耗时、延迟分位数、错误率和结果校验。 |
| 诊断 | 查询标识、EXPLAIN、Profile、Tablet 大小分布、缓存状态、监控与查询审计记录。 |
| 成本 | 测试时间范围、计算及缓存配置变化、存储用量、达到目标负载所需的资源与费用。 |
每轮只改变一个因素，例如桶数、索引、SQL、集群规格或缓存条件。保存原始基线及每轮结果，避免同时修改多个配置后无法判断收益来源。
最终按最初的验收标准逐项说明：已满足的要求、未满足的要求、适用条件和上线前的后续工作。测试结束后，通过资源用量及组织的账单核对费用，暂停不再使用且支持启停的集群；暂停后缓存与持久化存储等仍可能计费，参见资源用量与费用。
常见问题与排查
| 问题 | 建议排查顺序 |
|---|---|
| 客户端无法连接或查询无法启动 | 检查目标仓库与计算集群状态、地址端口、网络与白名单、数据库凭据及权限。SaaS 免费试用集群暂停后需要手动启动，不支持自动恢复。 |
建表提示 Tablet count should be greater than 0 | 检查 DDL 的分桶声明，使用符合所选模型的分布方式及有效桶数；保留完整报错与 DDL 继续定位。 |
| 查询比预期慢 | 核对执行集群和并发，检查分区裁剪、Tablet 倾斜、索引过滤，再通过 Profile 区分扫描、计算和等待。 |
| 湖上查询内存不足 | 检查元数据、文件与 Split 数量，以及关联、聚合等算子的内存；按瓶颈治理小文件、减少扫描或调整资源。 |
| 持续写入后查询变慢 | 检查写入批次、频率、版本积压与 Compaction，评估客户端合批及 Group Commit，并复核更新和重试语义。 |
| 重复运行快，但首次查询慢 | 对比缓存读取来源、远端 I/O 与元数据开销，分别报告冷热状态，不以最快一次耗时代表全部业务。 |
| 使用 Profile 后耗时发生变化 | 核对采集设置和后台负载，分别进行诊断与容量测试，并在相同设置下复测。 |
POC 所需时间取决于数据准备、接入方式、业务复杂度和验收范围。先完成正确性验证与基线测试，再为调优、并发测试及重复测量预留时间。需要技术支持协助时，提供版本、集群配置、DDL、测试 SQL、脱敏后的数据特征、查询标识和诊断结果，便于复现问题。