NodeJS API

使用说明

运行环境

要求Nodejs版本10.21或以上。使用到了BigInt。

建立连接

const {DBconnection} = require('dolphindb-api-nodejs');
var conn = new DBconnection();
await conn.connect("localhost", 8848);

函数说明:

connect(host, port, username, password)

  • host: 主机名
  • port: 主机端口
  • username: 用户名
  • password: 用户密码

运行脚本

建立连接之后,可以把脚本传输到服务端运行,并返回相应结果,如下所示:

let result;
result = await conn.run('typestr [1,2,3]');
// 返回 FAST INT VECTOR
result = await conn.run("dict(1 7 5,`AA`BB`CC)");
// 返回 Map(3) {5 => CC, 1 => AA, 7=> BB}

运行函数

result = await conn.runFunc('add', [1,2,3], [4,5,6]);
// 返回 [5,7,9]
await conn.run('a=[1,2,3]');
result = await conn.runFunc('add{a,}', [1,2.6,7]);
// 返回 [2, 4.6, 10]

函数说明:

runFunc(funcName, ...args)

  • funcName: 要在服务端运行的函数名(由数据库本身提供)
  • args: 参数列表,可传入任意多个参数

注意,在上传参数时,可能需要进行包装, 以下进行说明:

标量类型

  • bool类型, 可以直接传递或使用DT.Bool包装
  • char类型, 需使用DT.Char包装
  • short类型, 需使用DT.Short包装
  • int类型, 可以直接传递或使用DT.Int包装
  • long类型, 可以直接传递或使用DT.Long包装
  • date类型,需使用DT.Date包装,支持字符串格式YYYY-MM-DD,对象格式{year: 1970, month: 1, day: 1}和天数格式(距离1970年1月1日的天数)
  • month类型,需要使用DT.Month包装,支持字符串格式YYYY-MM,对象格式{year: 1970, month: 1}和月格式(距离公元0年初始的月数)
  • time类型, 需使用DT.Time包装,支持字符串格式HH:mm:ss.s,对象格式{hour: 0, minute: 0, second: 0, nanoSecond: 0}和毫秒格式(距离当天0点的毫秒数)
  • minute类型: 需使用DT.Minute包装,支持字符串格式HH:mm,对象格式{hour: 0, minute: 0}和分钟格式(距离当天0点的分钟数)
  • second类型: 需要使用DT.Second包装,支持字符串格式HH:mm:ss,对象格式{hour: 0, minute: 0, second:0}和秒格式(距离当天0点的秒数)
  • datetime类型:需要使用DT.DateTime包装,支持字符串格式YYYY-MM-DD HH:mm:ss,对象格式{year: 1970, month: 1, day: 1, hour: 0, minute: 0, second: 0}和秒格式(距离1970年1月1日0点的秒数)
  • timestamp类型: 需要使用DT.TimeStamp包装,支持字符串格式YYYY-MM-DD HH:mm:ss.s, 对象格式{date: {year: 1970, month: 1, day: 1}, time: {hour: 0, minute: 0, second: 0, nanoSecond: 0}}和毫秒格式(距离1970年1月1日0点的毫秒数,需要使用BigInt类型数值)
  • nanotime类型:需要使用DT.NanoTimeStamp包装,支持字符串格式YYYY-MM-DD HH:mm:ss.s,对象格式{hour: 0, minute: 0, second: 0, nanoSecond: 0}和纳秒格式(距离当天0点的纳秒数,需使用BigInt类型数值)
  • nanotimestamp类型: 需要使用DT.NanoTimeStamp包装,支持字符串格式YYYY-MM-DD HH:mm:ss.s,对象格式{date: {year: 1970, month: 1, day: 1}, time: {hour: 0, minute: 0, second: 0, nanoSecond: 0}}和纳秒格式(距离1970年1月1日0点的纳秒数,需要使用BigInt类型数值)
  • float类型: 需要使用DT.Float包装
  • double类型: 可以直接传递或使用DT.Double包装
  • symbol类型: 需要使用DT.Symbol包装
  • string类型: 可以直接传递或使用DT.String包装
  • uuid类型: 需要使用DT.UUID包装,支持字符串格式00000000-0000-0000-0000-000000000000和对象格式{high: 0n, low: 0n}
  • ipaddr类型: 需要使用DT.IpAddr包装,支持字符串格式192.168.1.0和对象格式{high: 0n, low: 0n}。对于Ipv6格式,可以直接以16进制字符格式传递(不要:号)
  • int128类型:需要使用DT.Int128包装,支持字符串格式e1671797c52e15f763380b45e841ec32和对象格式{high: 0n, low: 0n}
  • null类型: 需要使用DT.Null包装。以上各种类型都对应一个NULL类型,例如int类型的NULL类型可表示为DT.Int(), DT.Int(null), DT.Null('int'), 对于服务器端void类型,则使用DT.Null(0)DT.Null('void')表示。

复合类型

  • vector类型: 对应javascript中的Array类型,可以直接传递或使用DT.Vector包装
  • pair类型: 2元组的vector类型,需使用DT.Pair包装,传入字符形式的数据对,如'12:18'
  • matrix类型: 需要使用DT.Matrix包装,传入矩阵对象{colnames:[], rownames: [], type: 'int', data: [[1,2],[3,4]]}。除了data为必须,其它均可不设置
  • set类型: 对应javascript中的Set类型,需要使用DT.Set包装
  • dictionary类型: 对应javascript中的Map类型,需要使用DT.Dict包装
  • table类型: 需要使用DT.Table包装, 传入表对象{tablename:'t', colnames: ['id','val'], types: ['int','string'], data: [[1,2,3],['aa','bb','mm']]}。除了data为必须,其它均可不设置

上传本地对象到服务器

const {DT} = require('dolphindb-api-nodejs')

await conn.upload("a",  DT.TimeStamp("2012-06-13 13:30:10.008"));
result = await conn.run('a');
// 返回TimeStamp对象, 需使用toString()方法格式化输出, 结果为: 2012-6-13 13:30:10.8000000ns

函数说明:

upload(varnames, ...vars)

  • varnames: 上传的变量名,如有多个,以,分隔。
  • vars: 变量列表,可传入任意多个变量

上传变量格式与上传函数参数时使用的格式相同

流数据

订阅

const {StreamClient} = require('dolphindb-api-nodejs');
const client = new StreamClient(8997); // 提供本地监听端口    

var script = '' +
'share streamTable(100:0, `sym`date`price`qty, [SYMBOL, DATE, DOUBLE, INT]) as trades \n'+
'setStreamTableFilterColumn(trades, `qty) \n'+
'tmp = table(symbol(`A`B`C`D`E) as sym, 2012.01.01..2012.01.05 as date, [20.5, 45.2, 15.6, 58.4, 12.0] as price, [2200, 1500, 4800, 5900, 4600] as qty) \n'+
'trades.append!(tmp)'
await conn.run(script)
client.subscribe("localhost",8848, "trades", "trades_sub1", {handler: function(data) {console.log(data)}, offset:0,filter:Int([2200, 1500])})

函数说明: subscibe (host, port, tableName, actionName, options)

  • host:发布端节点的IP地址。

  • port:发布端节点的端口号。

  • tableName:发布表的名称。

  • actionName:订阅任务的名称。

  • options:可选参数,包括,

    • handler:用户自定义的回调函数,用于处理每次流入的数据。
    • offset:整数,表示订阅任务开始后的第一条消息所在的位置。消息是流数据表中的行。如果没有指定offset,或它为负数或超过了流数据表的记录行数,订阅将会从流数据表的当前行开始。offset与流数据表创建时的第一行对应。如果某些行因为内存限制被删除,在决定订阅开始的位置时,这些行仍然考虑在内。
    • filter:向量,表示过滤条件。流数据表过滤列在filter中的数据才会发布到订阅端,不在filter中的数据不会发布。
    • allowExistTopic: bool值。
    • msgAsTable: bool值,当值为true时,订阅到的数据包会附上table表头,格式如{header:[columes],body:[value]},否则仅返回数据。

需要注意的是若客户端只接收到一行数据,则nodejs返回的是一维数组;若接收到多行数据时,返回的是二维数组。

取消订阅

await client.unsubscribe("127.0.0.1", 8848, "trades", "trades_subs1");

函数说明: unsubscibe (host, port, tableName, actionName)

参数意义同subscribe()函数。