dolphindb 3.1.56 → 3.1.58

package/README.md

@@ -611,8 +611,24 @@ After the connection is established, the received streaming data will be called
 ```ts
 export interface StreamingParams {
     table: string
+    
     action?: string
     
+    /** offset is the position of the first message after the subscription task starts. A message is a row in the stream table.
+        If not specified, or set to -1, the subscription starts from the current row of the stream table.
+        If offset = -2, the system retrieves the offset persisted to disk and starts the subscription from that position. Note: persistOffset = true must be set at the same time for offset = -2 to take effect; otherwise offset becomes -1.
+        offset corresponds to the first row when the stream table was created. If some rows have been deleted due to memory limits, they are still taken into account when determining the position to start the subscription. */
+    offset?: number
+    
+    filters?: {
+        /** Needs to be used together with the setStreamTableFilterColumn function
+            https://docs.dolphindb.cn/en/funcs/s/subscribeTable.html */
+        column?: DdbObj
+        
+        /** DolphinDB expression of the filter condition */
+        expression?: string
+    }
+    
     handler (message: StreamingMessage): any
 }
 
@@ -647,6 +663,37 @@ export interface StreamingMessage <TRows = any> extends StreamingParams {
 }
 ```
 
+#### Example of using the filters option
+
+With the `filters` option, filter conditions can be constructed on the js side, so that only streaming data satisfying the conditions is received
+
+Before subscribing, you need to execute `setStreamTableFilterColumn` on the stream table on the server side to specify the filter column, e.g.: `setStreamTableFilterColumn(table_name, 'sym')`
+
+```ts
+import { DdbVectorSymbol } from 'dolphindb'
+
+let sddb = new DDB('ws://127.0.0.1:8848', {
+    autologin: true,
+    streaming: {
+        table: 'name of the stream table to subscribe to',
+        
+        filters: {
+            // Construct the filter column values (DdbObj) on the js side, corresponding to the filter parameter of subscribeTable
+            // Here only rows whose sym column value is 'aaa' or 'bbb' are received. If the filter column is of other types, use DdbVectorInt, etc.
+            column: new DdbVectorSymbol(['aaa', 'bbb']),
+        },
+        
+        // Stream data processing callback
+        handler (message) {
+            console.log(message)
+        }
+    }
+})
+
+// Start subscription
+await sddb.connect()
+```
+
 To close streaming data subscription, use the following two methods to disconnect:
 - Automatically disconnect by closing the browser page
 - Manually disconnect by calling `sddb.disconnect()`

package/README.zh.md

@@ -591,8 +591,24 @@ await sddb.connect()
 ```ts
 export interface StreamingParams {
     table: string
+    
     action?: string
     
+    /** offset 是订阅任务开始后的第一条消息所在的位置。消息是流数据表中的行。
+        如果未指定，或设为 -1，订阅将会从流数据表的当前行开始。
+        如果 offset = -2，系统会获取持久化到磁盘上的 offset，并从该位置开始订阅。注意：须同时设置 persistOffset = true，offset = -2 才会生效；否则 offset 会变为 -1。
+        offset 与流数据表创建时的第一行对应。如果某些行因为内存限制被删除，在决定订阅开始的位置时，这些行仍然考虑在内。 */
+    offset?: number
+    
+    filters?: {
+        /** 需要配合 setStreamTableFilterColumn 函数一起使用
+            https://docs.dolphindb.cn/zh/funcs/s/subscribeTable.html */
+        column?: DdbObj
+        
+        /** 过滤条件的 DolphinDB 表达式 */
+        expression?: string
+    }
+    
     handler (message: StreamingMessage): any
 }
 
@@ -627,6 +643,37 @@ export interface StreamingMessage <TRows = any> extends StreamingParams {
 }
 ```
 
+#### 使用 filters 选项的例子
+
+通过 `filters` 选项可以在 js 侧构造过滤条件，只接收满足条件的流数据
+
+需要事先在服务器端对被订阅的流表执行 `setStreamTableFilterColumn` 指定过滤列，例如: `setStreamTableFilterColumn(table_name, 'sym')`
+
+```ts
+import { DdbVectorSymbol } from 'dolphindb'
+
+let sddb = new DDB('ws://127.0.0.1:8848', {
+    autologin: true,
+    streaming: {
+        table: '要订阅的流表名称',
+        
+        filters: {
+            // 在 js 侧构造过滤列值 (DdbObj), 对应 subscribeTable 的 filter 参数
+            // 这里只接收 sym 列值为 'aaa' 或 'bbb' 的行, 过滤列是其它类型时可换用 DdbVectorInt 等
+            column: new DdbVectorSymbol(['aaa', 'bbb']),
+        },
+        
+        // 流数据处理回调
+        handler (message) {
+            console.log(message)
+        }
+    }
+})
+
+// 开始订阅
+await sddb.connect()
+```
+
 关闭流数据订阅使用下面两种断开连接的方法
 - 关闭浏览器页面自动断开连接
 - 调用 `sddb.disconnect()` 手动断开连接

package/browser.d.ts

@@ -52,6 +52,12 @@ export interface DdbChartValue {
         auto_scale_y_axes?: boolean;
     };
     data: DdbMatrixObj;
+    /** 箱线图 (Boxplot) 的离群点，服务端 plot(chartType = BOXPLOT) 返回的 chart 可能具有该属性
+        原属性 outliers
+        N×2 矩阵，每行为 [序列编号, 离群点值]，序列编号从 0 开始，对应 data 的行号
+        data 每行为一个箱子的 [下须, Q1, median, Q3, 上须]，首尾值为须端点 (服务端按 whis = 1.5 计算)
+        无离群点时为 0×2 矩阵  */
+    outliers?: DdbMatrixObj;
 }
 export type DdbValue = DdbScalarValue | DdbVectorValue | DdbMatrixValue | DdbDictValue | DdbChartValue | DdbTensorValue | DdbExtObjValue;
 export type DdbStringObj = DdbObj<string>;
@@ -656,8 +662,8 @@ export declare class BigInt128Array {
             value: bigint;
             done: boolean;
         } | {
-            done: boolean;
             value?: undefined;
+            done: boolean;
         };
     };
     toString(): string;

package/browser.js

@@ -158,7 +158,7 @@ export class DdbObj {
                 if (form === DdbForm.dict)
                     return dict;
                 else {
-                    const { chartType: type, stacking, binStart: bin_start, binEnd: bin_end, binCount: bin_count, title: titles, extras, data, ...others } = dict.to_dict();
+                    const { chartType: type, stacking, binStart: bin_start, binEnd: bin_end, binCount: bin_count, title: titles, extras, data, outliers, ...others } = dict.to_dict();
                     const [chart, x_axis, y_axis, z_axis] = titles.value;
                     dict.form = DdbForm.chart;
                     dict.value = {
@@ -174,6 +174,7 @@ export class DdbObj {
                         ...bin_count ? { bin_count } : {},
                         ...extras ? { extras: map_keys(extras.data()) } : {},
                         data,
+                        ...outliers ? { outliers } : {},
                         ...others,
                     };
                     return dict;
@@ -941,7 +942,7 @@ export class DdbObj {
                 case DdbForm.dict:
                     return [value[0].pack(), value[1].pack()];
                 case DdbForm.chart: {
-                    const { type, stacking, bin_start, bin_end, bin_count, titles: { chart, x_axis, y_axis, z_axis }, extras, data } = this.value;
+                    const { type, stacking, bin_start, bin_end, bin_count, titles: { chart, x_axis, y_axis, z_axis }, extras, data, outliers } = this.value;
                     const { value: [keys, values] } = new DdbDict({
                         chartType: new DdbInt(type),
                         stacking,
@@ -950,6 +951,7 @@ export class DdbObj {
                         title: new DdbVectorString([chart, x_axis, y_axis, z_axis]),
                         ...extras ? { extras: new DdbDict(map_keys(extras, to_lower_camel_case)) } : {},
                         data,
+                        ...outliers ? { outliers } : {},
                     });
                     return [keys.pack(), values.pack()];
                 }