连接器 & API

适用于130、200及更高版本系列的 Server。

DolphinDB 的 API 与连接器都有以下三个交互阶段:

  • 连接
  • 客户端发送报文
  • 服务端返回报文

连接

连接阶段是客户端和服务端握手的阶段。客户端向服务器发送connect命令请求连接,服务端返回'OK',并且分配新的SessionID给客户端。

客户端发送连接请求

长度(Byte) 报文 说明
3 API 请求类型
1 空格 char(0x20)
1 0 SESSIONID
1 空格 char(0x20)
2 8 报文指令长度,固定字符串connect\n
1 换行符(LF) char(0x10)
8 "connect\n" 固定字符串

服务端应答报文请求

长度(Byte) 报文 说明
不固定 例如'1195587396' SESSIONID
1 空格 char(0x20)
1 0 返回对象数量
1 空格 char(0x20)
1 1 大小端,1-小端,0-大端
1 换行符(LF) char(0x10)
不固定 执行结果 "OK"

指令交互

请求报文

| 请求类型 | 空格 | SESSIONID | 空格 | 报文指令长度 | 换行符(LF)
| 指令类型 | 换行符(LF)
| 指令参数 | 数据 |

应答报文

| SESSIONID | 空格 | 返回对象数量 | 空格 | 大小端 | 换行符(LF)
| 执行结果 | 换行符(LF)

会话

会话编号(session ID)代表终端与 DolphinDB 建立的一次 TCP 连接。终端通过 connect 连接成功后 DolphinDB 会返回一个新的 session ID,在此之后所有的报文交互都基于此 session ID进行,直到此连接被终端主动关闭。

如果请求报文的 session ID 为 0,或者服务器找不到指定的 session ID,服务器会创建并返回一个新的 session ID。

session ID 是一个随机的长整型。

请求类型

请求方式 说明
API 调用并返回结果,无进度信息返回。
API2 调用返回结果的同时,持续返回执行中脚本输出的信息。此方式仅支持 script 指令。

指令类型

DolphinDB database 支持以下三种指令类型:

  • script: 这种指令使用非常灵活,它以字符串形式发送脚本,服务器会返回脚本执行的结果。
  • function: 这种指令可以调用指定的函数,可以是内置函数或自定义函数。函数可以接受多个对象作为函数参数。
  • variable: 将客户端对象变量上传到服务器并指定其变量名。

Script

script 指令用来向 DolphinDB 发送脚本字符串,DolphinDB 执行脚本并返回执行结果。

1. 请求报文格式
长度(Byte) 报文 说明 样本
3 或 4 请求类型 API,API2 API
1 空格 char(0x20)
不固定 SESSIONID 长度不固定,到空格为止 2247761467
1 空格 char(0x20)
2 报文指令长度 包含从“script"到脚本内容结束为止的长度,如"script\n1+1" 11
1 换行符 char(0x10)
7 指令 script "script"
1 换行符 char(0x10)
不固定 脚本内容 长度到下一个换行符为止 select * from loadTable('dfs://db','tb1') 或 sum(1..100) + avg(1..100)
2. 响应报文格式
长度(Byte) 报文 说明 样本
不固定 MSG 如果请求类型为API2, 并且脚本中间有print等输出脚本,在返回报文包含MSG段 MSG"this is output message1"MSG"this is output message2"
不固定 SESSIONID 长度不固定,到空格为止 2247761467
1 空格 char(0x20)
1 大小端 1-小端,0-大端 1
1 换行符(LF) char(0x10)
1 执行成功否 返回文本OK表示执行成功 "OK"
1 换行符(LF) char(0x10)
不固定 返回结果 数据格式参考第3节

function

function 指令用来向 DolphinDB 发送函数调用请求,DolphinDB 会执行指定函数并返回执行结果。

3. 请求报文
长度(Byte) 报文 说明 样本
3 请求类型 API API
1 空格 char(0x20)
不固定 SESSIONID 长度不固定,到空格为止 2247761467,638252939
1 空格 char(0x20)
2 报文指令长度 包含从“function"到大小端标志为止的长度,如"function\nsum\n1\n1" 16
1 换行符 char(0x10)
8 指令 function "function"
1 换行符 char(0x10)
不固定 函数名称 长度到下一个换行符为止 sum
1 换行符 char(0x10)
1 参数数量 传递到函数的参数个数 1
1 换行符 char(0x10)
1 大小端标志 1-小端,0-大端 1
不固定 参数数据 数据格式参考第3节
4. 响应报文格式
长度(Byte) 报文 说明 样本
3 SESSIONID 长度不固定,到空格为止 API
1 空格 char(0x20)
1 大小端 1-小端,0-大端 1
1 换行符(LF) char(0x10)
1 执行成功否 返回文本OK表示执行成功 "OK"
1 换行符(LF) char(0x10)
不固定 返回结果 数据格式参考第3节

variable

variable 指令用来向 DolphinDB 发送本地数据,DolphinDB 会在 server 端生成指定变量。

长度(Byte) 报文 说明 样本
3 请求类型 API API
1 空格 char(0x20)
不固定 SESSIONID 长度不固定,到空格为止 2247761467
1 空格 char(0x20)
2 报文指令长度 包含从“variable"到大小端标志为止的长度,如"variable\na,b\n2\n1" 16
1 换行符 char(0x10)
8 指令 variable "variable"
1 换行符 char(0x10)
不固定 变量名 多个变量通过","号分隔,字符串 a,b
1 换行符 char(0x10)
1 变量数量 传递到函数的变量个数 2
1 换行符 char(0x10)
1 大小端标志 1-小端,0-大端 1
不固定 变量数据 数据格式参考第3节
5. 响应报文格式
占位(Byte) 报文 说明 样本
3 SESSIONID 长度不定,到空格为止 API
1 空格 char(0x20)
1 大小端 1-小端,0-大端 1
1 换行符(LF) char(0x10)
1 执行成功否 返回文本OK表示执行成功 "OK"

行为标识

在 提交 script,function 报文时,在 "报文指令长度" 之后,增加"行为标识"报文来指示Server按照指定的要求来执行脚本或函数。

行为标识以字符串方式传输。每一个标识用下划线_分隔,整个字符串的含义如下:

标识名 标识范围 说明 样本
flag (0,1,2,4,8,16)任意数字组的和 一组开关量标识,按位取值, 参考flag表格 4
cancellable 0,1 任务是否可以取消 1
priority 0~8 指定本任务优先级 8
parallelism 0~64 指定本任务并行度 8
rootId 整数 根任务编号,内部使用,API中固定为空 12
fetchSize 指定分块返回的块大小 10000
offset API中固定为空

一个标准的行为标识字符串用"/ "开头,以换行符结束。如:"/ 4_1_8_8__10000\n"。

flag 的含义如下:

数位(从低位开始) 标识名 说明
0 isUrgent 是否紧急任务。即使系统繁忙,isUrgent=1的任务会通过紧急通道得以执行。
1 isSecondaryJob API提交的任务,isSecondaryJob必须为0
2 isAsync 是否异步任务
3 isPickle 让服务端以picle协议返回数据,固定为0
4 isClearSessionMemory 本次任务完成后
5 isAPIClient 内部使用,固定为0

数据报文

数据格式

6. 标量(DF_SCALAR)
报文字段 长度(Byte) 说明
DataType 1 数据类型
DataForm 1 数据形式
Data 不固定 数据
7. 向量(DF_VECTOR)
报文字段 长度(Byte) 说明
DataForm 1 数据形式
DataType 1 数据类型
Rows 4 行数
Columns 4 列数,向量的columns是1
Data 不固定 数据
8. 数据对(DF_PAIR)
报文字段 长度(Byte) 说明
DataForm 1 固定为2
DataType 1 数据类型
Rows 4 行数,固定为2
Columns 4 列数,固定为1
values 不固定 数据, 参照向量格式
9. 矩阵(DF_MATRIX)
报文字段 长度(Byte) 说明
HasRowLabel 1bit Byte中第一个bit, 0000 0001
HasColumnLabel 1bit Byte中第二个bit,0000 0010
DataForm 1 数据形式
DataType 1 数据类型
RowLabels 不固定 行名称
ColumnsLabels 1 列名称
Rows 4 行数
Columns 4 列数
Data 不固定 数据
10. 集合(DF_SET)
报文字段 长度(Byte) 说明
DataForm 1 固定为4
DataType 1 数据类型
Rows 4 行数
Columns 4 列数,固定为1
values 不固定 数据, 参照向量格式
11. 字典(DF_DICTIONARY)
报文字段 长度(Byte) 说明
DataForm 1 固定为5
DataType 1 数据类型
Keys 不固定 键, 参照向量格式
values 不固定 值, 参照向量格式
12. 表(Table)
报文字段 长度(Byte) 说明
DataForm 1 固定为6
DataType 1 数据类型
Rows 4 行数
Columns 4 列数
TableName 不固定 行名称
ColumnNames1 不固定 列名称1
ColumnNamesn 不固定 列名称n
VectorData1 不固定 列1数据, 参照向量格式
VectorDatan 不固定 列n数据, 参照向量格式

数据类型

API 使用基本的数据类型包括 Byte,Short,Int,Long,Float,Double,String 这几种,所有的日期和时间类型在系统内部都是用 INT 或者 LONG 来存储和传输数据。

数据类型 长度 说明 样例
BOOL 1 1b, 0b true, false
CHAR 1 -27+1 ~ 27-1 'a', 97c
SHORT 2 -215+1 ~ 215-1 122h
INT 4 -231+1 ~ 231-1 22
LONG 8 -263+1 ~ 263-1 22l
DATE 4 INT 2013.06.13
MONTH 4 INT 2012.06M
TIME 4 INT 13:30:10.008
MINUTE 4 INT 13:30m
SECOND 4 INT 13:30:10
DATETIME 4 INT 2012.06.13 13:30:10 or 2012.06.13T13:30:10
TIMESTAMP 8 LONG 2012.06.13 13:30:10.008 or 2012.06.13T13:30:10.008
NANOTIME 8 LONG 13:30:10.008007006
NANOTIMESTAMP 8 LONG 2012.06.13 13:30:10.008007006 or 2012.06.13T13:30:10.008007006
FLOAT 4 2.1f
DOUBLE 8 2.1
STRING 不固定 采用UTF8编码,每个字符串用0做终止符 "String Hello World0"

附录:数据报文编码

13. 数据类型(DataType)
数据类型 报文值
DT_VOID 0
DT_BOOL 1
DT_BYTE 2
DT_SHORT 3
DT_INT 4
DT_LONG 5
DT_DATE 6
DT_MONTH 7
DT_TIME 8
DT_MINUTE 9
DT_SECOND 10
DT_DATETIME 11
DT_TIMESTAMP 12
DT_NANOTIME 13
DT_NANOTIMESTAMP 14
DT_FLOAT 15
DT_DOUBLE 16
DT_SYMBOL 17
DT_STRING 18
DT_UUID 19
DT_FUNCTIONDEF 20
DT_HANDLE 21
DT_CODE 22
DT_DATASOURCE 23
DT_RESOURCE 24
DT_ANY 25
DT_DICTIONARY 26
DT_OBJECT 27
14. 数据形式(DataForm)
数据形式 报文值
DF_SCALAR 0
DF_VECTOR 1
DF_PAIR 2
DF_MATRIX 3
DF_SET 4
DF_DICTIONARY 5
DF_TABLE 6
DF_CHART 7
DF_CHUNK 8