create-dwy 0.9.1 → 0.11.0

package/templates/claude-global/skills/dwy-dolphindb/references/crud-operations.md

@@ -0,0 +1,281 @@
+# 增删改查
+
+## SELECT 基础
+
+```dolphindb
+dbName = "dfs://stock_lv2_snapshot"
+tbName = "snapshot"
+t = loadTable(dbName, tbName)
+
+// 基本查询（WHERE 必带分区列！）
+select * from t where TradeDate = 2024.01.03
+
+// 字段处理
+select concatDateTime(TradeDate, TradeTime) as ts,
+       SecurityID,
+       OfferPrice[0] as ask1,        // 数组向量取第 0 档
+       BidPrice[0] as bid1,
+       LastPrice
+from t
+where TradeDate = 2024.01.03 and SecurityID = `600000`
+
+// 多个分区
+select * from t
+where TradeDate between 2024.01.03 and 2024.01.05
+  and SecurityID in [`600000`, `600036`]
+```
+
+## 分区剪枝（**最重要**）
+
+WHERE 必须用分区列 + DDB 能识别的写法，否则全表扫。
+
+### ✅ 触发剪枝的写法
+
+```dolphindb
+where TradeDate = 2024.01.03
+where TradeDate between 2024.01.03 and 2024.01.05
+where TradeDate >= 2024.01.01 and TradeDate <= 2024.01.05
+where TradeDate in [2024.01.03, 2024.01.04]
+where SecurityID = `600000`        // HASH 分区列也可剪枝
+```
+
+### ❌ 不触发剪枝（全表扫）
+
+```dolphindb
+where 2024.01.01 <= TradeDate <= 2024.01.05    // 链式比较
+where year(TradeDate) = 2024                    // 分区列被函数包裹
+where temporalAdd(TradeDate,1,'d') > 2024.01.03 // 同上
+where TradeDate + 1 = 2024.01.04                // 列上做了运算
+```
+
+### 验证剪枝
+
+```dolphindb
+// 加 [HINT_EXPLAIN] 看执行计划
+select [HINT_EXPLAIN] *
+from t
+where TradeDate between 2024.01.03 and 2024.01.05
+```
+
+输出 `partitions.local` 的数量应该等于范围内分区数，不是全库分区数。
+
+**实测对比**（同一查询、同一表）：
+
+| 写法 | 扫描分区数 |
+|---|---|
+| `where 2022.12.01 <= TradeDate <= 2022.12.03` | 10091（全表扫） |
+| `where TradeDate between 2022.12.01 and 2022.12.03` | 90（剪枝成功） |
+| `where TradeDate >= 2022.12.01 and TradeDate <= 2022.12.03` | 90 |
+
+## INSERT / 写入
+
+```dolphindb
+// 方式 1：tableInsert（推荐，可链式）
+t1 = loadTable(dbName, tbName)
+rows = t1.tableInsert(newData)
+
+// 方式 2：append!
+loadTable(dbName, tbName).append!(newData)
+
+// 方式 3：insert into（只能逐行小批）
+insert into snapshot values(2024.01.03, 09:30:00.000, `600000`, 10.5, ...)
+
+// 方式 4：upsert!（按 key 去重写入）
+loadTable(dbName, tbName).upsert!(
+    newData,
+    keyColNames=[`TradeDate, `TradeTime, `SecurityID]
+)
+```
+
+**append! 列对齐警告**：DDB 不检查列名，**只按位置**。如果列顺序错位，数据全错且不报错。导入前必做：
+
+```dolphindb
+expectedCols = loadTable(dbName, tbName).schema().colDefs.name
+newData.reorderColumns!(expectedCols)   // 强制对齐
+```
+
+## DELETE
+
+### 按分区删（**首选**）
+
+```dolphindb
+db = database(dbName)
+dropPartition(db, [2024.01.03], tableName=tbName)              // 单天
+dropPartition(db, [2024.01.03..2024.01.05], tableName=tbName)  // 多天
+```
+
+秒级，不占内存。
+
+### 按条件删（慢）
+
+```dolphindb
+delete from loadTable(dbName, tbName) where SecurityID = `600000`
+```
+
+会扫描所有分区，**OLAP 引擎不支持**，只能用 `dropPartition`。
+
+### 清空整张表
+
+```dolphindb
+truncate(dbName, tbName)              // 保留表结构
+dropTable(db, tbName)                 // 表结构也删
+dropDatabase(dbName)                  // 整个库
+```
+
+## UPDATE
+
+```dolphindb
+update loadTable(dbName, tbName)
+set ask1 = OfferPrice[0], bid1 = BidPrice[0]
+where TradeDate = 2024.01.03
+```
+
+**OLAP 不支持 UPDATE**，TSDB 才行。OLAP 要改数据：删分区 → 重写。
+
+## 函数式 SQL（动态构造）
+
+适合脚本里按参数拼条件，比拼字符串更安全：
+
+```dolphindb
+dt = 2024.01.03
+sid = `600000
+
+// sql() 构造，再用 sqlDS / executeSQL 跑
+q = sql(
+    select = sqlCol(`LastPrice).avg(),
+    from = loadTable(dbName, tbName),
+    where = expr(sqlCol(`TradeDate), ==, dt)
+)
+// 跑：把 q 喂给 mr / 或直接拿 SQL 文本
+print(q)                  // 看生成的 SQL
+```
+
+**meta SQL 慎用**：能写死的就不要动态拼，可读性和性能都更好。
+
+## 大结果集分页拉取
+
+服务端 SELECT 结果太大 → 客户端 OOM。Python SDK 用 `fetchSize`：
+
+```python
+block = s.run("select * from loadTable('dfs://x','t') where TradeDate=2024.01.03",
+              fetchSize=8192)
+while block.hasNext():
+    chunk = block.read()           // pd.DataFrame
+    process(chunk)
+# block.skipAll()                  // 不需要剩余数据时调
+```
+
+或者**先在服务端聚合再拉**：
+
+```python
+# ❌ 拉 1 亿行下来再 groupby
+df = s.run("select * from loadTable(...) where TradeDate=2024.01.03")
+df.groupby('SecurityID')['LastPrice'].mean()
+
+# ✅ 服务端 group by，只拉结果
+df = s.run("select avg(LastPrice) from loadTable(...) where TradeDate=2024.01.03 group by SecurityID")
+```
+
+## 查询优化必修
+
+### 1. 聚合查询合并成一次
+
+```python
+# ❌ 3 次往返
+min_d = s.run("select min(TradeDate) from loadTable('dfs://x','t')")
+max_d = s.run("select max(TradeDate) from loadTable('dfs://x','t')")
+cnt   = s.run("select count(*) from loadTable('dfs://x','t')")
+
+# ✅ 1 次
+r = s.run("""
+    select min(TradeDate) as earliest, max(TradeDate) as latest, count(*) as total
+    from loadTable('dfs://x','t')
+""")
+```
+
+### 2. 只 select 需要的列
+
+```dolphindb
+// ❌ 30 列全传
+select * from loadTable('dfs://x','t') where TradeDate=2024.01.03
+
+// ✅ 只取要的
+select TradeDate, TradeTime, SecurityID, LastPrice, TotalVolumeTrade
+from loadTable('dfs://x','t') where TradeDate=2024.01.03
+```
+
+列式存储，少列就少 IO。
+
+### 3. 多因子查询用 pivot by（服务端转列）
+
+```dolphindb
+// ❌ Python 端 merge：N 个因子 N 次查询 + N 次 join
+// ✅ 服务端一次 pivot 完成宽表
+select value from loadTable('dfs://factor','f')
+where TradeDate between 2024.01.01 and 2024.01.31
+pivot by TradeDate, SecurityID, factorName
+```
+
+### 4. 分页语法（**DDB ≠ 标准 SQL**）
+
+```dolphindb
+// ❌ 标准 SQL OFFSET 关键字 DDB 不支持
+select * from loadTable('dfs://x','t') limit 100 offset 200
+
+// ✅ DDB 分页语法：limit 跳过行数, 返回行数
+select * from loadTable('dfs://x','t') limit 200, 100
+//                                            ^^^  ^^^
+//                                          offset count
+```
+
+## 常用聚合
+
+```dolphindb
+// 行级
+select first(LastPrice), last(LastPrice), max(HighPrice), min(LowPrice),
+       avg(LastPrice), sum(TotalVolumeTrade), count(*), wavg(LastPrice, TotalVolumeTrade)
+from t where TradeDate=2024.01.03 group by SecurityID
+
+// 分桶（5 分钟 K 线）
+select first(LastPrice) as open, max(HighPrice) as high,
+       min(LowPrice) as low, last(LastPrice) as close,
+       sum(TotalVolumeTrade) as vol
+from t
+where TradeDate=2024.01.03
+group by SecurityID, bar(TradeTime, 5*60*1000) as bar5min
+
+// interval 填充缺失桶
+select last(LastPrice) as close
+from t
+group by SecurityID, interval(X=TradeTime, duration=60s, label='left', fill=0) as bar1min
+```
+
+## context by 与 csort（**分组内排序**）
+
+`group by` 聚合后只剩一行，`context by` 保留所有行（窗口运算）：
+
+```dolphindb
+// 按股票分组、按时间排序，算每只股的累计成交量
+select TradeDate, TradeTime, SecurityID, TotalVolumeTrade,
+       cumsum(TotalVolumeTrade) as cumVol
+from t where TradeDate=2024.01.03
+context by SecurityID csort TradeTime
+```
+
+`csort` 默认升序。`csort TradeTime desc` 降序。
+
+## pivot（行列转换）
+
+```dolphindb
+// 输出矩阵：行 = 时间，列 = 股票
+m = exec last(LastPrice) from t
+    where TradeDate=2024.01.03
+    pivot by TradeTime, SecurityID
+
+// 截面排名
+rowRank(m)
+```
+
+`exec` 是 `select` 的标量版本，配合 `pivot by` 出矩阵。
+
+跨引用：批计算 → [[sql-batch-compute]]，慢查询排查 → [[performance-tuning]]。

package/templates/claude-global/skills/dwy-dolphindb/references/data-import.md

@@ -0,0 +1,271 @@
+# 数据导入
+
+## 30 秒选型
+
+| 场景 | 方法 | 优势 |
+|---|---|---|
+| 单文件 / dev 验证 | `loadText` → `tableInsert` | 简单 |
+| 大文件（>1GB） | `textChunkDS` + `mr` | 分块流式，不爆内存 |
+| 一天一文件，批量历史回填 | `loadTextEx` + `submitJob` 多并发 | 并行 |
+| 海量小文件（每个股票一文件） | HASH 分桶合并 + `submitJob` | 减少小事务 |
+| Python DataFrame → DDB | `TableAppender` / `PartitionedTableAppender` | 自动类型转换 |
+| 高频流式写入 | `MultithreadedTableWriter` | C++ 后台批量 |
+
+## DDB Script 三种导入
+
+### 方式 1：loadTextEx（推荐，按日切文件）
+
+```dolphindb
+dataPath = "/data/snapshot/"            // 一天一文件
+file_list = files(dataPath).filename
+dbName = "dfs://stock_lv2_snapshot"
+tbName = "snapshot"
+
+// 用现有表 schema 解析（保证类型一致）
+schema = select name, typeString as type
+         from loadTable(dbName, tbName).schema().colDefs
+
+def loadDataByDay(dbName, tbName, schema, fileName){
+    loadTextEx(
+        dbHandle=database(dbName), tableName=tbName,
+        partitionColumns=["TradeDate", "SecurityID"],
+        filename=fileName, schema=schema,
+        sortColumns=[`SecurityID, `TradeTime]
+    )
+}
+
+def submitLoad(dbName, tbName, schema, fileName){
+    submitJob("loadDay", "load " + fileName,
+              loadDataByDay, dbName, tbName, schema, fileName)
+}
+
+// 串行（社区版 4 worker，4 个并发就够了）
+each(submitLoad{dbName, tbName, schema}, dataPath + file_list)
+
+// 看进度
+getRecentJobs(size(file_list))
+```
+
+### 方式 2：textChunkDS + mr（大文件不爆内存）
+
+```dolphindb
+// 512 MB 一块
+ds = textChunkDS(fileName=dataPath+"huge_file.csv",
+                 chunkSize=512, schema=schema)
+
+// parallel=false：每块串行写（多线程并发写同一 DFS 表会冲突）
+mr(ds, tableInsert{loadTable(dbName, tbName)}, parallel=false)
+```
+
+**关键**：`parallel=false` 不能省。多 worker 并发写同一分区会触发锁等待，反而更慢。
+
+### 方式 3：海量小文件按 HASH 合并
+
+```dolphindb
+// 每个股票一个 csv，5000 个文件 → 合成 50 个批次
+tmp = table(file_list as path, file_list.split(".")[0] as sid)
+update tmp set hashNo = sid.hashBucket(50)
+batches = select toArray(path) as fileBucket from tmp group by hashNo
+
+def loadBatch(dbName, tbName, schema, fileNames){
+    bigTable = loop(loadText{schema=schema}, fileNames).unionAll()
+    return loadTable(dbName, tbName).tableInsert(bigTable)
+}
+
+for(i in 0:batches.size()){
+    submitJob("loadBatch_" + string(i), "load hash " + string(batches.hashNo[i]),
+              loadBatch, dbName, tbName, schema, dataPath + batches.fileBucket[i])
+}
+```
+
+## 数据预处理（导入时变换）
+
+### 时间格式转换
+
+```dolphindb
+// CSV 时间列是字符串 "09:30:00.000 04/01/2022"
+schema = extractTextSchema(dataPath)
+update schema set type = "STRING" where name = "tradetime"
+
+def transFunc(mutable msg){
+    msg.replaceColumn!("tradetime",
+        msg.tradetime.temporalParse("HH:mm:ss.SSS dd/MM/yyyy"))
+    return msg
+}
+
+loadTextEx(dbHandle=database(dbName), tableName=tbName,
+           partitionColumns="tradetime",
+           filename=dataPath, schema=schema,
+           transform=transFunc)
+```
+
+### 从文件名提取字段
+
+```dolphindb
+// 文件名是股票代码，要加进表里
+def transFunc(mutable msg, sid, orderCols){
+    data = select sid as SecurityID, * from msg
+    data.reorderColumns!(orderCols)
+    return data
+}
+
+orderCols = loadTable(dbName, tbName).schema().colDefs.name
+
+for(i in 0:sids.size()){
+    loadTextEx(..., transform=transFunc{, sids[i], orderCols})
+}
+```
+
+### 多列合并成数组向量（10 档行情）
+
+```dolphindb
+def transFunc(mutable msg){
+    return select TradeDate, TradeTime, SecurityID,
+        fixedLengthArrayVector(offerPx1, offerPx2, ..., offerPx10) as offerPx,
+        fixedLengthArrayVector(bidPx1, bidPx2, ..., bidPx10) as bidPx
+    from msg
+}
+```
+
+## Python SDK 四种写入方式
+
+### 1. tableInsert（一次性小批量）
+
+```python
+import pandas as pd
+
+s.run("t = table(100:0, [`code`,`price`], [SYMBOL, DOUBLE])")
+data = pd.DataFrame({'code': ['600000','600036'], 'price': [10.5, 35.2]})
+s.run("tableInsert{t}", data)
+```
+
+适合：内存表 / 单次少量数据。
+
+### 2. TableAppender（自动类型转换）
+
+```python
+import dolphindb as ddb
+
+appender = ddb.TableAppender(
+    dbPath="dfs://stock_lv2_snapshot",
+    tableName="snapshot",
+    ddbSession=s,
+)
+rows = appender.append(df)   # df 是 pd.DataFrame
+```
+
+适合：DataFrame → DDB 单连接顺序写。**不需要手动管理列类型映射**。
+
+### 3. PartitionedTableAppender（并发写分区表，**推荐**）
+
+```python
+pool = ddb.DBConnectionPool("localhost", 8848, threadNum=3,
+                             userId="admin", password="123456")
+
+ptAppender = ddb.PartitionedTableAppender(
+    dbPath="dfs://stock_lv2_snapshot",
+    tableName="snapshot",
+    partitionColName="SecurityID",     // Python SDK 用普通字符串，不要写反引号
+    dbConnectionPool=pool,
+)
+rows = ptAppender.append(df)
+pool.shutDown()
+```
+
+适合：DataFrame → DFS 分区表的**主流方式**。`partitionColName` 必须是表的分区列之一，pool 会按 hash 分发到不同连接并发写。
+
+**社区版 4 worker → pool size 3**（留 1 个给 web/管理）。
+
+### 4. MultithreadedTableWriter（高频流式写入）
+
+```python
+writer = ddb.MultithreadedTableWriter(
+    "localhost", 8848, "admin", "123456",
+    dbPath="dfs://stock_lv2_snapshot",
+    tableName="snapshot",
+    batchSize=10000,            // 攒 1w 行批量发
+    throttle=1,                 // 或最多攒 1s
+    threadCount=2,              // 后台线程数
+    partitionCol="SecurityID",
+)
+
+for record in tick_stream:
+    writer.insert(*record)      // 逐条插入，writer 自己批
+
+writer.waitForThreadCompletion()
+status = writer.getStatus()
+```
+
+适合：实时行情、kafka 消费等高频场景。后台 C++ 线程不受 Python GIL 限制。
+
+**坑**：`insert(*args)` 参数顺序必须和表列顺序一致，写错只在线程里报错，主线程不感知。要看 `writer.getStatus()` 确认。
+
+## 批量写入硬限（**Python 端必守**）
+
+```python
+BATCH_SIZE = 500_000   // TSDB 单次 append ≤ 204MB（约 800K 行 × 30 列），500K 行 ≈ 120MB 安全余量
+```
+
+| 规则 | 原因 |
+|---|---|
+| 每批 ≤ 500K 行 | TSDB 单次 append 内存上限 204MB，超出报 `exceeds max limit` |
+| 每批后 `gc.collect()` | 释放 Python 侧 DataFrame 内存 |
+| 每批后 `del batch_df` | 显式释放引用 |
+| 大文件用 pyarrow 分片 | `pf.read_table()` memory-mapped，不全量加载 |
+| 批量循环复用同一 Session | 不要每批新建/关闭连接 |
+
+### 标准范式：pyarrow + slice 分片
+
+```python
+import pyarrow.feather as pf
+import gc
+
+table = pf.read_table("10M_rows.ftr")          # memory-mapped，不全量读入 RAM
+appender = ddb.TableAppender(dbPath="dfs://x", tableName="t", ddbSession=s)
+
+num_batches = (table.num_rows + BATCH_SIZE - 1) // BATCH_SIZE
+for i in range(num_batches):
+    arrow_slice = table.slice(i * BATCH_SIZE, BATCH_SIZE)
+    batch_df = arrow_slice.to_pandas()
+    del arrow_slice
+    appender.append(batch_df)
+    del batch_df
+    gc.collect()
+```
+
+### 禁止的写法
+
+```python
+# ❌ 一次性读取大文件到 pandas（10M 行 ≈ 2.6GB，OOM）
+df = pd.read_feather("10M_rows.ftr")
+
+# ❌ 单次 append 超过 500K 行
+appender.append(df_1million_rows)              # 直接报 exceeds max limit
+
+# ❌ 循环不释放内存
+for batch in batches:
+    appender.append(batch)
+    # 忘记 del + gc.collect() → 累积到 8GB OOM
+```
+
+## 性能基线（2核8G 社区版参考）
+
+| 方式 | 吞吐 |
+|---|---|
+| loadText（单线程） | 100-200 MB/s |
+| loadTextEx + submitJob × 4 | 300-500 MB/s |
+| TableAppender | 50-100 万行/s |
+| PartitionedTableAppender + pool 3 | 200-400 万行/s |
+| MultithreadedTableWriter | 500-1000 万行/s |
+
+## 常见报错
+
+| 报错 | 原因 | 处理 |
+|---|---|---|
+| `Data conversion error: column X` | DataFrame 列类型对不上 | 用 `df[col].astype(...)` 转好；或换 `TableAppender` 自动转 |
+| `Out of memory` | 单批太大 | DataFrame 切片：`for chunk in np.array_split(df, 10): appender.append(chunk)` |
+| `Partition does not exist` | VALUE 分区还没建 | 库要开 `allowMissingPartitions=true` 或预建好分区 |
+| `loadTextEx` 卡住 | 文件被 office 锁住 / 编码问题 | `extractTextSchema()` 看是否能正确识别 |
+| 写入很慢 | 多 worker 写同一分区抢锁 | `parallel=false`（DDB Script）或按分区列分发（Python） |
+
+跨引用：建表 → [[create-database-table]]，查询 → [[crud-operations]]，调优 → [[performance-tuning]]。

package/templates/claude-global/skills/dwy-dolphindb/references/docker-deployment.md

@@ -0,0 +1,63 @@
+# Docker 部署（v3 Alpine 镜像）
+
+## 已知坑（按踩坑频次）
+
+| 问题 | 表现 | 解决 |
+|---|---|---|
+| 镜像里没有 `curl` | healthcheck `curl: not found` | 用 `wget` 替代 |
+| `localhost` 解析到 IPv6 ::1，DDB 只监听 v4 | healthcheck 连不上 | 改 `127.0.0.1` |
+| macOS 宿主无 `/etc/hostname` `/etc/machine-id` | 启动报 mount 失败 | 不要 mount 这两个文件 |
+| 自定义 `dolphindb.cfg` 写了 `logFile`/`volumes` 路径 | 与 Docker volume 冲突 → 数据写错位置 | 只覆盖必要参数（如 `maxMemSize`），其余用默认 |
+| `dataSync` 和 `CacheEngine` 只开一个 | 启动失败或数据异常 | 要开都开，要关都关。开发环境**都不配**用默认值 |
+| 服务名 vs localhost | 后端 `localhost:8848` 连不到容器内的 DDB | 用 Docker 服务名 `dolphindb:8848` |
+
+## 标准 healthcheck
+
+```yaml
+services:
+  dolphindb:
+    image: dolphindb/dolphindb:v3.00.x-alpine
+    ports:
+      - "8848:8848"
+    healthcheck:
+      test: ["CMD-SHELL", "wget -qO- --timeout=3 http://127.0.0.1:8848/ || exit 1"]
+      start_period: 30s    # DDB 初始化慢，给足时间
+      interval: 5s
+      timeout: 5s
+      retries: 10
+    deploy:
+      resources:
+        limits:
+          memory: 8G       # 社区版硬上限
+          cpus: '2'        # 社区版硬上限
+```
+
+## 后端连接 env 模板
+
+```bash
+# 容器间用服务名，不要 localhost
+DOLPHINDB_HOST=dolphindb
+DOLPHINDB_PORT=8848
+DOLPHINDB_USER=admin
+DOLPHINDB_PASSWORD=改成你的强密码
+DOLPHINDB_POOL_SIZE=2           # 2 核机器经验值，不是协议层 512 的上限
+DOLPHINDB_KEEPALIVE=120         # 长查询调高，默认 30s 容易断
+```
+
+`DOLPHINDB_POOL_SIZE` 取值：4 worker → pool size 3。设大没收益（worker 是 4），还可能挤占 web/管理。
+
+## 配置最小化
+
+只覆盖**必须**的几个参数，其余用镜像默认：
+
+```ini
+# dolphindb.cfg（minimal）
+maxMemSize=6                    # 留 2GB 给 OS
+workerNum=4                     # CPU 核数 × 2
+chunkCacheEngineMemSize=1       # 列缓存上限
+TSDBCacheEngineSize=0.5         // TSDB 写缓存
+```
+
+**别动**：`logFile`、`volumes`、`dfsMetaDir`、`chunkMetaDir`、`persistenceDir`、`TSDBRedoLogDir` —— 这些和 Docker volume 挂载位置耦合，改了启动失败或数据丢失。
+
+跨引用：连接配置 → [[setup-and-connection]]，性能调优 → [[performance-tuning]]。