FIU

为订阅 FIU 融源行情网关推送的外盘期货行情数据，DolphinDB 基于《FIU 融源行情网关使用手册 外盘期货 V1.0.1》开发了 FIU 插件。使用 FIU 插件可以通过 TCP 接收并解析 JSON 或 protobuf 格式的外盘期货行情数据。插件不兼容旧版 3 字节 protobuf 包头及消息号 100/103。

安装插件

版本要求

DolphinDB Server：3.00.4 及更高版本，支持 Linux x86-64、Linux ABI。

安装步骤

  1. 在 DolphinDB 客户端中使用 listRemotePlugins 函数查看可供安装的插件。

    login("admin", "123456")
listRemotePlugins()

  2. 使用 installPlugin 函数安装插件。

    installPlugin("FIU")

  3. 使用 loadPlugin 函数加载插件。

    loadPlugin("FIU")

接口说明

createSubJob

语法

FIU::createSubJob(host, port, protocol, username, password, symbols, snapshotTable, [codeTable], [orderTable], [config])

详情

创建一个 FIU 行情订阅任务。每次与 FIU 行情网关建立新连接后，均重新执行登录和订阅。

参数

host STRING 类型标量，指定 FIU 行情网关地址。

port INT 类型标量，指定 FIU 行情网关端口。

protocol STRING 类型标量，指定订阅使用的接口协议格式，可选值为 "json" 或 "protobuf"。

username STRING 类型标量，指定 FIU 行情网关账号，不能为空。

password STRING 类型标量，指定 FIU 行情网关账号的密码，不能为空。

symbols STRING 类型标量或向量，指定订阅列表。格式为：市场@品种@月份合约，例如 "CME@6A@6A2612"。支持：

  • 全量订阅，格式：*@*@*

  • 单品种订阅，格式：CME@6A@*

  • 单市场订阅，格式：CME@*@*

snapshotTable 指定快照输出表，表结构必须与 getSchema("snapshot") 一致。

codeTable（可选参数）指定码表输出表，表结构必须与 getSchema("codetable") 一致。

orderTable（可选参数）指定五档挂单输出表，表结构必须与 getSchema("order") 一致。

config （可选参数）字典（Dictionary<STRING, ANY>），不指定时使用默认值。支持以下 key：

key value 类型 默认值 说明
"reconnectInterval" INT 类型标量 3000 指定重连间隔，单位为毫秒；可以为 0
"heartbeatTimeout" INT 类型标量 5000 指定从最近完整消息开始计算的超时时间，单位为毫秒；指定为 0 表示关闭超时检测
"enableReconnect" BOOL 类型标量 true 指定断线、登录失败或订阅失败后是否重连
"receiveTime" BOOL 类型标量 false 指定是否在输出表末尾增加一列，记录插件接收到数据的时间，类型为 NANOTIMESTAMP

返回值

返回一个 STRING 类型的订阅任务标识 jobId，用于查询订阅状态或取消订阅任务。

cancelSubJob

语法

FIU::cancelSubJob(jobId)

详情

取消 FIU 行情订阅任务。

参数

jobId STRING 类型标量，由 createSubJob 接口返回的任务标识。

返回值

返回一个布尔值。订阅取消成功时返回 true，失败返回 false。

getSchema

语法

FIU::getSchema(dataType, [needReceiveTime])

详情

获取指定消息类型的 schema 描述表。

参数

dataType STRING 类型标量，指定消息类型。可选值为：

  • "snapshot"：行情快照

  • "codetable"：码表

  • "order"：五档挂单

needReceiveTime（可选参数）BOOL 类型标量，默认值为 false。该参数必须与使用 createSubJob 接口创建订阅任务时指定的 config["receiveTime"] 一致。

返回值

返回一个表格，包含以下字段：

字段 类型 含义
name STRING 字段名
typeString STRING 字段数据类型
typeInt INT 类型的枚举值

getSubJobStat

语法

FIU::getSubJobStat()

详情

返回所有 FIU 行情订阅任务的状态表。

参数

无

返回值

返回一个表格，包含以下字段：

字段 类型 说明
jobId STRING 由 createSubJob 接口返回的订阅任务标识
host STRING FIU 行情网关地址
port INT FIU 行情网关端口
protocol STRING 订阅使用的协议，"json" 或 "protobuf"
connected BOOL 当前 TCP 连接是否建立
authenticated BOOL 当前连接是否登录成功
subscribed BOOL 当前连接是否订阅成功
createTime NANOTIMESTAMP 订阅任务创建时间
lastMsgTime NANOTIMESTAMP 最近一次收到完整 FIU 消息的时间
lastHeartbeatTime NANOTIMESTAMP 最近一次收到心跳消息的时间
receivedMessages LONG 已接收的完整消息总数，包含登录、订阅、行情和心跳
receivedSnapshot LONG 已解析的行情快照消息数
receivedCodeTable LONG 已解析的码表消息数；未配置码表时仍统计
receivedOrder LONG 已解析的挂单消息数；未配置挂单表时仍统计
receivedHeartbeat LONG 已接收的心跳消息数
failedMessages LONG 解析、认证、订阅或异步写表失败的消息数
reconnectCount LONG 已触发的 TCP 重连次数
lastError STRING 最近一次错误；重连成功后仍保留历史错误

使用示例

本示例演示一个完整的订阅场景，通过 FIU 插件以 protobuf 协议连接到 FIU 行情网关，执行全量订阅（*@*@*），将推送过来的三类行情数据分别写入三张共享持久化的流表。需指定 persistenceDir 配置项开启流数据持久化，详见功能配置。

// 指定 receiveTime 为 true
receiveTime = true

// 获取各消息类型的 schema 描述表
snapshotSchema = FIU::getSchema("snapshot", receiveTime)
snapshotTable = streamTable(10000:0, snapshotSchema[`name], snapshotSchema[`typeString])

// 创建快照输出表
enableTableShareAndPersistence(table=snapshotTable, tableName=`FIUSnapshot, cacheSize=1000000, retentionMinutes=1440)
snapshotTable = objByName(`FIUSnapshot)

// 创建码表输出表
codeSchema = FIU::getSchema("codetable", receiveTime)
codeTable = streamTable(10000:0, codeSchema[`name], codeSchema[`typeString])
enableTableShareAndPersistence(table=codeTable, tableName=`FIUCodeTable, cacheSize=100000, retentionMinutes=1440)
codeTable = objByName(`FIUCodeTable)

// 创建五档挂单输出表
orderSchema = FIU::getSchema("order", receiveTime)
orderTable = streamTable(10000:0, orderSchema[`name], orderSchema[`typeString])
enableTableShareAndPersistence(table=orderTable, tableName=`FIUOrder, cacheSize=1000000, retentionMinutes=1440)
orderTable = objByName(`FIUOrder)

// 构造订阅配置字典
config = dict(STRING, ANY)
config["receiveTime"] = receiveTime

// 全量订阅
job = FIU::createSubJob(
    "127.0.0.1", 9001, "protobuf",
    "fiuAccount", "plainPassword", "*@*@*",
    snapshotTable, codeTable, orderTable, config)

// 查询当前所有订阅任务的状态
FIU::getSubJobStat()

// 取消订阅任务
FIU::cancelSubJob(job)

字段转换规则

FIU 插件订阅支持两种口协议格式 "json" 或 "protobuf"。

JSON to DolphinDB

JSON 字段名按大小写不敏感匹配。JSON 数值字段支持 number 或数字字符串。JSON 字段不存在、为 null 或空字符串时，标量输出为 DolphinDB NULL。DolphinDB 的 array vector 不支持单元格 NULL，因此缺失的五档数组输出为空 LONG[]。

snapshot

JSON 协议名为 qhsnapshot。

DolphinDB 字段 DolphinDB 类型 JSON 字段 JSON 类型 JSON 示例值 转换
symbol SYMBOL symbol string "LMECA2605" 字符串写入 SYMBOL
time TIMESTAMP time string/number 1787103585000 13 位 epoch 毫秒直接写入；17 位 yyyyMMddHHmmssSSS 解析为 TIMESTAMP；缺失或 0 为 NULL
localTime TIMESTAMP localtime string/number 1787103585001 13 位 epoch 毫秒直接写入；17 位 yyyyMMddHHmmssSSS 解析为 TIMESTAMP；缺失或 0 为 NULL
price DOUBLE Price string/number "9876.50" 转为 DOUBLE
vol LONG Vol string/number "12" 原始整数
totalVol LONG TotalVol string/number "123456" 原始整数
openInterest LONG OpenInterest string/number "654321" 原始整数
preOpenInterest LONG PreOpenInterest string/number "650000" 原始整数
preSettle DOUBLE PreSettle string/number "9800.00" 转为 DOUBLE
settle DOUBLE Settle string/number "9820.00" 转为 DOUBLE
high DOUBLE High string/number "9900.00" 转为 DOUBLE
low DOUBLE Low string/number "9700.00" 转为 DOUBLE
close DOUBLE Close string/number "9860.00" 转为 DOUBLE
open DOUBLE Open string/number "9810.00" 转为 DOUBLE
turnover DOUBLE Turnover string/number "1234567.89" 转为 DOUBLE
receiveTime NANOTIMESTAMP 无 无 无 config["receiveTime"]=true 时由插件生成

codetable

JSON 协议名为 qhcode。

DolphinDB 字段 DolphinDB 类型 JSON 字段 JSON 类型 JSON 示例值 转换
symbol STRING Symbol string "LMECA2605" 直接写入
secType STRING SecType string "FUT" 直接写入
exchange STRING Exchange string "LME" 直接写入
localSymbol STRING LocalSymbol string "CA2605" 直接写入
multiplier STRING Multiplier string "25" 直接写入
currency STRING Currency string "USD" 直接写入
minTick DOUBLE MinTick string/number "0.5" 转为 DOUBLE
longName STRING LongName string "LME Copper May 2026" 直接写入
month MONTH Month string "202605" 按 yyyyMM 解析
lastTradeDate DATE LastTradeDate string "20260518" 按 yyyyMMdd 解析
timeZone STRING TimeZone string "Asia/Shanghai" 直接写入
expirationDate DATE ExpirationDate string "20260518" 按 yyyyMMdd 解析
lastTradeTime STRING LastTradeTime string "23:59:59" 直接写入
nameCn STRING name_cn string "铜 2605" 直接写入
nameTc STRING name_tc string "銅 2605" 直接写入
nameEn STRING name_en string "Copper 2605" 直接写入
mainFlag INT MainFlag string/number "1" 转为 INT
tradeDate STRING TradeDate string "20260519:0000-20260520:0000" 可交易日期及时段，不等于 LastTradeDate
underlying STRING Underlying string "CA" 合约标的
receiveTime NANOTIMESTAMP 无 无 无 config["receiveTime"]=true 时由插件生成

order

JSON 协议名为 qhorder。

DolphinDB 字段 DolphinDB 类型 JSON 字段 JSON 类型 JSON 示例值 转换
symbol SYMBOL symbol string "LMECA2605" 字符串写入 SYMBOL
time TIMESTAMP time string/number 1787103585000 13 位 epoch 毫秒直接写入；17 位 yyyyMMddHHmmssSSS 解析为 TIMESTAMP；缺失或 0 为 NULL
localTime TIMESTAMP localtime string/number 1787103585001 13 位 epoch 毫秒直接写入；17 位 yyyyMMddHHmmssSSS 解析为 TIMESTAMP；缺失或 0 为 NULL
bidPrice DOUBLE[] bidprice array<string/number> [9876.0,9875.0] 转为 DOUBLE
bidSize LONG[] bidsize array<string/number> [10,20] 最多五档
askPrice DOUBLE[] askprice array<string/number> [9877.0,9878.0] 转为 DOUBLE，最多五档
askSize LONG[] asksize array<string/number> [11,21] 最多五档
receiveTime NANOTIMESTAMP 无 无 无 config["receiveTime"]=true 时由插件生成

protobuf to DolphinDB

protobuf optional 字段未设置、为 null 或空字符串时，标量输出为 DolphinDB NULL。DolphinDB 的 array vector 不支持单元格 NULL，因此缺失的五档数组输出为空 LONG[]。

snapshot

protobuf 消息号为 302，消息体为 QHClientData。

DolphinDB 字段 DolphinDB 类型 protobuf 字段 protobuf 类型 转换
symbol SYMBOL Symbol string 字符串写入 SYMBOL
time TIMESTAMP Time int64 13 位 epoch 毫秒直接写入；17 位 yyyyMMddHHmmssSSS 解析为 TIMESTAMP；缺失或 0 为 NULL
localTime TIMESTAMP LocalTime int64 13 位 epoch 毫秒直接写入；17 位 yyyyMMddHHmmssSSS 解析为 TIMESTAMP；缺失或 0 为 NULL
price DOUBLE Price int64 按 Decimal 缩放
vol LONG Vol int64 原始整数
totalVol LONG TotalVol int64 原始整数
openInterest LONG OpenInterest int64 原始整数
preOpenInterest LONG PreOpenInterest int64 原始整数
preSettle DOUBLE PreSettle int64 按 Decimal 缩放
settle DOUBLE Settle int64 按 Decimal 缩放
high DOUBLE High int64 按 Decimal 缩放
low DOUBLE Low int64 按 Decimal 缩放
close DOUBLE Close int64 按 Decimal 缩放
open DOUBLE Open int64 按 Decimal 缩放
turnover DOUBLE Turnover int64 按 Decimal 缩放
receiveTime NANOTIMESTAMP 无 无 config["receiveTime"]=true 时由插件生成

codetable

protobuf 消息号为 301，消息体为 QHClientCode。

DolphinDB 字段 DolphinDB 类型 protobuf 字段 protobuf 类型 转换
symbol STRING Symbol string 直接写入
secType STRING SecType string 直接写入
exchange STRING Exchange string 直接写入
localSymbol STRING LocalSymbol string 直接写入
multiplier STRING Multiplier string 直接写入
currency STRING Currency string 直接写入
minTick DOUBLE MinTick double 转 DOUBLE
longName STRING LongName string 直接写入
month MONTH Month string 按 yyyyMM 解析
lastTradeDate DATE LastTradeDate string 按 yyyyMMdd 解析
timeZone STRING TimeZone string 直接写入
expirationDate DATE ExpirationDate string 按 yyyyMMdd 解析
lastTradeTime STRING LastTradeTime string 直接写入
nameCn STRING Name_cn string 直接写入
nameTc STRING Name_tc string 直接写入
nameEn STRING Name_en string 直接写入
mainFlag INT MainFlag int32 转 INT
tradeDate STRING TradeDate string 可交易日期及时段，不等于 LastTradeDate
underlying STRING Underlying string 合约标的
receiveTime NANOTIMESTAMP 无 无 config["receiveTime"]=true 时由插件生成

order

protobuf 消息号为 303，消息体为 QHClientOrder。

DolphinDB 字段 DolphinDB 类型 protobuf 字段 protobuf 类型 转换
symbol SYMBOL Symbol string 字符串写入 SYMBOL
time TIMESTAMP Time int64 13 位 epoch 毫秒直接写入；17 位 yyyyMMddHHmmssSSS 解析为 TIMESTAMP；缺失或 0 为 NULL
localTime TIMESTAMP LocalTime int64 13 位 epoch 毫秒直接写入；17 位 yyyyMMddHHmmssSSS 解析为 TIMESTAMP；缺失或 0 为 NULL
bidPrice DOUBLE[] BidPrice repeated int64 按 Decimal 缩放，最多五档
bidSize LONG[] BidSize repeated int64 最多五档
askPrice DOUBLE[] AskPrice repeated int64 按 Decimal 缩放，最多五档
askSize LONG[] AskSize repeated int64 最多五档
receiveTime NANOTIMESTAMP 无 无 config["receiveTime"]=true 时由插件生成