create-dwy 0.12.2 → 0.13.1

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

@@ -0,0 +1,141 @@
+---
+topic: perf-tuning
+source_files:
+  - official/funcs/g/getClusterPerf.md
+  - official/funcs/g/getConsoleJobs.md
+  - official/funcs/g/getSessionMemoryStat.md
+  - official/funcs/g/getMemoryStat.md
+  - official/funcs/c/cancelJob.md
+generated_at: 2026-05-19
+---
+
+# 性能调优
+
+## 何时用此主题
+
+- 节点慢/卡，需要定位是 CPU、内存、磁盘还是网络瓶颈
+- 查询 RT 突增，需要找出慢 SQL/慢作业并杀掉
+- 频繁 OOM、`Out of memory` 错误
+- 写入吞吐下降、`flushTSDBCache` 阻塞、redo log 堆积
+- 集群容量规划（磁盘 80%、内存 70% 告警阈值）
+
+## 1. 资源监控速查表
+
+所有命令优先用 `pnodeRun(funcName)` 批量打到所有数据节点。
+
+| 维度 | 函数 | 关键字段 | 用途 |
+| --- | --- | --- | --- |
+| 集群总览 | `getClusterPerf(true)` | memoryUsed/cpuUsage/avgLoad/runningJobs/queuedJobs/diskFreeSpaceRatio | 一次性看所有节点的 CPU、内存、磁盘、作业队列 |
+| 活跃作业 | `getConsoleJobs()` | rootJobId/desc/priority/parallelism/firstTaskStartTime/queue | 看本地节点正在跑的交互式作业 |
+| 全集群作业 | `pnodeRun(getConsoleJobs)` | 同上 | 看所有数据节点的活跃作业 |
+| 历史作业 | `getRecentJobs([n])` | jobId/startTime/endTime/errorMsg | 看最近 n 条批作业（含已完成/失败） |
+| 节点内存 | `getMemoryStat()` | allocatedBytes/freeBytes | 节点已分配/未使用内存（差值=占用） |
+| 会话内存 | `getSessionMemoryStat()` | userId/sessionId/memSize | 哪个会话/哪个引擎吃内存（含 OLAP/TSDB CacheEngine、共享表、维度表、流队列） |
+| 磁盘 IO | `getDiskIOStat()` | readRate/writeRate/IOPS | 看磁盘读写速率 |
+| 表磁盘占用 | `getTableDiskUsage(dbUrl, tbName)` | size | 单表占用空间，找异常大表 |
+| chunk 状态 | `getClusterChunksStatus()` | chunkId/state/version | 看 chunk 是否健康、版本是否一致 |
+
+速查脚本：
+
+```dolphindb
+// 一行体检
+select name, memoryUsed/1024/1024/1024 as memGB, cpuUsage, runningJobs, queuedJobs,
+       diskFreeSpaceRatio
+from pnodeRun(getClusterPerf) order by memGB desc
+
+// 找吃内存的会话
+select * from pnodeRun(getSessionMemoryStat) order by memSize desc limit 20
+
+// 找跑得最久的活跃作业
+select * from pnodeRun(getConsoleJobs) order by firstTaskStartTime asc limit 20
+```
+
+## 2. 慢查询定位流程
+
+1. 加 `HINT_EXPLAIN` 看物理计划：`select [HINT_EXPLAIN] ... from pt where ...` — 看是否走分区剪枝、是否走 sortColumns 索引
+2. 检查分区剪枝：where 条件必须命中分区字段；range/value 分区不剪枝时全表扫
+3. 资源争抢：`getConsoleJobs` 看是否同时有大批作业占满 workerNum
+4. 磁盘：`getDiskIOStat` 看 readRate 是否打满 IOPS，TSDB 大查询会读 level file
+5. 内存：`getSessionMemoryStat` 看 `__TSDBCacheEngine__` / `__OLAPCacheEngine__` 是否爆了
+6. sortColumns：TSDB 表查询必须带 sortColumns 前缀字段才走索引，否则全分区扫
+7. 看 `getClusterPerf` 的 `medLast10QueryTime` / `maxRunningQueryTime`（需 `perfMonitoring=1`）
+
+## 3. OOM 排查表
+
+| 现象 | 常见原因 | 修复 |
+| --- | --- | --- |
+| `Out of memory, used XX, limit YY` | `maxMemSize` 设置过小 | 调大 `maxMemSize`，单节点建议物理内存 70% |
+| 单会话 memSize 飙到几十 GB | 查询返回结果未分页/`select *` 全表拉回 | 加 LIMIT、用 `loop`/`each` 分批 |
+| `__TSDBCacheEngine__` 巨大 | 写入未及时刷盘 | 调小 `TSDBCacheEngineSize`，或主动 `flushTSDBCache()` |
+| `__OLAPCacheEngine__` 巨大 | OLAP 写入缓存堆积 | 调小 `chunkCacheEngineMemSize`，或调小 `cacheEngineLowWaterLevelRatio` |
+| `__SharedTable__` 巨大 | 共享表/流表无限增长 | 设置 `enableTableShareAndPersistence` keepDuration 自动清理 |
+
+## 4. 关键配置项
+
+| 配置 | 含义 | 经验值 |
+| --- | --- | --- |
+| `maxMemSize` | 节点内存上限（GB） | 物理内存 70% |
+| `workerNum` | 常规作业线程数 | CPU 核数 |
+| `localExecutors` | 本地执行线程数 | CPU 核数 - 1 |
+| `chunkCacheEngineMemSize` | OLAP Cache Engine 上限（GB） | maxMemSize 的 1/4 |
+| `TSDBCacheEngineSize` | TSDB Cache Engine 上限（GB） | maxMemSize 的 1/8~1/4 |
+| `redoLogPurgeInterval` | redo log 清理间隔（秒） | 30 |
+| `dataSync` | redo log 落盘策略 | 1=每事务 fsync，强一致；0=异步，性能高 |
+
+## 5. 杀作业
+
+```dolphindb
+// 杀交互式作业（getConsoleJobs 的 rootJobId）
+cancelConsoleJob(rootJobId)
+
+// 杀批处理作业（submitJob 返回的 jobId）
+cancelJob(jobId)              // 单个
+cancelJob(["jobId1", "jobId2"])  // 批量
+
+// 一键清理全集群所有未完成批作业
+def cancelAllBatchJob(){
+   jobids = exec jobid from getRecentJobs() where endTime=NULL
+   cancelJob(jobids)
+}
+pnodeRun(cancelAllBatchJob)
+```
+
+权限：管理员可杀任意用户作业；普通用户只能杀自己的（2.00.11+）。
+
+## 6. 写入慢排查
+
+| 现象 | 原因 | 修复 |
+| --- | --- | --- |
+| `tableInsert` RT 抖动 | 单线程写大批量 | 用 `PartitionedTableAppender` 多线程并发写 |
+| TSDB 写入越来越慢 | sortColumns 维度过多导致 level file 索引膨胀 | sortColumns 维度数 ≤ 3，高基数字段放最后 |
+| `redo log full` | 磁盘 IOPS 不够 | redo log 单独挂 SSD，或调大 `redoLogPurgeInterval` |
+| 写入卡住、`flushTSDBCache` 阻塞 | TSDBCacheEngine 满 | 调大 `TSDBCacheEngineSize` 或加 `flushTSDBCache()` 主动刷 |
+| OLAP 写入慢 | chunk 版本冲突 | 检查 `getClusterChunksStatus` 是否有 inconsistent |
+
+## 7. 磁盘 80% 监控
+
+```dolphindb
+// 告警脚本：磁盘可用空间 < 20%
+select name, diskFreeSpaceRatio
+from pnodeRun(getClusterPerf)
+where diskFreeSpaceRatio < 0.2
+```
+
+策略：
+
+- TSDB 表设 TTL 自动清理：`setRetentionPolicy(db, hours, partitionColumnIndex)`
+- 冷数据归档到 OSS/S3：`backup` + `restore`
+- 单分区过大时考虑 COMPO 分区拆分
+
+## 下钻
+
+- `references/official/funcs/g/getClusterPerf.md` — 集群性能字段完整列表（含 perfMonitoring=1 才返回的字段）
+- `references/official/funcs/g/getConsoleJobs.md` — 活跃作业字段、queue 类型说明
+- `references/official/funcs/g/getSessionMemoryStat.md` — 内置缓存标识符（`__OLAPCacheEngine__` 等）完整含义
+- `references/official/funcs/g/getMemoryStat.md` — allocatedBytes/freeBytes 字段
+- `references/official/funcs/g/getRecentJobs.md` — 历史批作业查询
+- `references/official/funcs/g/getDiskIOStat.md` — 磁盘 IO 速率
+- `references/official/funcs/g/getTableDiskUsage.md` — 单表磁盘占用
+- `references/official/funcs/g/getClusterChunksStatus.md` — chunk 状态
+- `references/official/funcs/c/cancelJob.md` — 批作业取消（含 pnodeRun 全集群清理示例）
+- `references/official/funcs/c/cancelConsoleJob.md` — 交互式作业取消

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

@@ -0,0 +1,189 @@
+---
+topic: python-sdk
+source_files:
+  - official/pydoc/BasicOperations/Session/Connect.md
+  - official/pydoc/BasicOperations/connection_pool.md
+  - official/pydoc/BasicOperations/table_append.md
+  - official/pydoc/BasicOperations/async_write.md
+  - official/pydoc/BasicOperations/Subscription/Subscription.md
+generated_at: 2026-05-19
+---
+# Python SDK 核心
+
+## 何时用此主题
+
+Python 应用接入 DolphinDB：建连、连接池、批量写入、流订阅、异步提交、Python ↔ DDB 类型映射、大结果分段拉取。优先看本摘要选型与陷阱，写真实代码前下钻原文确认参数。
+
+## 安装与版本
+
+- 包名 `dolphindb`，建议固定 `3.0.4`（与 server 主线 2.00.10+ 配套）。
+- `pip install dolphindb==3.0.4`，Python 3.8–3.11；arm64 mac 走 conda 或源码。
+- API 版本须匹配 server：1.30.x / 2.00.9 之前订阅需指定本地端口；2.00.9+ 反向推送，端口参数忽略。
+
+## session.connect 关键参数
+
+| 参数 | 说明 |
+|---|---|
+| host / port | 节点地址与端口（必填） |
+| userid / password | 登录账号；也可 `s.login()` 二次登录 |
+| highAvailability | True 开 API 高可用，自动重连 |
+| highAvailabilitySites | `["ip:port", ...]`，未填则用集群全部节点 |
+| keepAliveTime | TCP 保活秒数，默认 60，弱网下调大可及时释放半打开连接 |
+| reconnect | 非高可用模式下断线自动重连开关 |
+| tryReconnectNums | 重连尝试次数，缺省无限 |
+| readTimeout / writeTimeout | TCP 读写超时（秒），缺省无限 |
+| startup | 连接成功后执行的启动脚本（如 `clearAllCache();`、加载插件、定义流表） |
+| protocol | 序列化协议，金融大批量优先 `PROTOCOL_DDB`；与 numpy/pandas 互操作可用默认 |
+
+负载均衡公式：`load = (connectionNum + workerNum + executorNum) / 3.0`。多线程同时建连不能保证均衡，要么单线程错峰，要么客户端轮询。
+
+## DBConnectionPool 用法
+
+```python
+from dolphindb import DBConnectionPool
+pool = DBConnectionPool("localhost", 8848, 8, "admin", "123456")
+task_id = 1
+pool.addTask("select count(*) from loadTable('dfs://k', 'tick')", taskId=task_id)
+df = pool.getData(taskId=task_id)
+pool.shutDown()
+```
+
+- `size` 建议 = CPU 核数到 `2 × 核数`，跨节点查询可加大到 16；不是越大越好，server 端 workerNum 才是真瓶颈。
+- `pool.run(script)` 在内部线程上跑，**返回的是协程（awaitable）**，必须 `await pool.run(...)`，**不要**再套 `asyncio.to_thread`，会双层线程化导致死锁/吞吐崩。
+- `pool` 的 upload 与单 session 的 upload 不互通：连接池每条任务可能走不同物理连接，上传到一个连接的变量在另一个连接不可见。要共享变量改用单 session 或 server 端共享表（`share` / `streamTable`）。
+
+## 写入方式选型
+
+| 方式 | 适用场景 | 关键参数 | 是否多线程 |
+|---|---|---|---|
+| `tableAppender` | 中小批量、内存表/分布式表追加，需自动类型转换 | `dbPath, tableName, ddbSession` | 否 |
+| `tableInsert` | 简单一次性 insert，server 端 `tableInsert(tbl, data)` | — | 否 |
+| `PartitionedTableAppender` | 已知分区列、客户端并行按分区写入 dfs 表 | `dbPath, tableName, partitionColName, dbConnectionPool` | 是（按分区并发） |
+| `MultithreadedTableWriter`（MTW） | 高吞吐流式写入（行情、订单流），自带缓冲 + 后台 flush + 失败重传 | `host, port, dbPath, tableName, useSSL, enableHighAvailability, highAvailabilitySites, batchSize, throttle, threadCount, partitionCol` | 是 |
+
+经验：实时行情用 MTW；离线批 ETL 按分区切片用 PartitionedTableAppender；小批管理类数据用 tableAppender。
+
+## 类型映射
+
+| Python / pandas | DDB |
+|---|---|
+| `bool` | BOOL |
+| `int8/16/32/64` | CHAR / SHORT / INT / LONG |
+| `uint8/16/32/64` | 转 SHORT / INT / LONG / —（uint64 易溢出，建议强转 int64） |
+| `float32/64` | FLOAT / DOUBLE |
+| `str` | STRING |
+| `bytes`(定长) | SYMBOL（建议显式 dtype） |
+| `datetime64[ns]` | NANOTIMESTAMP |
+| `datetime64[ms]` | TIMESTAMP |
+| `datetime64[s]` | DATETIME |
+| `datetime64[D]` | DATE |
+| `Decimal` | DECIMAL32/64/128（须 server 端列已声明精度） |
+| `np.nan` / `pd.NA` / `None` | NULL（DDB 用类型化 NULL，不要混用） |
+
+upload DataFrame 时务必用 numpy dtype 明确化，禁止 `object`；时间列统一 `datetime64[ns]` 再让 server 端 cast。
+
+## 大结果集分段
+
+```python
+res = s.runBlock("select * from loadTable('dfs://k','tick') where date=2026.05.19", fetchSize=100000)
+while res.hasNext():
+    df = res.read()      # 每次 10w 行
+```
+
+- 单条 `run` 默认一次传完，大结果会爆内存；`fetchSize` 强制分段。
+- server 端单条 IPC 消息上限约 **500K 行**，超过会被截断/报错，配合 `fetchSize` 或 server 端分页。
+
+## 流订阅
+
+```python
+import dolphindb as ddb, numpy as np
+s = ddb.session()
+s.enableStreaming()   # 2.00.9+ 反向推送，无需端口
+
+def handler(msg):
+    print(msg)        # batchSize 未设 → 单条 list；msgAsTable=True + batchSize → DataFrame
+
+s.subscribe(
+    host="localhost", port=8848,
+    handler=handler,
+    tableName="trades", actionName="py_sub",
+    offset=-1,                       # -1 当前行；-2 从持久化 offset 续订
+    resub=True, resubscribeInterval=100,
+    filter=np.array(["000905"]),     # 或 lambda 字符串："msg -> select * from msg where sym=`000905"
+    msgAsTable=True, batchSize=2000, throttle=1.0,
+    backupSites=["192.168.1.3:8848"],
+)
+
+from threading import Event
+Event().wait()
+```
+
+- 主题 = `host/port/tableName/actionName`，同 session 不可重名。
+- 取消：`s.unsubscribe(host, port, tableName, actionName)`。
+- backupSites 切换重连时，主备表结构与表名必须完全一致。
+
+## 异步提交
+
+```python
+s = ddb.session(enableASYNC=True)    # 构造期开启异步
+s.connect("localhost", 8848, "admin", "123456")
+s.run("tableInsert{loadTable('dfs://k','tick')}", df)   # 立即返回，不阻塞结果回收
+```
+
+- 异步 session 的 `run` 返回 None，不可用于查询。
+- 高吞吐写入优先用 MTW（已内置异步），异步 session 只在简单"发完即忘"日志/埋点场景用。
+
+## 金融场景典型代码
+
+### 1. 行情高频写入（MTW）
+
+```python
+import dolphindb as ddb
+from dolphindb import MultithreadedTableWriter as MTW
+
+writer = MTW(
+    host="localhost", port=8848, userId="admin", password="123456",
+    dbPath="dfs://market", tableName="tick",
+    batchSize=20000, throttle=1.0, threadCount=4,
+    partitionCol="symbol",
+)
+for row in feed:   # row: [ts, symbol, price, volume]
+    writer.insert(*row)
+writer.waitForThreadCompletion()
+status = writer.getStatus()        # 检查 errorCode / sentRows
+```
+
+### 2. 分钟 K 线批量 ETL（PartitionedTableAppender）
+
+```python
+from dolphindb import DBConnectionPool, PartitionedTableAppender
+pool = DBConnectionPool("localhost", 8848, 8, "admin", "123456")
+appender = PartitionedTableAppender(
+    dbPath="dfs://kline", tableName="min1",
+    partitionColName="trade_date", dbConnectionPool=pool,
+)
+appender.append(df_min1)   # df 中 trade_date 列驱动并行
+pool.shutDown()
+```
+
+## 常见陷阱
+
+1. **`pool.run` 是原生协程**：`await pool.run(...)`，不要 `asyncio.to_thread(pool.run, ...)`，双线程化会卡死。
+2. **pool upload 变量不可见**：连接池每个任务可能走不同物理连接，跨任务共享要走 server 端共享变量 / 共享表。
+3. **session 必须显式 close**：长服务用 `try / finally s.close()`，否则 server 端 worker 不释放，重启服务后会被旧连接占满。
+4. **单消息 500K 行上限**：批量 upload / `run` 超大 DataFrame 会被截断；分批 + `fetchSize`。
+5. **uint 类型转换**：pandas 默认 `uint64` 上传到 DDB 会丢精度，先 `astype('int64')`。
+6. **NaN ↔ NULL**：DDB NULL 是类型化的，`np.nan` 仅适用于 FLOAT/DOUBLE；INT 列要用 `pd.NA` 或 numpy nullable int (`Int64`)，否则上传成 0。
+7. **订阅 batchSize 与 msgAsTable**：`msgAsTable=True` 必须配合 `batchSize > 0`，否则参数无效；若设了 `streamDeserializer`，`msgAsTable` 必须 False。
+8. **多线程同时 connect 高可用模式**：服务端负载信息未同步，所有 session 落到同一节点；改单线程错峰建连或客户端二次轮询。
+9. **enableStreaming 端口**：2.00.9 之前必须传端口且不能被占用；升级到 2.00.9+ 之前要先 unsubscribe，再升级，再重订。
+10. **startup 脚本失败不抛**：构造期 startup 异常被吞，连上后立刻 `s.run("...")` 做一次显式自检。
+
+## 下钻原文
+
+- `references/official/pydoc/BasicOperations/Session/Connect.md` — connect 全参数表
+- `references/official/pydoc/BasicOperations/connection_pool.md` — DBConnectionPool（目录页，详见同目录 connection_pool/）
+- `references/official/pydoc/BasicOperations/table_append.md` — 三种写入对象对比（目录页）
+- `references/official/pydoc/BasicOperations/async_write.md` — 异步写入三种方式对比（目录页）
+- `references/official/pydoc/BasicOperations/Subscription/Subscription.md` — 订阅完整参数与示例
+- `references/official/pydoc/AdvancedOperations/SubscriptionOptions/` — batchSize / msgAsTable / streamDeserializer 组合矩阵

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

@@ -0,0 +1,142 @@
+---
+topic: sql-essentials
+source_files: [official/progr/sql/sql_intro.md, official/progr/sql/Select.md, official/progr/sql/exec.md, official/progr/sql/where.md, official/progr/sql/groupby.md, official/progr/sql/contextBy.md, official/progr/sql/pivotBy.md, official/progr/sql/cgroupby.md, official/progr/sql/having.md, official/progr/sql/orderby.md, official/progr/sql/limit.md, official/progr/sql/top.md, official/progr/sql/join.md, official/progr/sql/equijoin.md, official/progr/sql/leftjoin.md, official/progr/sql/asofjoin.md, official/progr/sql/windowjoin.md, official/progr/sql/interval.md, official/progr/sql/in.md, official/progr/sql/between.md, official/progr/sql/predicates.md, official/progr/sql/exe_order.md]
+generated_at: 2026-05-19
+---
+
+# DolphinDB SQL 核心要点
+
+## 何时用此主题
+
+写 SELECT/JOIN/GROUP BY/分页/排序等基础查询时进来；确认 DolphinDB SQL 与 MySQL/PostgreSQL 写法差异时；写 K 线合成、TopN、时序对齐等金融典型查询时。
+
+## DolphinDB SQL 与标准 SQL 的关键差异
+
+| 特性 | 标准 SQL | DolphinDB |
+|---|---|---|
+| 分页 | `LIMIT count OFFSET m` | `limit offset, count`（顺序反过来） |
+| 取标量/向量 | `SELECT` 一律返回结果集 | `select` 必返回 table，要标量/向量用 `exec` |
+| 分组保留全部行 | window `OVER` | `context by`（每组返回与组内行数等长的向量） |
+| 透视 | 子查询拼装 | `pivot by`（与 select → 表，与 exec → 矩阵） |
+| 累计分组 | window `ROWS UNBOUNDED PRECEDING` | `cgroup by`，必须配 `order by` |
+| 时间最近匹配 | 无 | `aj`（asof join） |
+| 窗口聚合 join | 无 | `wj` / `pwj` |
+| 等距时间分组+插值 | `DATE_TRUNC` + group by | `group by interval(time, 5m, "prev")` |
+| top 写法 | `LIMIT n` | `top n` 或 `top start:end`（左闭右开，只能整型常量） |
+| where `=` / `==` | 仅赋值/比较 | where 中 `==` 等价 `=` |
+| 非等值 join | 支持 | **不支持**（`t1.x > t2.x` 不能写 ON） |
+
+## select / exec 区别
+
+- `select` 永远返回 table（哪怕 1×1）
+- `exec` 单列 → vector；单行单列聚合 → scalar；多列 → table；配 `pivot by` → matrix
+- 查询结果要参与后续标量运算必须 `exec`
+
+## where 子句最佳实践
+
+- `and` / `&&` / `,` 都是与，但 `,` 是**逐条过滤**（先过滤最左，再在结果上过滤下一条），`and` 是**各自过滤再取交集**
+- `or` / `||` 是或
+- `between v1 and v2` ≡ `between v1:v2`（闭区间）
+- `in (v1, v2)` / `in (subquery)` 替代多 or 和子查询
+- 标量子查询：`where col > (select avg(col) from t)`（单行单列 select 自动当标量）
+- 谓词清单：`not` / `is null` / `is not null` / `between and` / `exists` / `in` / `like` / `notLike` / `notBetween` / `notIn`
+- **不能用 select 里 `as` 起的别名**（where 在 select 之前执行），having / order by 才可以
+
+## group by / context by / pivot by / cgroup by 选择
+
+| 场景 | 用什么 |
+|---|---|
+| 分组聚合，每组一行 | `group by` |
+| 分组保留每行（组内累计/ratio/拟合） | `context by` |
+| 透视成二维表（行 × 列） | `pivot by` |
+| 累计分组（含前面所有组） | `cgroup by` + `order by` |
+| 等距时间窗口分组（含插值） | `group by interval(time, 5m, "prev")` |
+
+`context by` 关键点：必配顺序敏感函数（`cumsum` / `mavg` / `ratios` / `deltas` / `first` / `last`）；用 `csort col [asc|desc]` 在组内排序；配 `limit n` / `limit -n` 取每组前/后 n 条；`csort time desc limit 2` = 每组时间最近 2 条。
+
+## window 函数（窗口聚合）
+
+DolphinDB **不用** SQL 标准 `OVER` 语法，改用：
+- `context by` + 滑动函数（`mavg` / `mcount` / `msum` / `mmax`）
+- `wj` / `pwj` 把窗口聚合做成 join
+- 数组向量列用 `rowSum` / `rowMax` 等行级函数
+
+## join 类型
+
+| SQL 关键字 | 函数 | 含义 |
+|---|---|---|
+| `inner join` | `ej` / `sej`（结果排序版） | 等值连接 |
+| `left [outer] join` | `lj` | 右表多行匹配全保留 |
+| `left semijoin` | `lsj` | 右表多行匹配只取首条（行数 = 左表） |
+| `full join` | `fj` | 全外 |
+| `cross join` | `cj` | 笛卡尔积；无 `ON` 的 join 也是 cross |
+| `aj(...)` | asof | 时间最近匹配，右表取 ≤ t 最后一条 |
+| `wj/pwj(...)` | window | 对左表每行取右表 `[t+w1, t+w2]` 应用聚合函数 |
+
+约束：多连接列必须用 `and`（不支持 or）；自连接必须用别名；连接分布式表时分组列必须包含全部分区字段。
+
+## 典型查询模板
+
+K 线合成（5 分钟 OHLCV）：
+```dolphindb
+select first(price) as open, max(price) as high, min(price) as low,
+       last(price) as close, sum(volume) as vol
+from trades
+group by sym, interval(time, 5m, "none")
+```
+
+每只股票 TopN（按成交量取前 3）：
+```dolphindb
+select top 3 * from trades context by sym csort volume desc
+```
+
+trade 对 quote 时序对齐：
+```dolphindb
+select * from aj(trades, quotes, `sym`time)
+```
+
+组内累计与收益率：
+```dolphindb
+select sym, time, price, cumsum(volume) as cumVol, ratios(price)-1 as ret
+from t context by sym csort time
+```
+
+每组最新 1 条（行情快照）：
+```dolphindb
+select * from t context by sym csort time desc limit 1
+```
+
+行情转矩阵：
+```dolphindb
+priceMatrix = exec price from t pivot by time, sym
+```
+
+## 常见陷阱
+
+- `select count(*) from t` 返回 1×1 table；要数字用 `exec count(*) from t`
+- 分页是 `limit offset, count`，不是 `LIMIT count OFFSET offset`
+- `top n`、`top a:b` 只能用整型**常量**，禁止变量/表达式
+- `top` 不能与 `pivot by` 共用；`context by` + `top` 不允许 `top a:b` 范围
+- `csort` 只在配合**序列函数/聚合函数/having/limit** 时真正排序
+- `where` 不能用 select 别名
+- `,` 与 `and` 在边缘场景过滤路径不同
+- `group by` 列**自动加入结果**且排在最前，无需 select 中写
+- `pivot by` 行列重复时默认保最后一条；保全量需 `asis(col)` 且满足 DFS+分区列等多条限制
+- 暂**不支持非等值 join**
+
+## 执行顺序
+
+`from / on` → `where` → `group by` / `context by` / `pivot by` → `csort` → `having` → `select` → `distinct` → （有 `context by`）`limit` → `order by` → （无 `context by`）`limit`
+
+要点：where 在 select 之前 → where 不能用别名；order by 在 select 之后 → 可用别名；有 `context by` 时 limit 作用于每组且在 order by 之前，否则作用于全表且在 order by 之后。
+
+## 下钻原文
+
+- `official/progr/sql/sql_intro.md` — 语法总览与 SQL-92 差异对照
+- `official/progr/sql/exe_order.md` — 子句执行顺序与示例
+- `official/progr/sql/Select.md` / `exec.md` — select vs exec 返回形态
+- `official/progr/sql/contextBy.md` / `groupby.md` / `pivotBy.md` / `cgroupby.md` — 四种分组语义
+- `official/progr/sql/asofjoin.md` / `windowjoin.md` / `equijoin.md` / `leftjoin.md` / `join.md` — 各类 join
+- `official/progr/sql/interval.md` — 等距时间分组与插值
+- `official/progr/sql/predicates.md` / `in.md` / `between.md` — where 谓词
+- `official/progr/sql/top.md` / `limit.md` / `orderby.md` / `having.md` — 分页排序过滤

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

@@ -0,0 +1,141 @@
+# DolphinDB 流计算引擎摘要
+
+定位：DolphinDB 自研的高性能流处理引擎（C++），与时序数据库无缝融合，覆盖实时 ETL、低延时复杂计算、多源关联、流批一体。内置 10+ 流计算引擎，支持金融实时行情、量化因子、IoT 监控等场景。
+
+## 流 vs 批查询对比
+
+| 维度 | 批查询（SQL on DFS） | 流计算（Stream Engine） |
+|------|---------------------|------------------------|
+| 数据源 | 分布式分区表，静态历史数据 | 流数据表（share streamTable），持续追加 |
+| 触发方式 | 用户主动 `select` | 数据写入流表 → 订阅 handler 推送 → 引擎触发 |
+| 计算模式 | 一次性全量 / 批 | 增量、有状态、行/窗口触发 |
+| 结果 | 结果集（返回客户端 / 落表） | 持续写入 outputTable（可级联订阅） |
+| 延迟 | 秒～分钟 | 毫秒～亚毫秒 |
+| 代码 | DolphinDB SQL | 同一套 metrics 表达式（流批一体） |
+
+## 流引擎家族选型
+
+| 引擎 | 场景 | 输入 | 输出 |
+|------|------|------|------|
+| `createTimeSeriesEngine` | 滑动/翻滚时间窗口聚合（K 线、分钟均值） | 带 timeColumn 的流表 | 每个窗口结束触发一行（含 metrics） |
+| `createDailyTimeSeriesEngine` | 股票/期货固定交易时段的时序聚合 | 同上 + sessionStart/End | 每窗口一行，含跨段补齐 |
+| `createSessionWindowEngine` | 按事件活跃度动态划分会话窗口（用户点击、设备脉冲） | 时间列 + sessionGap | 会话结束（gap 超时）触发一行 |
+| `createCrossSectionalEngine` | 截面计算（指数内含值、批设备最值） | 含 keyColumn 的流表（每键最新值） | 按 perRow/perBatch/interval 触发 |
+| `createReactiveStateEngine` | 高频有状态因子（ema 嵌套、累积/topN）；每输入一行输出一行 | 含 keyColumn 的 tick 流 | 与输入同频，含 factor 值 |
+| `createAnomalyDetectionEngine` | 实时异常检测（温度持续上升、阈值越界） | 时间序列流 + 检测条件 | 命中条件触发告警行 |
+| `createAsofJoinEngine` / `createSnapshotJoinEngine` / `createEquiJoinEngine` / `createLookupJoinEngine` / `createLeftSemiJoinEngine` / `createNearestJoinEngine` | 双流/流-维表实时关联（订单匹配快照、报价对齐成交） | 两个流表/键值表 | 关联结果流 |
+| `createCEPEngine` | 复杂事件处理（订单异常模式、设备故障序列） | 事件流 + Monitor DSL | 命中模式发送事件/写表 |
+| `streamEngineParser` | SQL → 自动拆解多引擎链路 | 含窗口/聚合/状态的 SQL | 自动 outputTable 串接 |
+
+## 引擎链路（级联）
+
+两种串法：
+
+1. **显式串接**：A 引擎的 `outputTable` 是一个 `share streamTable`，B 引擎 `subscribeTable` 该流表 → handler 调 `append!{B}`。
+2. **streamEngineParser 自动拆解**：用 SQL 描述复杂计算，parser 自动识别窗口/状态算子并组装多级引擎，省去手工链路。
+
+示例（时序引擎 → 横截面引擎）：流表 `electricity` → `createTimeSeriesEngine` 滑动均值 → 写入 `outputTable1`（share streamTable） → 再用 `createReactiveStateEngine` 订阅 `outputTable1` 计算移动峰值。
+
+## 流订阅核心 API
+
+DolphinDB 服务端：
+
+```dolphindb
+// 1. 流表必须 share，否则订阅看不到
+share streamTable(1000:0, `time`sym`price`qty, [TIMESTAMP,SYMBOL,DOUBLE,INT]) as trades
+
+// 2. 创建引擎（以时序聚合为例）
+outputTable = table(10000:0, `time`sym`open`high`low`close`vol,
+                    [TIMESTAMP,SYMBOL,DOUBLE,DOUBLE,DOUBLE,DOUBLE,LONG])
+eng = createTimeSeriesEngine(name="kline1min", windowSize=60000, step=60000,
+        metrics=<[first(price), max(price), min(price), last(price), sum(qty)]>,
+        dummyTable=trades, outputTable=outputTable,
+        timeColumn=`time, keyColumn=`sym)
+
+// 3. 订阅流表 → handler 喂引擎
+subscribeTable(tableName="trades", actionName="kline1min_sub",
+               offset=-1, handler=append!{eng}, msgAsTable=true)
+```
+
+Python API：
+
+```python
+import dolphindb as ddb
+s = ddb.session()
+s.connect("127.0.0.1", 8848, "admin", "123456")
+s.enableStreaming(9999)  # 本机监听端口
+
+def handler(msg):
+    print(msg)  # msg 为 list 或 DataFrame，取决于 msgAsTable
+
+s.subscribe(host="127.0.0.1", port=8848, handler=handler,
+            tableName="outputTable", actionName="py_sub",
+            offset=0, msgAsTable=True)
+```
+
+清理：`unsubscribeTable(,tableName, actionName)` → `dropStreamEngine(name)` → `undef(\`tableName, SHARED)`。
+
+## 流批一体（replay）
+
+`replay` 把历史数据按 timeColumn 还原成流速注入流表，复用同一套 metrics/引擎代码做回测：
+
+- 历史回测：`replay(inputTables, outputTables, dateColumn, timeColumn, replayRate, parallelLevel)` → 引擎接到的数据顺序与实盘一致。
+- 同一份因子表达式在批 SQL（`select metrics ... context by sym`）和流引擎中产出完全相同的值，校验便捷。
+
+## 典型范式：tick → 1 分钟 K 线
+
+```dolphindb
+share streamTable(1000000:0, `time`sym`price`qty,
+                  [TIMESTAMP, SYMBOL, DOUBLE, INT]) as trades
+
+outputTable = table(100000:0,
+    `time`sym`open`high`low`close`volume,
+    [TIMESTAMP, SYMBOL, DOUBLE, DOUBLE, DOUBLE, DOUBLE, LONG])
+
+klineEng = createTimeSeriesEngine(
+    name        = "kline_1min",
+    windowSize  = 60000,      // 60s
+    step        = 60000,      // 翻滚（非滑动）
+    metrics     = <[first(price), max(price), min(price), last(price), sum(qty)]>,
+    dummyTable  = trades,
+    outputTable = outputTable,
+    timeColumn  = `time,
+    keyColumn   = `sym        // 按股票分组
+)
+
+subscribeTable(
+    tableName  = "trades",
+    actionName = "kline_1min_sub",
+    offset     = -1,
+    handler    = append!{klineEng},
+    msgAsTable = true
+)
+```
+
+要切成滑动 K 线，把 `step` 改小于 `windowSize`（如 `step=10000, windowSize=60000` → 每 10s 输出近 1 分钟 K 线）。
+
+## 常见陷阱
+
+- **流表必须 `share`**：未 share 的 streamTable 订阅不到，且重启 session 即丢失；命名 `share ... as name`。
+- **忘记清理订阅**：重复执行同一脚本前必须 `unsubscribeTable + dropStreamEngine + undef`，否则报 `engine already exists` / `subscription already exists`。
+- **流计算函数限制**：响应式状态引擎只支持「状态函数」（内置滑窗/累积/topN 或 `@state` 修饰的自定义函数）；普通自定义函数若有状态依赖必须显式声明 `@state`。
+- **不支持聚合嵌套**：时序引擎 `metrics` 中禁止 `sum(spread(ask,bid))` 这种聚合套聚合。
+- **窗口边界规整**：第一个窗口起点按数据时间向 step 取整（不是数据到达时间）；窗口结束需要后续数据触发，最后一个不完整窗口不会被计算（除非用 `forceTriggerTime` / `closed=\`left` 等参数）。
+- **Python 订阅端口**：`enableStreaming(port)` 监听的是**客户端**端口，需保证防火墙放行 server → client 方向；否则订阅创建成功但 handler 收不到数据。
+- **offset 含义**：`-1` = 从订阅当下最新位置开始；`0` = 从流表第一条开始；正整数 = 从该位置开始。回测/补数据用 `0`，实盘用 `-1`。
+- **outputTable 类型**：普通 table → 终点；share streamTable → 可被下游引擎再订阅串接。
+
+## 下钻原文
+
+- `references/official/stream/str_intro.md` — 流数据总览与核心特性
+- `references/official/stream/time_series_engine.md` — 时序聚合引擎完整用法
+- `references/official/stream/cross_sectional_engine.md` — 横截面引擎与触发模式
+- `references/official/stream/reactive_state_engine.md` — 响应式状态引擎与高频因子
+- `references/official/stream/session_window_engine.md` — 会话窗口引擎
+- `references/official/stream/anomaly_detection_engine.md` — 异常检测引擎
+- `references/official/stream/cep.md` / `cep_engine.md` / `cep_basic_concept.md` — CEP 复杂事件处理
+- `references/official/stream/str_join_engine.md` / `asof_join_engine.md` / `snapshot_join_engine.md` — 流连接系列
+- `references/official/stream/str_replay.md` / `str_replay_n21.md` / `str_replay_n2n.md` — 历史 replay
+- `references/official/stream/str_eng_parser.md` — streamEngineParser 自动拆解
+- `references/official/stream/str_api_python.md` / `py_sub.md` — Python 订阅 API
+- `references/official/stream/str_table.md` / `share` / `subscribeTable` 文档 — 流表与订阅基础