dolphindb 2.0.918 → 2.0.920

package/docs.zh.json

@@ -1746,7 +1746,7 @@
                         "value": [
                             "`left`/`right` 包含标签的矩阵/索引矩阵/索引序列。",
                             "",
-                            "`how` 矩阵的对齐方法。通过将矩阵的行列标签进行 join 操作，来实现标签对齐。可选值为：'outer' (or 'fj'), 'inner' (or 'fj'), 'left' (or 'fj'), 'asof' or 'asof ('aj')'，表示不同的连接方式。默认值是 'outer'，即外连接。",
+                            "`how` 矩阵的对齐方法。通过将矩阵的行列标签进行 join 操作，来实现标签对齐。可选值为：'outer' (or 'fj'), 'inner' (or 'ej'), 'left' (or 'lj'), or 'asof ('aj')'，表示不同的连接方式。默认值是 'outer'，即外连接。",
                             "",
                             "`byRow` 布尔值或空值。若为 true，表示按行标签对齐；若为 false，表示按列标签对齐。默认为空值，表示同时按照行列标签对齐。此时，若行、列的连接方式相同，how 需指定一个连接方式；否则，how 需指定两个连接方式，格式为\"行对齐方式,列对齐方式\"，例如 how=\"outer,inner\"。注意：逗号前后不能有空格或其他符号。",
                             "",
@@ -12885,7 +12885,7 @@
                     {
                         "type": "text",
                         "value": [
-                            "创建流数据 asof join 引擎。返回一个左、右两表 as join 后的表对象。注入 asof join 引擎的左、右两表将以 :ref:`matchingColumn <mc_aj>` + :ref:`timeColumn <tc_aj>` (或系统时间) 作为连接列，在右表中选取与连接列匹配的，在给定的左表时间戳前且最接近的记录。该引擎适用于两个数据源没有完全匹配的记录，需要按时间段作连接，以获取最新信息的场景。",
+                            "创建流数据 asof join 引擎。返回一个左、右两表 asof join 后的表对象。注入 asof join 引擎的左、右两表将以 :ref:`matchingColumn <mc_aj>` + :ref:`timeColumn <tc_aj>` (或系统时间) 作为连接列，在右表中选取与连接列匹配的，在给定的左表时间戳前且最接近的记录。该引擎适用于两个数据源没有完全匹配的记录，需要按时间段作连接，以获取最新信息的场景。",
                             "",
                             "注意：asof join 左表和右表的数据必须按照时间顺序排序。",
                             "",
@@ -12910,9 +12910,7 @@
                             "",
                             ".. _table_aj:",
                             "",
-                            "`leftTable` 表对象。可以不包含数据，但结构必须与订阅的流数据表相同。",
-                            "",
-                            "`rightTable` 表对象。可以不包含数据，但结构必须与订阅的流数据表相同。",
+                            "`leftTable` 和 `rightTable` 表对象。结构必须与订阅的流数据表相同。",
                             "",
                             ".. _outputTable_aj:",
                             "",
@@ -12958,17 +12956,15 @@
                             "",
                             "* 当 *useSystemTime* = true 时，按照数据进入引擎的时刻（毫秒精度的本地系统时间，与数据中的时间列无关）进行计算。",
                             "",
-                            "* 当 *useSystemTime* = false（缺省值）时，按照数据中的时间列进行计算。请注意，触发计算的数据并不会参与该次计算。",
+                            "* 当 *useSystemTime* = false（缺省值）时，按照数据中的时间列进行计算。",
                             "",
                             ".. _delayedTime_aj:",
                             "",
-                            "`delayedTime` 可选参数，正整数，单位同 timeColumn 精度一致。要设置 *delayedTime*， 必须指定 *timeColumn*。",
-                            "",
-                            "如果指定了 *delayedTime*，若左表中最新到来的数据时间与左表之前未计算的数据时间差大于 *delayedTime* 设置值，则这条数据可以直接触发左表和右表 join，或左表中的数据在经过 2 \\* *delayedTime* （小于2秒按2秒计算）后还没有 join 输出，则直接触发 join。",
+                            "`delayedTime` 可选参数，正整数，单位同 timeColumn 精度一致。表示左表中未联结数据被触发联结并计算输出的最大等待时间。要设置 *delayedTime*， 必须指定 *timeColumn*，更多介绍见详情。",
                             "",
                             ".. _garbageSize_aj:",
                             "",
-                            "`garbageSize` 可选参数，正整数，默认值是 5,000（单位为行）。随着订阅的流数据不断注入 asof join  引擎，存放在内存中的数据会越来越多，当左/右两表根据 *matchingCol* 分组后的各个分组内的数据行数超过 *garbageSize* 值时，系统会清理本次计算不需要的历史数据。",
+                            "`garbageSize` 可选参数，正整数，默认值是 5,000（单位为行）。随着订阅的流数据不断注入 asof join  引擎，存放在内存中的数据会越来越多，当各分组对应的缓存表（左表或右表）中数据行数超过 *garbageSize* 值时，系统会清理该表中已经触发计算的历史数据。",
                             ""
                         ]
                     }
@@ -13988,7 +13984,7 @@
                             "",
                             ".. _maxDelayedTime_ej:",
                             "",
-                            "`maxDelayedTime` 可选参数，正整数，单位同 timeColumn 精度一致，默认值为 3 秒。该参数仅在达到 *garbageSize* 清理条件时才会起效，表示引擎内能够保留最新多长时间的数据。详情参考上述清理条件 2。不建议设置 *maxDelayedTime* 值设置过小。"
+                            "`maxDelayedTime` 可选参数，正整数，单位同 timeColumn 精度一致，默认值为 3 秒。该参数仅在达到 *garbageSize* 清理条件时才会起效，表示引擎内能够保留最新多长时间的数据。详情参考上述清理条件 2。不建议设置 *maxDelayedTime* 值设置过小，否则可能导致一些需关联却没及时关联的数据被清理。"
                         ]
                     }
                 ]
@@ -14408,7 +14404,7 @@
                         "type": "text",
                         "value": [
                             "创建流数据表的 lookup join 引擎，该引擎以 :ref:`matchingColumn <matchingColumnLJ>` 作为连接列将两个流数据表进行实时 :doc:`/SQLStatements/TableJoiners/leftjoin`，",
-                            "或者将流数据表和非流数据表进行 left join（此时需要定时刷新非流表）。lookup join 引擎常用于右表更新不频繁的场景。",
+                            "或者将流数据表和非流数据表进行 left join（此时需要定时刷新非流表）。lookup join 引擎常用于右表更新不频繁的场景（如保存了日频指标的维度表）。",
                             "",
                             "工作机制：",
                             "",
@@ -14419,11 +14415,11 @@
                             "",
                             "lookup join 引擎实际采用 left join 的连接方式，但与 left join 不完全等价，区别在于：如果右表中有多条匹配记录，left join 会返回右表所有匹配的记录，但 lookup join 引擎只返回右表最新一条匹配的记录。",
                             "",
-                            "lookup join 引擎与 asof jion 引擎很相似，它们之间的区别与联系如下：",
+                            "lookup join 引擎与 asof join 引擎很相似，它们之间的区别如下：",
                             "",
                             "lookup join 引擎输出表的第一列可以不是时间列，而 asof join 引擎输出表第一列必须是时间列。",
                             "",
-                            "lookup join 引擎当左表有新数据流入便会触发 jion 输出，因此无需考虑数据延迟，也无需缓存数据。而 asof join 引擎，当指定 timeColumn 时，需要考虑左右表的数据延时，因此需要缓存数据。",
+                            "lookup join 引擎当左表有新数据流入便会触发 join 输出，因此无需考虑数据延迟，也无需缓存左表数据。而 asof join 引擎，当指定 timeColumn 时，需要考虑左右表的数据延时。",
                             "",
                             "更多流数据引擎的应用场景说明可以参考 :doc:`../../SeriesOfFunctions/streamingEngine`。"
                         ]
@@ -16273,22 +16269,7 @@
                             "",
                             "   \\1. 当前窗口数据的计算将由该窗口结束后的第一条数据触发。触发计算的数据不参与该窗口的计算。",
                             "",
-                            "   \\2. 指定 :ref:`maxDelayedTime <maxDelayedTimeWJ>` 后，对于某个未发生计算的窗口右，若其窗口边界 + *maxDelayedTime* < 右表最新收到的任意一个分组数据的时间戳，则该窗口的计算将被新收到的这条数据触发。",
-                            "",
-                            ".. versionadded:: 1.30.20",
-                            "   特殊窗口规则",
-                            "",
-                            "* *特殊窗口（window 指定为 0:0，此时不支持指定 maxDelayedTime）*：",
-                            "",
-                            "   右表的计算窗口将左表当前数据和其上一条数据的时间戳决定。假设左表当前记录的时间戳为 t，上一条记录的时间戳为 t0，则由左表当前记录时间戳确定的右表计算窗口为 [t0, t)。",
-                            "",
-                            "   触发规则：",
-                            "",
-                            "   * 当 useSystemTime=false 时，计算将由窗口结束后的第一条右表数据触发。",
-                            "",
-                            "   * 当 useSystemTime=true 时，左表每注入一条数据，就触发右表未计算数据的计算。",
-                            "",
-                            "   注意：window=0:0 时，若 metrics 中指定了非聚合的指标，其输出列必须为对应类型的 array vector。",
+                            "   \\2. 指定 :ref:`maxDelayedTime <maxDelayedTimeWJ>` 后，对于某个未发生计算的窗口，若其窗口右边界 + *maxDelayedTime* < 右表最新收到的任意一个分组数据的时间戳，则该窗口的计算将被新收到的这条数据触发。",
                             "",
                             "更多流数据引擎的应用场景说明可以参考 :doc:`../../SeriesOfFunctions/streamingEngine`。"
                         ]
@@ -16352,7 +16333,7 @@
                             "",
                             ".. _maxDelayedTimeWJ:",
                             "",
-                            "`maxDelayedTime` 可选参数，是正整数,默认值为3，单位为秒。通过设置该参数，帮助触发引擎中长时间未输出的分组数据进行计算。",
+                            "`maxDelayedTime` 可选参数，是正整数，默认值为3，单位为秒。通过设置该参数，帮助触发引擎中长时间未输出的分组数据进行计算。",
                             "即若右表中最新到来的数据时间戳 - 未计算的分组数据窗口的右边界 > maxDelayedTime，则这条数据会触发满足条件的分组数据窗口计算输出。",
                             "请注意，指定该参数时，必须同时指定 timeColumn，且单位需和 timeColumn 精度一致。",
                             "",
@@ -67601,7 +67582,7 @@
                             "",
                             "    请注意：",
                             "    ",
-                            "    * 若 *X* 不能被均分，多余元素优先存入编号较小的组内。",
+                            "    * 若 *X* 不能被均分，编号较小的组将多存放一个元素。例如 *X* 的元素个数为6，*groupNum* = 4，对 *X* 排序后，第1和2个元素属于组0，第3和4个元素属于组1，第5个和第6个元素分别属于组2和组3。",
                             "    * 若 *X* 中相同元素分别属于不同的组，则所有相同元素返回最小的组号。",
                             "* 如果 *ignoreNA* = true，则 NULL 值不参与排序，结果中 NULL 值的排名为空。",
                             "",
@@ -67632,6 +67613,9 @@
                             "    $ rank(X=9 5 4 8 1 3 6 2 7, groupNum=3);",
                             "    [2,1,1,2,0,0,1,0,2]",
                             "",
+                            "    $ rank(X=9 5 4 8 1 3 6 2 7, groupNum=6)",
+                            "    [5,2,1,4,0,1,2,0,3]",
+                            "",
                             "    $ rank(X=9 5 4 8 1 3 6 2 7, ascending=false, groupNum=3);",
                             "    [0,1,1,0,2,2,1,2,0]",
                             "",
@@ -93668,7 +93652,7 @@
                     {
                         "type": "text",
                         "value": [
-                            "如果X是一个元组，每个向量的长度必须相同，*tranpose* 函数返回的是一个与X中每个向量长度相同的元组，返回结果中的第n个元素是由X中每个向量的第n个值组成的向量。",
+                            "如果X是一个元组，每个向量的长度必须相同，*transpose* 函数返回的是一个与X中每个向量长度相同的元组，返回结果中的第n个元素是由X中每个向量的第n个值组成的向量。",
                             "",
                             "如果X是一个矩阵，*transpose* 函数返回X的转置矩阵。",
                             "",

package/i18n/dict.json

@@ -67,5 +67,8 @@
     },
     "已断开": {
         "en": "is already disconnected"
+    },
+    "连接出错了，可能由于网络原因连接已被关闭，或服务器断开连接": {
+        "en": "connection errored. The connection may have been closed due to network reasons, or the server disconnected"
     }
 }

package/index.js

@@ -4,7 +4,7 @@ import DayjsCustomParseFormat from 'dayjs/plugin/customParseFormat.js';
 dayjs.extend(DayjsCustomParseFormat);
 import ipaddrjs from 'ipaddr.js';
 const { fromByteArray: buf2ipaddr } = ipaddrjs;
-import { concat, assert, inspect, typed_array_to_buffer, connect_websocket, WebSocket } from 'xshell';
+import { concat, assert, inspect, typed_array_to_buffer, connect_websocket, WebSocket, WebSocketConnectionError } from 'xshell';
 import { t } from './i18n/index.js';
 export var DdbForm;
 (function (DdbForm) {
@@ -2109,7 +2109,10 @@ export class DdbConnectionError extends Error {
     name = 'DdbConnectionError';
     ddb;
     constructor(ddb, error_options) {
-        super(`${ddb.url} ${t('已断开')}`, error_options);
+        super(error_options?.cause ?
+            error_options.cause.message
+            :
+                `${ddb.url} ${t('连接出错了，可能由于网络原因连接已被关闭，或服务器断开连接')}`, error_options);
         this.ddb = ddb;
     }
 }
@@ -2204,7 +2207,7 @@ export class DDB {
         if (options.streaming !== undefined)
             this.streaming = options.streaming;
     }
-    on_message(event) {
+    on_message(buffer) {
         // 这里的实现一定会被 connect 中的实现覆盖
     }
     /** 建立实际的 WebSocket 连接到 URL 对应的 DolphinDB  Establish a actual websocket connection to the DolphindB corresponding to the URL
@@ -2221,22 +2224,30 @@ export class DDB {
         await ptail;
         try {
             if (!this.connected) {
-                this.on_message = (event) => {
+                this.on_message = buffer => {
                     assert(false, t('这是在调用 this.rpc 之前默认的 on_message, 不应该被调用到，除非建立连接后 server 先推送了 message'));
                 };
                 this.presult = Promise.resolve(null);
                 this.pnode_run_defined = false;
-                this.websocket = await connect_websocket(this.url, {
-                    protocols: (() => {
-                        if (this.streaming)
-                            return 'streaming';
-                        if (this.python)
-                            return 'python';
-                    })(),
-                    on_message: (event) => {
-                        this.on_message(event);
-                    }
-                });
+                try {
+                    this.websocket = await connect_websocket(this.url, {
+                        protocols: (() => {
+                            if (this.streaming)
+                                return 'streaming';
+                            if (this.python)
+                                return 'python';
+                        })(),
+                        on_message: (buffer) => {
+                            this.on_message(buffer);
+                        }
+                    });
+                }
+                catch (error) {
+                    if (error instanceof WebSocketConnectionError)
+                        throw new DdbConnectionError(this, { cause: error });
+                    else
+                        throw error;
+                }
                 if (this.streaming)
                     await this.subscribe();
                 else {
@@ -2373,7 +2384,7 @@ export class DDB {
         }
         catch { }
         // 临界区结束，只有一个 rpc 函数调用运行到这里，可以独占 this.on_message 然后写 WebSocket
-        this.on_message = ({ data: buffer }) => {
+        this.on_message = buffer => {
             try {
                 const buf = new Uint8Array(buffer);
                 if (this.print_message_buffer)
@@ -2597,7 +2608,7 @@ export class DDB {
             segments: [],
         };
         // 先准备好收到 websocket message 的 callback
-        this.on_message = ({ data: buffer }) => {
+        this.on_message = buffer => {
             let { streaming } = this;
             try {
                 const dv = new DataView(buffer);