create-dwy 0.12.2 → 0.13.0

package/templates/claude-global/skills//346/225/260/346/215/256/345/272/223/dwy-dolphindb/references/digest/data-ingest.md

@@ -0,0 +1,142 @@
+---
+topic: data-ingest
+source_files:
+  - official/db_distr_comp/db_oper/data_import_method.md
+  - official/funcs/l/loadTextEx.md
+  - official/funcs/l/loadText.md
+  - official/funcs/t/textChunkDS.md
+  - official/pydoc/BasicOperations/table_append.md
+---
+
+# 数据导入
+
+DolphinDB 数据导入选型与高性能落库指南。覆盖 CSV / Parquet / Python DataFrame / MySQL / Kafka / HDF5 六大数据源。
+
+## 30 秒导入选型
+
+| 数据源 | 推荐方式 | 关键函数 / 接口 | 适用场景 |
+|---|---|---|---|
+| CSV 小文件（< 1GB） | 单次落库 | `loadTextEx` | 一次性导入，直接落 DFS 表 |
+| CSV 大文件（> 1GB） | 切片 + map-reduce | `textChunkDS` + `mr` | 内存有限、需多线程并行 |
+| CSV 海量小文件 | 批量合并 | `loadText` + `unionAll` + `append!` | 单文件小、数量多（如一股票一文件） |
+| CSV 内存表 | 单/多线程读 | `loadText` / `ploadText` | 仅做内存分析，不落库；`ploadText` 适合 16MB+ |
+| Parquet | parquet 插件 | `parquet::loadParquet` | 跨平台列式数据 |
+| HDF5 | hdf5 插件 | `hdf5::loadHDF5` | 科研数据、量化历史行情 |
+| Python DataFrame | API + appender | `PartitionedTableAppender` / `tableAppender` | Python 端批量写入 |
+| MySQL | mysql / odbc 插件 | `mysql::load` / `odbc::query` | 关系型库迁移 |
+| Kafka | kafka 插件 | `kafka::subscribe` → 流表 | 实时行情、日志 |
+| 二进制 | 内置函数 | `loadRecord` / `readRecord!` | 自定义二进制协议 |
+| JSON | 内置函数 | `fromJson` / `fromStdJson` | 配置、嵌套对象 |
+
+## 大文件导入 4 步流程
+
+1. **估行数 / 抽样**：`wc -l file.csv`；`extractTextSchema(path)` 推断列类型
+2. **切片**：`textChunkDS(file, chunkSize)`，chunkSize 取 256 ~ 1024 MB（参数范围 1 ~ 2048 MB）
+3. **多线程入库**：`mr(ds, append!{pt}, , , parallel=false)` — **同分区禁并发写**
+4. **批量上限**：单次 append / appender 不超过 **50 万行（500K）**，超过需切 batch
+
+```dolphindb
+ds = textChunkDS("/data/trades.csv", 500)   // 500 MB/块
+mr(ds, append!{pt}, , , false)              // parallel=false 必填
+```
+
+## loadTextEx 关键参数
+
+```
+loadTextEx(dbHandle, tableName, partitionColumns, filename,
+           [delimiter], [schema], [skipRows], [transform],
+           [sortColumns], [atomic], [arrayDelimiter], [containHeader], [arrayMarker])
+```
+
+| 参数 | 作用 | 常见用法 |
+|---|---|---|
+| `schema` | 列名 / 类型 / 时间 format / 列下标 col | `extractTextSchema(path)` 再 `update` 改 type / format |
+| `delimiter` | 列分隔符（默认 `,`） | TSV 用 `\t`，可多字符 |
+| `partitionColumns` | 分区列 | 必填；组合分区传向量 `` `date`ID `` |
+| `sortColumns` | 分区内排序列（仅 TSDB） | 高频查询字段靠前；最后一列须时间 / 整型；每分区 sort key ≤ 2000 |
+| `transform` | 入库前一元函数 | `nullFill!{,0}` 填空、`mytrans{,sym}` 加列 / 调列序 |
+| `skipRows` | 跳过文件头行数 | 0 ~ 1024 |
+| `atomic` | 单文件是否原子事务 | 文件 > Cache Engine 必须 `false`，否则事务卡死 |
+| `containHeader` | 是否含标题行 | 默认自动判断 |
+| `arrayDelimiter` | 数组向量分隔符 | 配合 `schema.type = "DOUBLE[]"` 使用 |
+| `encoding` | 源文件编码 | **必须 UTF-8**；GBK 须先转码 |
+
+注：列名非中英文/数字/下划线会被自动改写（如 `1_test` → `c1_test`，`test-a!` → `test_a_`）。
+
+## 写入性能基线
+
+| 写入方式 | 吞吐量级 | 适用 | 备注 |
+|---|---|---|---|
+| `loadTextEx` (CSV → DFS) | 100 ~ 300 万行/秒 | 离线全量入库 | 单线程，分批落盘，内存占用低 |
+| `textChunkDS` + `mr` | 200 ~ 500 万行/秒 | 大文件多线程 | `parallel=false`，靠多分区并行 |
+| `PartitionedTableAppender` (Python) | 100 ~ 200 万行/秒 | Python 批量回填 | 连接池 + 分区路由，最高效 |
+| `tableAppender` (Python) | 50 ~ 100 万行/秒 | Python 单连接追加 | 一般小数据量 / 流式追加 |
+| `tableInsert` / `append!` | 50 ~ 100 万行/秒 | 实时流写入 | 单次建议 1 ~ 50 万行 |
+| 单行 `insert into` | < 1 万行/秒 | 调试 | 生产禁用 |
+
+## 典型导入 3 例
+
+### 例 1. loadTextEx：CSV → DFS（含 transform 加列 + sortColumns）
+
+```dolphindb
+db = database("dfs://stock_data", VALUE, 2000.01M..2025.12M, , "TSDB")
+schema = extractTextSchema("/data/sz000001.csv")
+update schema set type="DATETIME" where name="tradetime"
+
+def mytrans(mutable t, sym, colNames) {
+    t1 = select sym, * from t
+    t1.reorderColumns!(colNames)
+    return t1
+}
+loadTextEx(db, `pt, `tradetime, "/data/sz000001.csv",
+           schema=schema,
+           transform=mytrans{,"sz000001", colNames},
+           sortColumns=`sym`tradetime)
+```
+
+### 例 2. textChunkDS + mr：3GB 大文件多线程
+
+```dolphindb
+db = database("dfs://db1", VALUE, `IBM`MSFT`GOOG`AMZN`TSLA)
+pt = db.createPartitionedTable(trades, `pt, `sym)
+ds = textChunkDS("/data/trades.txt", 500)   // 500MB/块
+mr(ds, append!{pt}, , , false)              // parallel 必为 false
+```
+
+### 例 3. Python pool + PartitionedTableAppender
+
+```python
+import dolphindb as ddb
+pool = ddb.DBConnectionPool("localhost", 8848, 8, "admin", "123456")
+appender = ddb.PartitionedTableAppender(
+    dbPath="dfs://stock", tableName="pt",
+    partitionColName="date", dbConnectionPool=pool)
+# uint 列须先转换；NaN 自动转 NULL
+df["qty"] = df["qty"].astype("int64")
+appender.append(df)   # 单批 ≤ 500K 行
+```
+
+## 常见陷阱
+
+| 陷阱 | 表现 | 解决 |
+|---|---|---|
+| 单批超 50 万行 | append 卡顿 / OOM | 切分 batch，单次 ≤ 500K |
+| 文件 GBK 编码 | 中文乱码 | 先 `iconv -f GBK -t UTF-8` 转码 |
+| `mr` 用 `parallel=true` | 同分区并发写抛异常 | 必须 `parallel=false` |
+| DataFrame 含 uint | API 写入类型不匹配 | `.astype("int64")` 显式转换 |
+| DataFrame 含 NaN | 期望写 NULL | 数值列自动转；object 列须 `.where(pd.notna(df), None)` |
+| `loadText` 单线程慢 | 16MB+ 文件耗时 | 改用 `ploadText` 多核并行 |
+| 时间列被识别为 LONG | 形如 `20190623145457` | schema 指定 `type=DATETIME` + `format="yyyyMMddHHmmss"` |
+| `atomic=true` + 大文件 | 事务卡死（既不能 commit 也不能 rollback） | 文件超 Cache Engine 必须 `atomic=false` |
+| 数组向量列识别失败 | 默认按字符串读 | schema 改 `type="DOUBLE[]"` + `arrayDelimiter` |
+| 海量小文件逐个导 | 效率极低 | 批量 `each(loadText, files).unionAll(false)` 后 append |
+| schema 自动推断错列类型 | 抽样不准 | 显式传 `schema`，类型 / format 强制指定 |
+| 列名以数字开头 | 被改名为 `c1_xxx` | 数据文件预处理或接受自动改名 |
+
+## 下钻原文
+
+- 导入方法总览：`/Users/chances/WebstormProjects/dwy-shared/claude-cli/templates/claude-global/skills/数据库/dwy-dolphindb/references/official/db_distr_comp/db_oper/data_import_method.md`
+- loadTextEx 全参 / transform / sortColumns 示例：`/Users/chances/WebstormProjects/dwy-shared/claude-cli/templates/claude-global/skills/数据库/dwy-dolphindb/references/official/funcs/l/loadTextEx.md`
+- loadText / schema / arrayMarker / 批量小文件：`/Users/chances/WebstormProjects/dwy-shared/claude-cli/templates/claude-global/skills/数据库/dwy-dolphindb/references/official/funcs/l/loadText.md`
+- textChunkDS + mr 大文件切片：`/Users/chances/WebstormProjects/dwy-shared/claude-cli/templates/claude-global/skills/数据库/dwy-dolphindb/references/official/funcs/t/textChunkDS.md`
+- Python API 追加（tableAppender / PartitionedTableAppender）：`/Users/chances/WebstormProjects/dwy-shared/claude-cli/templates/claude-global/skills/数据库/dwy-dolphindb/references/official/pydoc/BasicOperations/table_append.md`

package/templates/claude-global/skills//346/225/260/346/215/256/345/272/223/dwy-dolphindb/references/digest/deploy-ops.md

@@ -0,0 +1,133 @@
+---
+title: 部署与运维
+category: digest
+covers: [deploy, sys_man, funcs/b/backup, funcs/r/restore, cluster_async_replc]
+---
+
+# 部署与运维
+
+## 何时用
+
+- 选型阶段：决定单节点 / 单机集群 / 多机集群 / 多机 HA 集群
+- 上线前：规划节点角色与端口、配置 HA、制定备份策略
+- 日常运维：扩容、升级、备份恢复、监控、异地容灾（异步复制）
+- 故障处置前：先看本文「错误操作禁忌表」，避免破坏元数据导致数据不可恢复
+
+## 部署形态对比
+
+| 形态 | 控制节点 | 数据节点 | 计算节点 | HA | 适用场景 |
+| --- | --- | --- | --- | --- | --- |
+| 单节点（standalone） | 不分离，全在一进程 | 同左 | — | 无 | 开发、研究、小规模生产 |
+| 单机集群（single-machine cluster） | 1 | N（同机） | 0~N | 数据多副本可有 | 单机但需扩展节点、本地多副本 |
+| 多机集群（multi-machine cluster） | 1 | N（跨机） | 0~N | 数据多副本可有 | 一般生产 |
+| 多机 HA 集群 | 3+（Raft 仲裁） | N（跨机） | 0~N | 元数据 + 数据 + API 三层 HA | 企业级关键业务 |
+
+> 单节点不支持扩展和高可用，集群模式可扩展并支持 HA。
+
+## 节点角色
+
+| 角色 | 数量约束 | 职责 |
+| --- | --- | --- |
+| controller（控制节点） | 单集群 1 个；HA 集群 3+ | 收集 agent/data node 心跳；管理 DFS 元数据、事务日志；调度任务 |
+| agent（代理节点） | 每台物理机有且仅有 1 个 | 执行 controller 下发的 start/stop 命令，拉起/关停本机的 data node 和 compute node |
+| data node（数据节点） | 每机可多个 | 存储数据；同时承担查询、计算 |
+| compute node（计算节点） | 每机 0 ~ 多个 | 仅响应客户端查询/计算请求，不存储；实现存算分离 |
+
+> 计算节点用于把计算压力从 data node 上剥离。需要跨节点并行时，compute node 通过 controller 协调多 data node 拉数据。
+
+## 关键端口（默认）
+
+| 端口 | 用途 | 说明 |
+| --- | --- | --- |
+| 8848 | 单节点 / controller 监听端口（默认） | Web 管理工具、客户端连接同一端口 |
+| 8900+ | data node / agent / compute node 端口 | 由 `cluster.nodes` 配置文件分配 |
+
+> 多机部署时，所有节点之间需双向开通 TCP；防火墙限制是新人最常踩的坑（节点显示 isAlive=false）。
+
+## HA 配置要点（多机 HA 集群）
+
+- **控制节点**：至少 3 个（推荐 3 或 5），通过 Raft 协议选主，半数以上存活才可写元数据
+- **数据副本**：`dfsReplicationFactor=2` 起步（推荐 3），副本分布在不同物理机（`dfsReplicaReliabilityLevel=1` 强制跨节点）
+- **API HA**：客户端 / API SDK 配置多个控制节点地址列表，控制节点切主后客户端自动重连
+- **事务日志（redo log）**：所有 data node 必须开启 redo log，崩溃恢复依赖它
+
+## 备份恢复
+
+**严禁 cp 文件备份数据库**：DolphinDB 的 chunk 元数据由 controller 维护，直接拷贝数据目录会让元数据和数据不一致，集群级损坏不可逆。
+
+使用官方函数：
+
+| 函数 | 用途 | 关键参数 |
+| --- | --- | --- |
+| `backup(backupDir, dbPath\|sqlObj, force=false, parallel=false, snapshot=true)` | 按分区备份分布式表 | `force=true` 全量；`snapshot=true` 同步删除主库已删的分区 |
+| `backupDB(backupDir, dbPath)` | 按库备份 | 整库 |
+| `backupTable(backupDir, tableObj)` | 按表备份 | 单表 |
+| `restore(backupDir, dbPath, tableName, partition, force)` | 按分区恢复 | 支持指定分区子集恢复 |
+| `restoreDB / restoreTable` | 按库 / 按表恢复 | — |
+
+支持本地路径、AWS S3（路径以 `s3://` 开头，需 `preloadModules=plugins::awss3` + S3 凭证配置）。Linux 下可通过 `keyPath` 参数指定加密密钥。
+
+## 错误操作禁忌表
+
+| 禁忌操作 | 后果 | 正确做法 |
+| --- | --- | --- |
+| `cp -r /storage/CHUNKS/...` 备份数据目录 | 元数据与数据不一致，恢复时分区丢失 | `backup()` / `backupDB()` |
+| 手工删 redo log（`/log/*.redo`） | 崩溃恢复失败，节点起不来 | 等节点正常关闭后日志自动回收 |
+| `kill -9` 强杀 data node | 进行中事务可能丢失或元数据不一致 | Web 管理工具 stopDataNode；脚本 `stopDataNode` 函数 |
+| 不停服改 hostname / ip | controller 心跳认不出节点，集群分裂 | 停集群 → 改 host → 改 `cluster.nodes` → 启 |
+| 直接删 DFS 表对应的目录 | 元数据残留，无法 drop 也无法重建同名表 | `dropTable / dropDatabase / dropPartition` 函数 |
+| 控制节点只部署 2 个 | Raft 无法选主，故障即失去元数据写能力 | HA 控制节点 3 / 5 个奇数 |
+| 单副本 + 单机宕机 | 数据永久丢失 | `dfsReplicationFactor>=2`，副本跨机 |
+| 异步复制中跳过任务但不查原因 | 主从永久不一致 | 先 `getSlaveReplicationStatus` 看失败原因，处理后 `startClusterReplication` 重启；最后才用 `skipClusterReplicationTask` |
+
+## 升级流程（标准滚动）
+
+1. 备份：`backup()` 全量备份关键库 + 导出配置文件（`cluster.cfg / cluster.nodes / agent.cfg`）
+2. 停服：Web 管理工具或脚本 `stopDataNode` 优雅停 data node，再停 controller，最后停 agent
+3. 替换：解压新版 `server/` 目录，**保留**旧的 `dolphindb.lic`、`config/`、`data/`、`log/`
+4. 配置：对比新版 `cluster.cfg.example` 是否有新增项，按需合入
+5. 启动：先 agent → controller → 集群管理页面启动 data node / compute node
+6. 校验：
+   - Web 集群管理页面所有节点 `isAlive=true`
+   - 跑一遍 smoke test：`select count(*) from loadTable("dfs://...","...")`、写入测试、备份还原测试
+   - 检查 `log/*.log` 无 ERROR
+
+> HA 集群滚动升级：3 个 controller 逐一升级，每次升级前确认其余 2 个健康。
+
+## 监控告警信号清单
+
+| 信号源 | 关注指标 | 告警阈值（建议） |
+| --- | --- | --- |
+| `getClusterPerf()` | 各节点 CPU / 内存 / 磁盘 / 网络 | CPU > 80% 持续 5min；内存 > 90% |
+| `getClusterChunksStatus()` | chunk 副本数、状态 | 副本数 < 配置值；存在 `RECOVERING` 持续 > 30min |
+| `getRecoveryTaskStatus()` | 恢复任务队列长度 | 持续增长不下降 |
+| `getJobStat()` / `getConsoleJobs()` | 长跑作业 | 单作业 > 业务 SLA |
+| log 文件 | ERROR / FATAL 关键字 | 任意 ERROR 立即告警 |
+| `getSlaveReplicationStatus()` | 异步复制 lag | lag > 业务容忍上限（如 5 分钟）|
+| Raft leader 切换日志 | 频繁切主 | 1 小时内 ≥ 2 次 |
+
+## 异步复制（异地容灾）
+
+- 用途：主集群 → 从集群单向异步同步，主集群挂了从集群可继续提供读
+- 启用：主集群数据节点调 `setDatabaseForClusterReplication("dfs://xxx", true)`，每次一个库
+- 工作流：主集群提交事务后，把已完成事务的元数据放入发送队列；从集群按 taskID 偏移量拉取并执行
+- 仅支持分布式表（不支持内存表、本地磁盘表）
+- 不支持权限管理、分级存储、存储引擎修改等非 DDL/DML
+- 故障处理：从集群多次失败导致中断 → `getSlaveReplicationStatus` 查原因 → 处理后 `startClusterReplication` 重启 → 实在过不去再 `skipClusterReplicationTask` 跳过
+- 停止：主从都调 `stopClusterReplication()`；停单库用 `setDatabaseForClusterReplication("dfs://xxx", false)`
+- 注意：从集群新增节点后，哈希算法仍基于原节点数映射，新节点不会分到任务
+
+## 下钻原文路径
+
+- 部署总览：`official/deploy/deploy_intro.md`
+- 单节点部署：`official/tutorials/standalone_server.md`
+- 单机集群部署：`official/tutorials/single_machine_cluster_deploy.md`
+- 多机集群部署：`official/tutorials/multi_machine_cluster_deployment.md`
+- 高可用集群部署：`official/tutorials/ha_cluster_deployment.md`
+- 集群管理（扩容 / 升级）：`official/sys_man/cluster_manage.md`
+- 多集群管理：`official/sys_man/multi_cluster_management.md`
+- 异步复制：`official/sys_man/cluster_async_replc.md`
+- 备份恢复函数：`official/funcs/b/backup.md`、`backupDB.md`、`backupTable.md`、`backupsettings.md`
+- 恢复函数：`official/funcs/r/restore.md`、`restoreDB.md`、`restoreTable.md`、`restoresettings.md`
+- License 指纹：`official/deploy/license_fingerprint_collection.md`
+- 错误码：`official/error_codes/`

package/templates/claude-global/skills//346/225/260/346/215/256/345/272/223/dwy-dolphindb/references/digest/engines.md

@@ -0,0 +1,102 @@
+---
+topic: engines
+source_files:
+  - official/db_distr_comp/db/tsdb.md
+  - official/db_distr_comp/db/olap.md
+  - official/db_distr_comp/db/pkey_engine.md
+  - official/db_distr_comp/db/imoltp.md
+  - official/db_distr_comp/db/vectordb.md
+generated_at: 2026-05-19
+---
+
+# DolphinDB 5 大存储引擎选型
+
+## 何时用此主题
+
+用户问"该用 TSDB 还是 OLAP"、"PKEY 能不能改主键"、"VECTORDB 性能如何"、"行情数据用什么引擎"、"主键 CDC 同步进 DolphinDB 怎么选" 等引擎选型问题时进来。
+
+## 核心要点
+
+- **OLAP / TSDB / PKEY / VECTORDB 都是 DFS 分布式引擎**，建库时通过 `engine='TSDB'|'OLAP'|'PKEY'` 指定；VECTORDB 是 TSDB 之上的索引能力，仍设 `engine="TSDB"`。
+- **IMOLTP 是单节点纯内存引擎**，库路径必须以 `oltp://` 开头，须在配置文件设 `enableIMOLTPEngine=true`，且当前版本不支持分区。
+- **TSDB 必填 `sortColumns`**（最后一列必须是 INTEGER 或 TEMPORAL 类型），可选 `keepDuplicates`（ALL/LAST/FIRST）；PKEY 必填 `primaryKey`，可选 `indexes`（仅支持 bloomfilter）。
+- **TSDB 的去重策略影响更新代价**：`keepDuplicates=LAST` 走追加更新最高效；`ALL/FIRST` 要全分区读改写。
+- **主键唯一性 + 实时更新只有 PKEY 能做**：TSDB LAST 能"查询不返回重复行"但磁盘有冗余且无非主键索引；OLAP 不支持去重。
+- **TSDB 单分区推荐 400MB–1GB（压缩前），`sortColumns` 不超过 4 列，单分区 sortKey 组合数建议 < 2000**。
+
+## 引擎横向对比
+
+| 引擎 | 存储模式 | 主键/索引 | 更新支持 | 典型场景 | 关键配置 |
+|---|---|---|---|---|---|
+| OLAP | DFS 列存（顺序追加，单列单文件） | 无主键，无索引 | 支持 update/delete，但按分区全量读改写，代价大 | 全表/全分区批量扫描分析（如全市场交易量统计） | `OLAPCacheEngineSize`、`compressMethods` |
+| TSDB | DFS 列存 + LSM-Tree + sortKey 索引 + zonemap | `sortColumns`（最后一列 INTEGER/TEMPORAL，前 n-1 列作 sortKey） | LAST 追加更新高效；ALL/FIRST 按分区重写 | 时序点查（行情/IoT/宽表/array vector/BLOB） | `sortColumns`、`keepDuplicates`、`sortKeyMappingFunction`、`TSDBCacheEngineSize` |
+| PKEY | DFS 列存 + LSM-Tree + Merge-on-Write + delete bitmap | `primaryKey`（必含分区列），可加 `indexes={"col":"bloomfilter"}`（zonemap 自动建） | 近实时更新，主键唯一性保证 | OLTP CDC 同步入仓、Ad-Hoc 查询、需要主键唯一约束的场景 | `primaryKey`、`indexes`、`PKEYCacheEngineSize`、`PKEYDeleteBitmapUpdateThreshold` |
+| IMOLTP | 单机内存行存 + B+ 树（OLC 算法） + WAL/Checkpoint | `primaryKey` 必填，可加多个 `secondaryKey`（unique/non-unique） | 完整 ACID 跨表事务（`transaction` 块、commit/rollback） | 高并发 OLTP（订单/交易系统），数据量受单机内存限制 | `enableIMOLTPEngine=true`、库前缀 `oltp://`、`createIMOLTPTable` |
+| VECTORDB | TSDB 之上对 `FLOAT[]` 列建 Faiss 向量索引（每个 Level File 一份） | 继承 TSDB 的 `sortColumns`；额外 `indexes={"col":"vectorindex(type=..., dim=...)"}` | 同 TSDB，且 `keepDuplicates=ALL` 强制 | 向量相似度检索（RAG/推荐/图搜） | 索引类型 Flat/PQ/IVF/IVFPQ/HNSW；查询走 `rowEuclidean + ORDER BY ASC + LIMIT` |
+
+## 选型决策树
+
+```
+1. 单机、数据量 <= 内存、需要完整 ACID 跨表事务？
+   → IMOLTP
+2. 需要向量相似度检索（RAG/嵌入/相似图）？
+   → VECTORDB（TSDB engine + vectorindex）
+3. 需要主键唯一性 + 实时更新 + 非主键列索引（OLTP CDC 入仓）？
+   → PKEY
+4. 时序数据点查 / 宽表 / array vector / 频繁按 sortKey 过滤？
+   → TSDB
+5. 仅做大批量顺序写 + 全分区扫描分析，不需要去重和点查？
+   → OLAP
+```
+
+## 典型用法
+
+TSDB 建库建表（行情场景，按日期 VALUE + 股票 HASH 组合分区）：
+
+```dolphindb
+db1 = database(, VALUE, 2024.01.01..2024.12.31)
+db2 = database(, HASH, [SYMBOL, 50])
+db  = database(directory="dfs://stock_tsdb", partitionType=COMPO,
+               partitionScheme=[db1, db2], engine="TSDB")
+
+tb = table(1:0, `SecurityID`TradeDate`TradeTime`Price`Volume,
+                [SYMBOL, DATE, TIME, DOUBLE, INT])
+
+db.createPartitionedTable(table=tb, tableName=`trade,
+    partitionColumns=`TradeDate`SecurityID,
+    sortColumns=`SecurityID`TradeTime,
+    keepDuplicates=LAST)
+```
+
+OLAP 建库建表（仅做批量扫描分析，无去重需求）：
+
+```dolphindb
+db = database(directory="dfs://stock_olap", partitionType=VALUE,
+              partitionScheme=2024.01.01..2024.12.31, engine="OLAP")
+
+tb = table(1:0, `SecurityID`TradeDate`Price`Volume,
+                [SYMBOL, DATE, DOUBLE, INT])
+
+db.createPartitionedTable(table=tb, tableName=`trade,
+                          partitionColumns=`TradeDate)
+```
+
+## 常见陷阱
+
+- **TSDB sortKey 当主键用导致库膨胀**：把唯一约束设为 `sortColumns`，每个 sortKey 只对应几行，元数据膨胀，极端场景数据库放大 50 倍。需主键唯一性请改用 PKEY。
+- **TSDB `keepDuplicates=ALL/FIRST` 的更新踩坑**：每次更新按分区全量读取到内存改写，分区过大可能 OOM；高频更新场景必须用 `LAST`。
+- **TSDB 整分区扫描不如 OLAP**：TSDB 增加了索引和 Cache Engine 排序开销，整列扫描场景 OLAP 更快。
+- **PKEY 写入吞吐量上限低于 TSDB**：吞吐量增长后 PKEY 写入耗时上升更快，纯高吞吐写入用 TSDB。
+- **VECTORDB Cache Engine 中数据无索引**：刚写入的向量在 Cache Engine 中只能穷举搜索，需 `flushTSDBCache()` 强制落盘后才走向量索引。
+- **VECTORDB 查询限制多**：必须 `ORDER BY rowEuclidean(...) ASC`、必须 `LIMIT`、不能 JOIN、`WHERE` 不能用 `sortColumns` 中的列、不能 `GROUP BY/HAVING`。
+- **IMOLTP 当前版本不支持分区也不支持 DDL 事务**：`partitionType` / `partitionScheme` 只为接口一致性保留，无实际作用；`transaction` 块内仅支持 DML。
+- **PKEY 分区列影响写入性能**：递增 ID 或带日期的唯一 ID 直接当分区列会让写入分散到大量分区，需用分区转换函数（如 `myPartitionFunc(id, 6, 8)`）从中提取日期再分区。
+
+## 下钻原文
+
+- `official/db_distr_comp/db/tsdb.md` — TSDB 引擎详解（LSM-Tree、sortColumns、Level File、写入/查询/更新/删除流程、性能调优）
+- `official/db_distr_comp/db/olap.md` — OLAP 列存引擎、Cache Engine、MVCC 事务
+- `official/db_distr_comp/db/pkey_engine.md` — PKEY 主键引擎、Merge-on-Write、delete bitmap、bloomfilter/zonemap 索引
+- `official/db_distr_comp/db/imoltp.md` — IMOLTP 内存 OLTP 引擎、B+ 树 OLC、MV2PL、WAL/Checkpoint、`createIMOLTPTable`
+- `official/db_distr_comp/db/vectordb.md` — VectorDB 向量索引（Flat/PQ/IVF/IVFPQ/HNSW）、混合检索、Faiss 集成
+- `official/db_distr_comp/db/tiered_storage.md` — 分级存储（热数据 volumes → 冷数据 coldVolumes / S3）

package/templates/claude-global/skills//346/225/260/346/215/256/345/272/223/dwy-dolphindb/references/digest/finance-patterns.md

@@ -0,0 +1,181 @@
+# DolphinDB 金融场景核心范式
+
+来源：tutorials/new_users_finance.md、backtest/backtest_intro.md、funcs/b/bar.md、funcs/d/dailyAlignedBar.md。
+
+## 1. Tick 行情表结构（L2 逐笔成交）
+
+COMPO 分区（日期 VALUE + 股票代码 HASH），TSDB 引擎，sortColumns 必须含 SecurityID + TradeTime。
+
+```dolphindb
+dbDate = database("", VALUE, 2024.01.01..2024.12.31)
+dbSym  = database("", HASH, [SYMBOL, 25])
+db = database("dfs://tick_l2", COMPO, [dbDate, dbSym], engine="TSDB")
+
+schema = table(
+    1:0,
+    `SecurityID`TradeTime`TradePrice`TradeQty`TradeAmount`BuyNo`SellNo`TradeBSFlag`ChannelNo,
+    [SYMBOL, TIMESTAMP, DECIMAL64(4), LONG, DECIMAL64(4), LONG, LONG, SYMBOL, INT]
+)
+db.createPartitionedTable(
+    schema, `tick,
+    partitionColumns=`TradeTime`SecurityID,
+    sortColumns=`SecurityID`TradeTime,    // TSDB 必须，最后一列为时间
+    keepDuplicates=ALL
+)
+```
+
+L2 快照 10 档行情用数组向量列：
+
+```dolphindb
+`BidPrice`BidQty`OfferPrice`OfferQty 列类型用 DECIMAL64(4)[] 与 LONG[]
+```
+
+## 2. K 线（OHLCV）表结构
+
+```dolphindb
+kline = table(
+    1:0,
+    `SecurityID`BarTime`Open`High`Low`Close`Volume`Amount,
+    [SYMBOL, TIMESTAMP, DECIMAL64(4), DECIMAL64(4), DECIMAL64(4), DECIMAL64(4), LONG, DECIMAL64(4)]
+)
+db.createPartitionedTable(kline, `kline_1min,
+    partitionColumns=`BarTime`SecurityID,
+    sortColumns=`SecurityID`BarTime)
+```
+
+## 3. K 线合成
+
+### 3.1 批量 SQL（历史数据）
+
+bar 函数按固定窗口分组，对齐到 0 时刻：
+
+```dolphindb
+select
+    first(TradePrice) as Open,
+    max(TradePrice)   as High,
+    min(TradePrice)   as Low,
+    last(TradePrice)  as Close,
+    sum(TradeQty)     as Volume,
+    sum(TradeAmount)  as Amount
+from loadTable("dfs://tick_l2", "tick")
+where date(TradeTime) = 2024.01.15
+group by SecurityID, bar(TradeTime, 60s) as BarTime
+```
+
+### 3.2 dailyAlignedBar（对齐交易时段，处理午休/隔夜）
+
+A 股两段：09:30-11:30、13:00-15:00：
+
+```dolphindb
+sessionsBegin = 09:30:00 13:00:00
+sessionsEnd   = 11:30:00 15:00:00
+select first(price) as Open, max(price) as High, min(price) as Low,
+       last(price) as Close, sum(volume) as Volume
+from tick
+group by SecurityID,
+    dailyAlignedBar(TradeTime, sessionsBegin, 1m, sessionsEnd, mergeSessionEnd=true) as BarTime
+```
+
+支持隔夜期货时段（13:30-16:30 + 22:30 跨日至 02:30）。
+
+### 3.3 流式 createTimeSeriesEngine（实时合成）
+
+```dolphindb
+engine = createTimeSeriesEngine(
+    name="kline1min",
+    windowSize=60000, step=60000,
+    metrics=<[first(TradePrice), max(TradePrice), min(TradePrice),
+              last(TradePrice), sum(TradeQty)]>,
+    dummyTable=tickStream, outputTable=klineStream,
+    timeColumn=`TradeTime, keyColumn=`SecurityID,
+    useSystemTime=false, useWindowStartTime=true
+)
+subscribeTable(tableName="tickStream", actionName="kline1min",
+               handler=append!{engine}, msgAsTable=true)
+```
+
+## 4. 因子计算
+
+DolphinDB 内置千余指标函数 + TA-lib 接口 + Alpha101 / 国君 191 因子库。
+
+### 4.1 截面 z-score
+
+```dolphindb
+select SecurityID, BarTime,
+       (Close - avg(Close)) \ std(Close) as zscore
+from kline_1min
+context by BarTime    // 按时间截面分组
+```
+
+### 4.2 时序 mavg / rolling
+
+```dolphindb
+update kline_1min set ma20 = mavg(Close, 20) context by SecurityID
+update kline_1min set rsi  = ta::rsi(Close, 14) context by SecurityID
+```
+
+### 4.3 WorldQuant Alpha101 / 国君 Alpha191
+
+模块名：`wq101alpha` / `gtja191alpha`，加载后 `wq101alpha::alpha1(...)` 直接调用，参考教程 [Practical_Factor_Analysis_Modeling](../official/tutorials/Practical_Factor_Analysis_Modeling.md)。
+
+## 5. TopN 选股 SQL
+
+DolphinDB 用 `limit`（小写），不是 SQL 标准的 `LIMIT`：
+
+```dolphindb
+// 按当日成交额取前 50
+select SecurityID, sum(Amount) as amt
+from loadTable("dfs://tick_l2", "tick")
+where date(TradeTime) = 2024.01.15
+group by SecurityID
+order by amt desc
+limit 50
+```
+
+参考教程 [DolphinDB_TopN](../official/tutorials/DolphinDB_TopN.md)，专门讲千万级数据下的 TopN 优化（topN 排序索引、context by + isort）。
+
+## 6. 回测引擎
+
+`Backtest` 插件 + `Matching Engine Simulator` 模拟撮合插件。
+
+- 资产：股票 / 期货 / 期权 / 银行间债券 / 数字货币 / 多资产组合
+- 数据源：DolphinDB 分布式表（dfs://）或本地 csv 回放
+- 模式：事件驱动型回测，订单流通过 Matching Engine 撮合，输出成交记录 + 持仓 + 盈亏
+
+下钻：[backtest_intro.md](../official/backtest/backtest_intro.md)。
+
+## 7. 交易日历
+
+模块 `MarketHoliday`，处理节假日/调休：
+
+```dolphindb
+use MarketHoliday
+MarketHoliday::isBusinessDay(2024.10.01, "CN")        // false（国庆）
+MarketHoliday::businessDayOffset(2024.09.30, 1, "CN") // 2024.10.08（下一交易日）
+MarketHoliday::businessDaysBetween(2024.01.01, 2024.12.31, "CN")  // 全年交易日数
+```
+
+## 8. 金融场景特有陷阱
+
+| 陷阱 | 正确做法 | 错误做法 |
+|------|---------|---------|
+| 价格精度 | `DECIMAL64(4)` 或 `DECIMAL128(N)` | `DOUBLE`（浮点累加误差，金额对账不上） |
+| 股票代码 | `SYMBOL`（≤ 255 字节，自动字典编码，分区/排序友好） | `STRING`（不参与字典，体积大） |
+| 时间类型 | `TIMESTAMP`（毫秒精度，年份范围足） | `DATETIME`（2038 年溢出，秒精度不够 tick） |
+| L2 高频时间 | `NANOTIMESTAMP`（纳秒） | `TIMESTAMP`（毫秒粒度，逐笔会撞时间戳） |
+| TSDB sortColumns | `[SecurityID, TradeTime]`，时间放最后 | 时间放前面 → 同 SecurityID 时序读取退化 |
+| L2 10 档行情 | 数组向量 `DECIMAL64(4)[]` 一列存 10 个价 | 拆 10 个列 BidPrice1..BidPrice10（schema 难扩展） |
+| 分区粒度 | 日期 VALUE + 股票 HASH 25 桶 | 按分钟分区（元数据爆炸，meta 撑爆控制节点） |
+| K 线 bar 截断 | `bar(time, 60s)` / `dailyAlignedBar(...)` 处理跨段 | 自己 `minute(time) \ N` 拼时间戳 |
+| TopN SQL | 小写 `limit 50` | 大写 `LIMIT 50`（语法错误） |
+| 整数溢出 | `barMinutes*60*long(1000000000)` 显式转 LONG | `barMinutes*60*1000000000`（int 溢出） |
+
+## 9. 下钻原文
+
+- `/Users/chances/WebstormProjects/dwy-shared/claude-cli/templates/claude-global/skills/数据库/dwy-dolphindb/references/official/tutorials/new_users_finance.md` — 金融入门完整教程
+- `/Users/chances/WebstormProjects/dwy-shared/claude-cli/templates/claude-global/skills/数据库/dwy-dolphindb/references/official/tutorials/OHLC.md` + `OHLC_2.md` — K 线合成专题
+- `/Users/chances/WebstormProjects/dwy-shared/claude-cli/templates/claude-global/skills/数据库/dwy-dolphindb/references/official/tutorials/DolphinDB_TopN.md` — TopN 优化
+- `/Users/chances/WebstormProjects/dwy-shared/claude-cli/templates/claude-global/skills/数据库/dwy-dolphindb/references/official/tutorials/Practical_Factor_Analysis_Modeling.md` — Alphalens 因子分析
+- `/Users/chances/WebstormProjects/dwy-shared/claude-cli/templates/claude-global/skills/数据库/dwy-dolphindb/references/official/backtest/backtest_intro.md` — 回测引擎概述
+- `/Users/chances/WebstormProjects/dwy-shared/claude-cli/templates/claude-global/skills/数据库/dwy-dolphindb/references/official/funcs/b/bar.md` — bar 函数
+- `/Users/chances/WebstormProjects/dwy-shared/claude-cli/templates/claude-global/skills/数据库/dwy-dolphindb/references/official/funcs/d/dailyAlignedBar.md` — 对齐交易时段分组