DolphinDB JavaScript API

English | 中文

简介

DolphinDB JavaScript API 是一个 JavaScript 库，封装了操作 DolphinDB 数据库的能力，如：连接数据库、执行脚本、调用函数、上传变量等

https://www.npmjs.com/package/dolphindb

特性

- 使用 WebSocket 与 DolphinDB 数据库通信，用二进制格式进行数据交换，支持流数据实时推送
- 支持在浏览器环境和 Node.js 环境中运行
- 使用了 JavaScript 中的 Int32Array 等 TypedArray 处理二进制数据，性能较高
- 单次调用支持最大 2 GB 数据的序列化上传，下载数据量不受限制

用法

$3

#### 方法一：在浏览器中直接使用构建好的 CDN 版本

保存以下内容到 example.html 文件，用浏览器打开即可运行，F12 打开调试控制台可以看到日志

``html










`

#### 方法二：在项目中安装 npm 包并导入

##### 1. 安装

1.1. 在机器上安装最新版的 Node.js 及浏览器。
- windows: https://nodejs.org/en/download/prebuilt-installer/current
- linux: https://github.com/nodesource/distributions?tab=readme-ov-file#debian-and-ubuntu-based-distributions

1.2. （可选）使用以下命令创建新项目。如果已有项目，可跳过此步。
`bash
mkdir dolphindb-example
cd dolphindb-example
npm init --yes
`

1.3. 用编辑器打开 package.json 文件，在 "main": "./index.js" 下方加入一行 "type": "module", 这样能够启用 ECMAScript modules，在后面代码中可以使用 import { DDB } from 'dolphindb' 导入 npm 包。

1.4. 在项目中安装 npm 包。
`bash
npm install dolphindb
`

##### 2. 使用

`ts
// 2.1 在浏览器环境中用下面的方法导入
import { DDB } from 'dolphindb/browser.js'

// 2.1 在 Node.js 环境中用下面的方法导入
// import { DDB } from 'dolphindb'
// 已有的使用 CommonJS 模块的项目的导入方法为 const { DDB } = await import('dolphindb')

// 2.2 使用 WebSocket URL 初始化连接到 DolphinDB 的实例（不建立实际的网络连接）
let ddb = new DDB('ws://127.0.0.1:8848')

// 使用 HTTPS 加密
// let ddb = new DDB('wss://dolphindb.com')

// 2.3 调用 DolphinDB add 函数，调用时自动连接到数据库（要求 DolphinDB 数据库版本不低于 1.30.16 或 2.00.4）
console.log(await ddb.invoke('add', [1, 2])) // 输出 3

// 2.4 使用完毕，断开连接释放资源
ddb.disconnect()
`

#### 代码补全、函数提示数据
- https://cdn.dolphindb.cn/assets/docs.zh.json
- https://cdn.dolphindb.cn/assets/docs.en.json


#### DDB 连接选项

`ts
let ddb = new DDB('ws://127.0.0.1:8848', {
// 是否在建立连接后自动登录，默认 true
autologin: true,

// DolphinDB 登录用户名，默认 'admin'
username: 'admin',

// DolphinDB 登录密码，默认 '123456'
password: '123456',

// 设置 python session flag，默认 false
python: false,

// 设置当前会话执行的 sql 标准, 请使用 SqlStandard 枚举进行传参，默认 DolphinDB
// sql: SqlStandard.MySQL,
// sql: SqlStandard.Oracle,

// 设置该选项后，该数据库连接只用于流数据，详细用法见后文 5. 流数据
streaming: undefined
})
`




$3


#### invoke 方法
##### invoke 方法代码示例
`ts
const result = await ddb.invoke('add', [1, 1])
// TypeScript: const result = await ddb.invoke('add', [1, 1])

console.log(result === 2) // true
`

上面例子中，上传了两个参数 1 (对应 DolphinDB 中的 int 类型) 到 DolphinDB 数据库，作为 add 函数的参数，并接收函数调用的结果 result

用于 TypeScript 推断返回值的类型

##### invoke 方法声明
`ts
/* 调用 dolphindb 函数，传入 js 原生数组作为参数，返回 js 原生对象或值（调用 DdbObj.data() 后的结果）/
async invoke (
/* 函数名 /
func: string,

/* [ ] 调用参数，可以是 js 原生数组 /
args?: any[],

/* 调用选项 /
options?: {
/* 紧急 flag。使用 urgent worker 执行，防止被其它作业阻塞 /
urgent?: boolean

/* 设置结点 alias 时发送到集群中对应的结点执行 (使用 DolphinDB 中的 rpc 方法) /
node?: string

/* 设置多个结点 alias 时发送到集群中对应的多个结点执行 (使用 DolphinDB 中的 pnodeRun 方法) /
nodes?: string[]

/* 设置 node 参数且参数数组为空时必传，需指定函数类型，其它情况下不传 /
func_type?: DdbFunctionType

/* 设置 nodes 参数时选传，其它情况不传 /
add_node_alias?: boolean

/* 处理本次 rpc 期间的消息 (DdbMessage) /
listener?: DdbMessageListener
} = { }
): Promise
`

#### call 方法
##### call 方法代码示例
`ts
import { DdbInt } from 'dolphindb'

const result = await ddb.call('add', [new DdbInt(1), new DdbInt(1)])
// TypeScript: const result = await ddb.call('add', [new DdbInt(1), new DdbInt(1)])

console.log(result.value === 2) // true
`

###### 用 DdbObj 对象来表示 DolphinDB 中的数据类型

上面例子中，上传了两个参数 1 (对应 DolphinDB 中的 int 类型) 到 DolphinDB 数据库，作为 add 函数的参数，并接收函数调用的结果 result

用于 TypeScript 推断返回值的类型

- result 是一个 DdbInt，也是 DdbObj
- result.form 是 DdbForm.scalar
- result.type 是 DdbType.int
- result.value 是 JavaScript 中原生的 number (int 的取值范围及精度可以用 JavaScript 的 number 准确表示)

建议先了解一下 JavaScript 中的 TypedArray 相关的概念，可以参考:
https://stackoverflow.com/questions/42416783/where-to-use-arraybuffer-vs-typed-array-in-javascript
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray

`ts
/* 可以表示所有 DolphinDB 数据库中的数据类型 /
class DdbObj {
/* 是否为小端 (little endian) /
le: boolean

/* 数据形式 https://www.dolphindb.cn/cn/help/DataTypesandStructures/DataForms/index.html /
form: DdbForm

/* 数据类型 https://www.dolphindb.cn/cn/help/DataTypesandStructures/DataTypes/index.html /
type: DdbType

/* 占用 parse 时传入的 buf 的长度 /
length: number

/* table name / column name /
name?: string

/**
最低维、第 1 维
- vector: rows = n, cols = 1
- pair: rows = 2, cols = 1
- matrix: rows = n, cols = m
- set: 同 vector
- dict: 包含 keys, values 向量
- table: 同 matrix
*/
rows?: number

/* 第 2 维 /
cols?: number

/* 实际数据。不同的 DdbForm, DdbType 使用 DdbValue 中不同的类型来表示实际数据 /
value: T

/* 原始二进制数据，仅在 parse_object 为 false 时通过 parse_message 生成的顶层对象有这个属性 /
buffer?: Uint8Array

constructor (data: Partial & { form: DdbForm, type: DdbType, length: number }) {
Object.assign(this, data)
}
}

class DdbInt extends DdbObj {
constructor (value: number) {
super({
form: DdbForm.scalar,
type: DdbType.int,
length: 4,
value
})
}
}

// ... 还有很多快捷类，如 DdbString, DdbLong, DdbDouble, DdbVectorDouble, DdbVectorAny 等

type DdbValue =
null | boolean | number | [number, number] | bigint | string | string[] |
Uint8Array | Int16Array | Int32Array | Float32Array | Float64Array | BigInt64Array | Uint8Array[] |
DdbObj[] | DdbFunctionDefValue | DdbSymbolExtendedValue


enum DdbForm {
scalar = 0,
vector = 1,
pair = 2,
matrix = 3,
set = 4,
dict = 5,
table = 6,
chart = 7,
chunk = 8,
}


enum DdbType {
void = 0,
bool = 1,
char = 2,
short = 3,
int = 4,
long = 5,
// ...
timestamp = 12,
// ...
double = 16,
symbol = 17,
string = 18,
// ...
}
`

###### 无快捷类的类型

对于没有快捷类的类型，可指定 form 和 type 手动创建 DdbObj 对象

`ts
// 通过 DdbDateTime 快捷类创建
new DdbDateTime(1644573600)

// 等价于手动通过 DdbObj 创建 form = scalar, type = datetime 的对象
const obj = new DdbObj({
form: DdbForm.scalar,
type: DdbType.datetime,
value: 1644573600,
length: 0
})


// value 在 js 中对应类型及取值可以参考 ddb.eval 返回的结果 (见后文 eval 方法声明)
const obj = await ddb.eval('2022.02.11 10:00:00')
console.log(obj.form === DdbForm.scalar)
console.log(obj.type === DdbType.datetime)
console.log(obj.value)

// 再比如创建一个 set
// 参考 ddb.eval
// const obj = await ddb.eval('set([1, 2, 3])')
// console.log(obj.value)
const obj = new DdbObj({
form: DdbForm.set,
type: DdbType.int,
value: Int32Array.of(1, 2, 3),
length: 0
})

// 使用快捷类较为简单
const obj = new DdbSetInt(
new Set([1, 2, 3])
)
`

###### scalar 形式的 NULL 对象

scalar 形式的 NULL 对象，其对应 DdbObj 的 value 为 JavaScript 中的 null：

`ts
;(await ddb.eval('double()')).value === null

// 创建 NULL 对象
new DdbInt(null)
new DdbDouble(null)
`

##### call 方法声明
`ts
async call (
/* 函数名 /
func: string,

/* 调用参数 (传入的原生 string 和 boolean 会被自动转换为 DdbObj 和 DdbObj) /
args?: (DdbObj | string | boolean)[] = [ ],

/* 调用选项 /
options?: {
/* 紧急 flag。使用 urgent worker 执行，防止被其它作业阻塞 /
urgent?: boolean

/* 设置结点 alias 时发送到集群中对应的结点执行 (使用 DolphinDB 中的 rpc 方法) /
node?: string

/* 设置多个结点 alias 时发送到集群中对应的多个结点执行 (使用 DolphinDB 中的 pnodeRun 方法) /
nodes?: string[]

/* 设置 node 参数时必传，需指定函数类型，其它情况下不传 /
func_type?: DdbFunctionType

/* 设置 nodes 参数时选传，其它情况不传 /
add_node_alias?: boolean
} = { }
): Promise
`

$3


#### execute 方法
##### execute 方法代码示例
`ts
const result = await ddb.execute(
'def foo (a, b) {\n' +
' return a + b\n' +
'}\n' +
'foo(1l, 1l)\n'
)

// TypeScript:
// const result = await ddb.execute(...)

console.log(result.value === 2n) // true
`

上面例子中，通过字符串上传了一段脚本到 DolphinDB 数据库执行，并接收最后一条语句 foo(1l, 1l) 执行结果 result

用于 TypeScript 推断返回值的类型

- result 是一个 bigint

只要 WebSocket 连接不断开，在后续的会话中 foo 这个自定义函数会一直存在，可复用，比如后续通过 await ddb.invoke('foo', [1, 1]) 调用这个自定义函数

##### execute 方法声明
`ts
/* 执行 dolphindb 脚本，返回 js 原生对象或值（调用 DdbObj.data() 后的结果）/
async execute (
/* 执行的脚本 /
script: string,

/* 执行选项 /
options?: {
/* 紧急 flag，确保提交的脚本使用 urgent worker 处理，防止被其它作业阻塞 /
urgent?: boolean
/* listener?: 处理本次 rpc 期间的消息 (DdbMessage) /
listener?: DdbMessageListener
}
): Promise
`

#### eval 方法
##### eval 方法代码示例
`ts
const result = await ddb.eval(
'def foo (a, b) {\n' +
' return a + b\n' +
'}\n' +
'foo(1l, 1l)\n'
)

// TypeScript:
// import type { DdbLong } from 'dolphindb'
// const result = await ddb.eval(...)

console.log(result.value === 2n) // true
`

上面例子中，通过字符串上传了一段脚本到 DolphinDB 数据库执行，并接收最后一条语句 foo(1l, 1l) 执行结果 result

用于 TypeScript 推断返回值的类型

- result 是一个 DdbLong，也是 DdbObj
- result.form 是 DdbForm.scalar
- result.type 是 DdbType.long
- result.value 是 JavaScript 中原生的 bigint (long 的精度不能用 JavaScript 的 number 准确表示，但可以用 bigint 表示)

##### eval 方法声明
`ts
/* 执行 dolphindb 脚本，返回 DdbObj 对象）/
async eval (
/* 执行的脚本 /
script: string,

/* 执行选项 /
options: {
/* 紧急 flag，确保提交的脚本使用 urgent worker 处理，防止被其它作业阻塞 /
urgent?: boolean
} = { }
): Promise
`

$3


#### 例子
`ts
import { DdbVectorDouble } from 'dolphindb'

let a = new Array(10000)
a.fill(1.0)

ddb.upload(['bar1', 'bar2'], [new DdbVectorDouble(a), new DdbVectorDouble(a)])
`

上面的例子中，上传了 bar1, bar2 两个变量，变量值是长度为 10000 的 double 向量

只要 WebSocket 连接不断开，在后续的会话中 bar1, bar2 这些变量会一直存在，可复用

#### upload 方法声明
`ts
async upload (
/* 上传的变量名 /
vars: string[],

/* 上传的变量值 /
args: (DdbObj | string | boolean)[]
): Promise
`




$3


`ts
// 在连接对应的会话中加载或创建表
await ddb.execute('t = table(1..10 as id, take(["A001", "B001"], 10) as sym, rand(10.0, 10) as val)')
// await ddb.execute('t = loadTable(database("dfs://path-to-db"), "table_name")')

console.log(
'插入的行数:',
// 使用 tableInsert 插入数据
await ddb.invoke(
'tableInsert',
[
't',

// 数据
new DdbTable([
// 第一列
new DdbVectorInt([1, 2, 3]),

// 第二列
new DdbVectorSymbol(['a', 'b', 'c']),

// 第三列
new DdbVectorDouble([1.1, 1.2, 1.3]),
])
]
)
)
`

$3


`ts
ddb.disconnect()
`

$3

`ts
import { nulls, DdbInt, timestamp2str, DdbVectorSymbol, DdbTable, DdbVectorDouble } from 'dolphindb'

// 将 DolphinDB 中的 timestamp 格式化为 string
timestamp2str(
(
await ddb.call('now', [false])
// TypeScript: await ddb.call>('now', [false])
).value
) === '2022.02.23 17:23:13.494'

// 创建 symbol vector
new DdbVectorSymbol(['aaa', 'aaa', 'aaa', 'aaa', 'aaa', 'bbb'])

// 使用 JavaScript 原生数组创建含有 NULL 值的 double vector
new DdbVectorDouble([0.1, null, 0.3])

// 使用 JavaScript TypedArray 更加高效且节约内存的创建 double vector
let av = new Float64Array(3)
av[0] = 0.1
av[1] = nulls.double
av[2] = 0.3
new DdbVectorDouble(av)

// 创建 DdbTable
new DdbTable(
[
new DdbVectorDouble([0.1, 0.2, null], 'col0'),
new DdbVectorSymbol(['a', 'b', 'c'], 'col1')
],
'mytable'
)
`




$3

`ts
// 新建流数据连接配置
let sddb = new DDB('ws://192.168.0.43:8800', {
autologin: true,
username: 'admin',
password: '123456',
streaming: {
table: '要订阅的流表名称',

// 流数据处理回调, message 的类型是 StreamingMessage
handler (message) {
console.log(message)
}
}
})

// 建立连接
await sddb.connect()
`

连接建立后接收到的流数据会作为 message 参数调用 handler, message 的类型是 StreamingMessage, 如下:

`ts
export interface StreamingParams {
table: string
action?: string

handler (message: StreamingMessage): any
}

export interface StreamingMessage extends StreamingParams {
/** server 发送消息的时间 (nano seconds since epoch)
std::chrono::system_clock::now().time_since_epoch() / std::chrono::nanoseconds(1) */
time: bigint

/* message id /
id: bigint

/** 订阅主题，即一个订阅的名称。
它是一个字符串，由订阅表所在节点的别名、流数据表名称和订阅任务名称（如果指定了 actionName）组合而成，使用 / 分隔 */
topic: string

/* 流数据 /
data: DdbTableData

window: {
/* 建立连接开始 offset = 0, 随着 window 的移动逐渐增加 /
offset: number

/* 历史数据 /
data: TRows[]

/* 每次接收到的 obj 组成的数组 /
objs: DdbObj[]
}

/* 成功订阅后，后续推送过来的 message 解析错误，则会设置 error 并调用 handler /
error?: Error
}
`

关闭流数据订阅使用下面两种断开连接的方法
- 关闭浏览器页面自动断开连接
- 调用 sddb.disconnect() 手动断开连接




$3

`shell


安装最新版的 nodejs (见上文)

安装 pnpm 包管理器

npm install -g pnpm

git clone https://github.com/dolphindb/api-javascript.git

cd api-javascript

国内网络推荐配置 registry

pnpm config set registry https://registry.npmmirror.com

安装项目依赖

pnpm install

将 .vscode/settings.template.json 复制为 .vscode/settings.json

cp .vscode/settings.template.json .vscode/settings.json

参考 package.json 中的 scripts

构建

pnpm run build

格式化代码并自动修复代码错误

pnpm run fix

测试

pnpm run test

扫描词条

pnpm run scan

手动补全未翻译词条

再次运行扫描以更新词典文件 dict.json

pnpm run scan
``