基于逐笔数据合成高频 Orderbook：DolphinDB Orderbook 引擎

Orderbook 引擎采用基于消减的合成逻辑，仅需输入逐笔委托与逐笔成交数据即可：

• 在一个通道内，按 ApplSeqNum 有序逐条处理逐笔数据。ApplSeqNum 为交易所原始消息记录号，也称为 BizIndex，同频道内自 1 开始计数；
• 当收到委托时缓存委托单的价格和量，当收到成交和撤单时，从缓存中减去对应委托单的价格和量；
• 通过引擎内部缓存的委托单信息可以计算出每个报价的委托量、委托笔数等信息。

整体的合成逻辑如上，在此基础上也会遵循交易规则修正后再输出 Orderbook，以保证输出结果的准确性。比如对于深交所股票，引擎支持创业板价格笼子判断，部分报价会因为触发价格笼子规则而不体现在 Orderbook 中，用户可以通过参数控制是否启动该规则。

通过将引擎计算结果与交易所发布的 3 秒快照进行比较，可以验证引擎内部合成逻辑的正确性。具体的校验方案与实现脚本见本文第 5 章。

Orderbook 快照表示了某个时刻的 Orderbook 截面，截面表示的窗口范围以及何时进行截面都由引擎自动控制。接下来我们介绍引擎在窗口时间、触发窗口的时机等方面的工作原理。

当 Orderbook 引擎设置的输出频率为 1 秒时，若输出一条时间戳字段为 10:00:00 的计算结果，该计算结果表示的是时间戳小于等于 10:00:00 的全部逐笔形成的最新 Orderbook。一些窗口指标如当前周期内成交量，则对应的是在 (09:59:59, 10:00:00] 这个左开右闭区间内的逐笔数据的总成交量。仅有时间戳为 14:57:00 的结果的含义稍有不同，引擎的输出到 14:57:00 就会停止，即引擎的处理与输出不包含收盘集合竞价阶段，所以 14:57:00 的计算结果对应 (14:56:59, 14:57:00) 这个左开右开区间内的逐笔数据。

在实时合成时，逐笔数据逐条进入引擎，引擎需要一个规则来判断何时窗口内的逐笔数据全部到齐了。以输出 10:00:00 的 Orderbook 为例，判断规则是一旦收到一条时间戳大于 10:00:00 的逐笔数据（包含委托和成交），则认为应该输出 10:00:00 的计算结果了。计算结果中不包含触发输出的这条逐笔数据。此判断规则可以基于单支标的或全部标的。当指定单支标的时，每支标的收到一条时间戳大于 10:00:00 的逐笔数据时，仅触发计算并输出该标的的 Orderbook。当指定全部标的时，收到任意标的的时间戳大于 10:00:00 的逐笔数据时，触发计算并输出全部标的的 Orderbook。

此外，若某一段时间的逐笔数据空缺，则输出也会空缺，以午盘休市为例，引擎不会输出11:30:01-12:59:59 时间戳的 Orderbook，因为没有这段时间的逐笔数据。

严格地按照逐笔数据里的时间戳截取 Orderbook 快照，将能够保证实盘和历史计算总能得到一致的结果，实现“流批一体”。根据已有的落地实践经验，在实盘中，我们推荐将一个通道中全部的标的视为一个整体，用全部标的的事件时间（即数据中的交易时间字段）来判断何时截取快照，这种方式能够保证尽快且准确地推出 Orderbook 快照。此外，为了满足不同的场景需求，后续版本中也将推出基于机器时间的 Orderbook 处理，即机器时间每经过一个时间间隔输出一次最新的 Orderbook。

在实盘环境中，接入到系统中的逐笔数据可能发生乱序，如不能正确处理乱序会影响 Orderbook 合成的正确性。在交易所内部系统中，每个交易通道中的标的发生的委托和成交事件都会被赋予一个顺序号，即 ApplSeqNum。这个顺序号反映了事件在交易所内部实际发生的顺序。数据乱序，是指可能是由于网络延迟或其他技术问题导致的事件没有严格按照 ApplSeqNum 到达数据处理系统。因此，数据处理系统收到的逐笔数据可能需要重新排序，以确保它们反映了在交易所内部实际发生的顺序。

例如，如果标的A的逐笔成交比对应的逐笔委托先到达，引擎按到达顺序处理，先处理成交再处理委托则会得到错误的 Orderbook 结果。为此，Orderbook 引擎支持指定输入数据中的 ApplSeqNum 字段，引擎会检测并缓存 ApplSeqNum 发跳变的数据，在接收到正确 ApplSeqNum 的数据后再计算输出，可以保证 Orderbook 合成的正确性。用户可以根据业务需求和接收到的数据质量，选择是否开启处理乱序数据的功能。

下图展示了收到不同的 ApplSeqNum 时的处理方式，从左至右表示了时间先后顺序，即最先收到ApplSeqNum=1的输入数据。

2.00.12及以上版本，支持沪深两市的股票、基金以及可转债等证券类型的 Orderbook 合成。更具体的规则支持性如下：

• 通过参数控制是否包含创业板价格笼子规则。深交所股票默认按全面注册制启动以前的规则处理的，其中包含创业板价格笼子规则；
• 包含对市价单、本方最优单等委托单的处理逻辑，能够以正确的价格输出到 Orderbook 上；
• 沪深可转债按2022年08月启动的新规进行处理；
• 不包含上市前5日创业板的特殊规则，即不保证创业板标的上市前5日的 Orderbook 正确性；
• 不包含上市首日主板的特殊规则，即不保证主板标的上市首日的 Orderbook 正确性。

• 成交和委托的合并表

Orderbook 引擎的输入为一张表，该表需要同时包含逐笔成交数据和逐笔委托数据。将逐笔成交、逐笔委托处理成相同的表结构可以存储到同一张输入表中。

• 完整的必选输入字段

输入数据至少包含以下 10 个字段，引擎计算依赖这 10 种数据内容。引擎创建时必须指定参数 inputColMap，该参数为字典，其指定了引擎计算需要的各种数据内容对应的输入数据中的字段名称。此外，输入表中可以冗余其他字段。

• 规范的枚举值

  Orderbook 引擎约定了以上字段中的枚举类型列中的枚举值。输入表中的枚举值必须符合约定才能得到正确结果。如 BSFlag 字段，约定1代表买方向， 2代表卖方向。

• seqColumn 列的注意事项

  • 深交所的委托单中的 seqColumn 列表示了委托单号，之后撤单和成交时都需要找到这个对应的委托单号，因此 seqColumn 代表的值必须正确。
  • 除上述含义以外，seqColumn 列还可以用于判断逐笔数据的处理顺序。Orderbook 引擎创建时指定参数 orderBySeq=false，则引擎依赖输入数据进入引擎的先后顺序逐条处理。创建时若指定参数 orderBySeq=true，则引擎依赖 seqColumn 列中值的大小顺序逐条处理数据，工作原理见 1.3 对输入数据乱序的处理小节。
  • 深交所股票、深交所可转债、深交所基金、上交所可转债分别在各自的通道中。上交所的基金和股票会在同一通道内。一个通道内的 ApplSeqNum 从1开始连续编号。

• 对于同一个 Orderbook 引擎，至多只能输入一天一个通道的全部标的

引擎内部为每支标的维护一个累积的 Orderbook，并且不会在新的交易日清除前一天的状态，因此引擎不允许跨越多个交易日计算 Orderbook。此外，若引擎的触发机制是任意到来一支标的的最新数据就触发全部标的输出（参数 triggerType=”mutual”），那么用同一个引擎处理多个通道（原始逐笔数据中的 ChannelNo ）也是不建议的，因为多个通道按 ApplSeqNum 递增排序后，逐笔时间字段可能不再递增，则将导致提前触发输出。

通常逐笔成交数据和逐笔委托数据以不同的表结构存储在不同的文件或者数据库表中，本例提供批量合并成交和委托至同一张表中的示例。由于深交所数据和上交所数据的差异，本章分为两个小节逐一介绍。

在实时数据接入 Orderbook 引擎时，建议保证逐笔成交和逐笔委托以交易所发送的真实顺序有序写入 DolphinDB 流数据表中。如果逐笔数据在抵达 DolphinDB 服务器时 ApplSeqnum 出现乱序，可以在创建引擎时指定 orderBySeq=true，由引擎保证按 seqColumn 的顺序处理数据。实时数据接入的大致流程如下:

• 首先在 DolphinDB 中创建流数据表，可以是共享流数据表，也可以是持久化流数据表。
• 其次，通过行情 sdk 同时订阅逐笔成交和逐笔委托数据。在行情 sdk 的回调函数中解析收到的逐笔成交和逐笔委托数据、转换枚举值。
• 最后，将同一个通道的逐笔成交和逐笔委托数据写入同一张流数据表 。

一般有两种方式将实时数据源接入 DolphinDB server 中：

• 方案一：使用行情数据源插件。目前，amdQuote、INSIGHT 插件已经支持将委托和成交接收到同一张表中，并且内置实现了枚举值转换。通过 amd 插件/insight 插件可以直接接收到 Orderbook 引擎期望的输入数据。
  • amd 插件： amdQuote（LINUX）
  • insight 插件：INSIGHT
  • 其余行情插件也将陆续支持此功能，最新进展见官网文档。如有需求也可以联系 DolphinDB 小助手进一步咨询。
• 方案二：使用 DolphinDB API 编写外部程序，推荐使用 MultithreadedTableWriter 接口往 DolphinDB 实时写入数据，具体开发可以参考上述流程和插件源码。

首先创建 Orderbook 引擎，以下脚本中名为“demo”的 Orderbook 引擎的功能是每1秒计算输出深交所股票10档 Orderbook，并且扩展了逐笔成交明细字段。

// 获取 Orderbook 引擎的输出表结构
depth = 10
orderBookAsArray =true
outputColMap, outputTableSch = genOutputColumnsForOBSnapshotEngine(basic=true, time=true, depth=(depth, orderBookAsArray), tradeDetail=true, orderDetail=false, withdrawDetail=false, orderBookDetailDepth=0, prevDetail=false)
// 定义引擎参数outputTable，即指定输出表
outTable = table(1:0, outputTableSch.schema().colDefs.name, outputTableSch.schema().colDefs.typeString)
// 定义引擎参数dummyTable，即指定输入表的表结构
colNames = `SecurityID`Date`Time`SourceType`Type`Price`Qty`BSFlag`BuyNo`SellNo`ApplSeqNum`ChannelNo`ReceiveTime
colTypes = [SYMBOL, DATE, TIME, INT, INT, LONG, LONG, INT, LONG, LONG, LONG, INT, NANOTIMESTAMP]
dummyOrderTrans = table(1:0, colNames, colTypes)
// 定义引擎参数inputColMap，即指定输入表各字段的含义
inputColMap = dict(`codeColumn`timeColumn`typeColumn`priceColumn`qtyColumn`buyOrderColumn`sellOrderColumn`sideColumn`msgTypeColumn`seqColumn`receiveTime, `SecurityID`Time`Type`Price`Qty`BuyNo`SellNo`BSFlag`SourceType`ApplSeqNum`ReceiveTime)
// 定义引擎参数prevClose，即昨日收盘价，prevClose不影响最终的输出结果中除昨日收盘价以外的其他字段
prevClose = dict(`000400.SZ`300274.SZ`300288.SZ`300122.SZ`300918.SZ, [1.1, 2.2, 3.3, 4.4, 5.5])
// 创建引擎，每1s计算输出深交所股票10档 Orderbook
engine = createOrderBookSnapshotEngine(name="demo", exchange="XSHE", orderbookDepth=depth, intervalInMilli=1000, date=2022.01.10, startTime=09:30:00.000,  prevClose=prevClose, dummyTable=dummyOrderTrans, inputColMap=inputColMap, outputTable=outTable, orderBySeq=false, outputColMap=outputColMap, orderBookAsArray=orderBookAsArray)

• 与上一小节不同，在调用 createOrderBookSnapshotEngine 函数创建引擎时，本节指定了 outputColMap 参数，用于选择需要输出的字段。而上一小节没有指定 outputColMap ，则输出了默认的字段。outputColMap 的具体使用方式和引擎的默认输出请参考 createOrderBookSnapshotEngine 函数的用户手册。
• 为了方便用户使用 outputColMap 参数选择需要输出的字段，DophinDB server 提供了genOutputColumnsForOBSnapshotEngine 函数，该函数返回要求引擎输出包含的字段以及对应的输出表结构。genOutputColumnsForOBSnapshotEngine 函数的参数是用于指定输出字段，本节设置 basic、time、depth 和 tradeDetail 为 true ，其余都设置为 false，表示只需要基础成交信息、时间、Orderbook 以及成交明细字段。
• genOutputColumnsForOBSnapshotEngine 函数的参数 time=true 时会返回多个时间字段，它们同样是引擎可以输出指标。这些时间字段是可选的，主要功能是方便统计计算性能，其包含每条计算结果输出时的系统时间，以及触发计算结果输出的原始逐笔的接收时间。为此，在指定 inputColMap 参数时需要包含 ReceiveTime 这个key，使引擎能获取输入的每条逐笔数据的接收时间。
• 此外，本节还指定了 orderBookAsArray=true，表示以 array vector 的形式输出多档量价，即 10 档买方价格存储在同一个字段中。反之，10 档买方价格分别存储在 10 个字段中。

接着，将历史数据注入 Orderbook 引擎。与上一小节不同，本节的输入数据多了一列 ReceiveTime，表示每条逐笔数据的接收时间。

t = select * from loadText("./orderTrans.csv") order by ApplSeqNum
update t set ReceiveTime = now(true) // 构造接收时间列
getStreamEngine("demo").append!(t)

输出结果表 outTable 如下：

首先创建 Orderbook 引擎，以下脚本中名为“demo”的 Orderbook 引擎的功能是每 1 秒计算输出深交所股票 10 档 Orderbook，并且扩展了 4 个用户自定义指标，指标定义如下：

// 定义 Orderbook 深度等
depth = 10
orderBookAsArray =true
outputColMap = genOutputColumnsForOBSnapshotEngine(basic=true, time=false, depth=(depth, orderBookAsArray), tradeDetail=true, orderDetail=false, withdrawDetail=true, orderBookDetailDepth=0, prevDetail=false)[0]
// 定义引擎参数 dummyTable，即指定输入表的表结构
colNames = `SecurityID`Date`Time`SourceType`Type`Price`Qty`BSFlag`BuyNo`SellNo`ApplSeqNum`ChannelNo
colTypes = [SYMBOL, DATE, TIME, INT, INT, LONG, LONG, INT, LONG, LONG, LONG, INT]
dummyOrderTrans = table(1:0, colNames, colTypes)
// 定义引擎参数 inputColMap，即指定输入表各字段的含义
inputColMap = dict(`codeColumn`timeColumn`typeColumn`priceColumn`qtyColumn`buyOrderColumn`sellOrderColumn`sideColumn`msgTypeColumn`seqColumn, `SecurityID`Time`Type`Price`Qty`BuyNo`SellNo`BSFlag`SourceType`ApplSeqNum)
// 定义引擎参数 prevClose，即昨日收盘价，prevClose不影响最终的输出结果中除昨日收盘价以外的其他字段
prevClose = dict(STRING, DOUBLE)
//// 定义用户自定义因子
def userDefinedFunc(t){
        AvgBuyDuration = rowAvg(t.TradeMDTimeList-t.TradeOrderBuyNoTimeList).int()
        AvgSellDuration = rowAvg(t.TradeMDTimeList-t.TradeOrderSellNoTimeList).int()        
        BuyWithdrawQty = rowSum(t.WithdrawBuyQtyList)
        SellWithdrawQty = rowSum(t.WithdrawSellQtyList)
        return (AvgBuyDuration, AvgSellDuration, BuyWithdrawQty, SellWithdrawQty)
}
// 定义 Orderbook 引擎的输出表
outputTableSch = genOutputColumnsForOBSnapshotEngine(basic=true, time=false, depth=(depth, orderBookAsArray), tradeDetail=false, orderDetail=false, withdrawDetail=false, orderBookDetailDepth=0, prevDetail=false)[1]
colNames = outputTableSch.schema().colDefs.name join (`AvgBuyDuration`AvgSellDuration`BuyWithdrawQty`SellWithdrawQty)
colTypes = outputTableSch.schema().colDefs.typeString join (`INT`INT`INT`INT) 
outTable = table(1:0, colNames, colTypes)
// 创建引擎，每1s计算输出深交所股票10档 Orderbook
try{dropStreamEngine(`demo)} catch(ex){}
engine = createOrderBookSnapshotEngine(name="demo", exchange="XSHE", orderbookDepth=depth, intervalInMilli=1000, date=2022.01.10, startTime=09:30:00.000,  prevClose=prevClose, dummyTable=dummyOrderTrans, inputColMap=inputColMap, outputTable=outTable, outputColMap=outputColMap, orderBookAsArray=orderBookAsArray, userDefinedMetrics=userDefinedFunc)

• 创建引擎时指定了 userDefinedMetrics 参数，它是一个一元函数，用于自定义指标的计算逻辑。该函数的入参必须是一张表，这张表的每一行是一个标的的快照，快照的每一列是 outputColMap 参数指定的引擎内置指标。用户可以操作这些引擎内置的指标实现自定义指标。本节中我们用引擎提供的两笔 Orderbook 快照之间的逐笔成交明细和撤单明细，计算了这个窗口内的挂单时长和撤单量等指标。
• 注意，当指定 userDefinedMetrics 参数后，引擎的输出表结构不再和 outputColMap 参数的内容一一对应，而是仅包含两部分内容：一部分是 genOutputColumnsForOBSnapshotEngine 函数对应的 basic 和 depth 指标；另一部分是用户自定义指标。

接着，用历史数据注入 Orderbook 引擎。

t = select * from loadText("./orderTrans.csv") order by ApplSeqNum
getStreamEngine("demo").append!(t)

输出结果表 outTable 如下，红框部分为用户自定义指标：

我们对 Orderbook 引擎直接注入了一天一整个通道的六百多支深交所股票，使用 timer 语句测试计算耗时。测试显示 1 秒频率的 Orderbook 仅需 1 分 57 秒。由于 10 毫秒频率的 Orderbook 的数据量大约是 1 秒频率的 3 倍多，输出耗时的增加导致了 10 毫秒频率的 Orderbook 的总耗时会更高。

测试结果：

测试环境：

DolphinDB：2.00.12 2024.04.02

物理服务器：

• 内核： Linux 3.10.0-1160.el7.x86_64 x86_64
• CPU：Intel(R) Xeon(R) Silver 4216 CPU @ 2.10GHz
• Mem：503 GB

我们测试了在实盘中，通过 INSIGHT 行情数据源插件实时接收深交所全市场股票的逐步数据，通过发布订阅实时写入 Orderbook 引擎的计算耗时。由于深交所股票分布在 4 个通道中，因此我们创建了4个不同的 Orderbook 引擎分别在4个消费线程上运行。测试显示，1 秒频率 Orderbook 快照的单条响应耗时约 0.67 毫秒，即收到触发输出的逐笔数据后仅 0.67 毫秒即可推出最新的快照。

测试结果：

注：响应耗时不仅包含引擎内部的计算耗时，也包含逐笔数据发布并写入计算引擎的耗时。在实盘中，通过 UpdateTime2 - UpdateTime1 可以计算出每一条快照的响应耗时，其中 UpdateTime2 是由引擎记录的完成计算的时刻，UpdateTime1 是系统接收到逐笔数据的时刻（ ReceiveTime 字段），每条快照的 UpdateTime1 取触发该条快照输出的那一条逐笔数据的接收时刻。

测试环境：

DolphinDB：2.00.12 2024.04.02

物理服务器：

• 系统：CentOS Linux release 7.9.2009 (Core)
• 内核： Linux 3.10.0-1160.el7.x86_64 x86_64
• CPU：Intel(R) Xeon(R) Silver 4216 CPU @ 2.10GHz
• Mem：503 GB

检查输出结果表中的 abnormal 字段全为 false，表示快照合成过程中没有出现接收到成交或者撤单时找不到逐笔委托的情况，即表示输入数据没有缺失或者乱序。测试代码如下，outTable 表为 Orderbook 引擎的输出结果表。

outTable = loadText("./engineOutput.csv")
@testing: case = "abnormal"
assert (exec count(*) from outTable where bool(abnormal)=true)==0

以上代码执行后，若无任何返回则代表测试通过，若返回 abnormal 则表示测试失败。

在通过 5.1 小节的校验后，可以以交易所原始的 3s 快照作为基准，对合成结果的各个指标字段进行正确性校验。

注意，不能按时间戳直接关联来比较两者，因为交易所的快照和逐笔数据是两个系统产生并发出的，这导致交易所快照的时间戳与逐笔数据的时间戳并不一致。Orderbook 快照其实是某一个时刻的 Orderbook 的截面，假设我们能得到足够密集的截面，那么交易所原始 3s 快照将是其子集。因此，推荐以合成出的高频快照是否包含全部的交易所快照来判断合成结果是否正确。

以深交所股票为例，通过 Orderbook 引擎生成 10ms 频率的快照，以交易所 3 秒快照被 10ms 合成快照覆盖的多少来评价 Orderbook 引擎的正确性。一条 3s 快照能够在 10 ms 快照结果中找到一条相同买卖十档盘口的记录且所有被找出的 10 ms 快照数据的时间戳有序递增，则认为该条 3s 快照被覆盖。

输入数据

此处仅以深交所数据为示例，引擎合成结果文件：engineOutput10s.csv

交易所 3s 快照文件：tick.csv

比对脚本

以下两段脚本共同完成对一支股票一天的合成结果进行校验。首先关联两份不同的 Orderbook 数据：

// 登录
login("admin", "123456")
// 指定比对股票和日期
id ="300274.SZ"
compareDate=2022.06.01
// 获取原始的快照数据
orgTickPath = "./tick.csv"
originTick = select * from loadText(orgTickPath) where SecurityID=id and MDDate=compareDate and ((MDTime between 09:30:00.000:11:30:00.000) or (MDTime between 13:00:00.000:14:56:59.000)) order by MDTime
// 获取生成的快照数据
genTickPath = "./engineOutput10s.csv"
generateTick = select * from loadText(genTickPath)  where SecurityID=id and date(timestamp)=compareDate order by timestamp
// 设置真实快照数据比对字段
orgColNames = `SecurityID`MDTime`LastPx`HighPx`LowPx`TotalBidQty`TotalOfferQty join ("BuyPrice" + string(1..10))  join ("BuyOrderQty" + string(1..10)) join ("BuyNumOrders" + string(1..10)) join ("SellPrice" + string(1..10)) join ("SellOrderQty" + string(1..10)) join ("SellNumOrders" + string(1..10)) 
// 设置生成快照数据比对字段
genColNames = `SecurityID`timestamp`lastPx`highPx`lowPx`bidVol`askVol join ("bids" + string(1..10))  join ("bidVolumes" + string(1..10)) join ("bidOrderNums" + string(1..10)) join ("asks" + string(1..10)) join ("askVolumes" + string(1..10)) join ("askOrderNums" + string(1..10)) 
// 计算快照表的content 形式数据展示表
def calContent(contentColNames, tickTable, format="0.00"){
	contentStr=concat("format(" +contentColNames[2:] +", \""+format+"\")", "+\",\"+")
	contentSql=parseExpr(contentStr)
           	return sql(select=(sqlCol(contentColNames[0]),sqlCol(contentColNames[1]),sqlColAlias(contentSql, "Content")), from=tickTable).eval()
}
// 生成原始快照表比对content表
originContent=calContent(orgColNames, originTick, "0.00")
// 生成合成快照表比对content表
generateContent=calContent(genColNames, generateTick, "0.00")
// 两个快照表进行Content 比对，以原始快照表为左表
jointable =  select * from lsj(originContent as a ,generateContent as b, `Content, `Content)

• originTick 表为交易所 3s 快照，generateTick 为 Orderbook 引擎输出的 10ms 快照。
• orgColNames 和 genColNames 为向量，前两个元素为股票 id 和日期列名，其余为需要进行数值比对的指标列名。注意：不要指定和当前周期有关的指标，比如当前周期内成交量，因为两个快照的频率不同，所以这类指标是一定无法重合的。
• calContent 函数的功能是将快照中的多个指标字段按字符串拼接为一个字符串类型的字段 content 。format 参数指定了数据的精度，股票需要设置为”0.00”，表示两位小数精度，可转债需要设置为“0.000”，表示三位小数精度。
• 最后通过 lsj 将两个快照表的 content 进行左半连接，3s 快照表为左表，关联的结果表 jointable 行数和 3s 快照表一致。

以下脚本对关联结果表 jointable 进行统计和校验：

• 第一个测试 case，测试 3 秒快照被 10ms 合成快照覆盖率大于等于 99，若不通过则返回 Not Covered
• 第二个测试 case，测试 3 秒快照对应的全部 10 ms 合成快照按时间戳有序，若不通过则返回 Not In Order。

// 3 秒快照被 10ms 合成快照覆盖率大于等于100 ，断言为测试通过
@testing: case = "Not Covered"
assert (exec count(b_SecurityID)\count(*)*100 as coverage from jointable ) >= 99
// 3 秒快照的全部 10 ms 合成快照按时间戳有序，断言为测试通过
flag = true 
if(at(deltas(jointable.timestamp)[1:]<=0).size()==0) {
	break
}else { 
	leftTime = 09:15:00.000
	for (row in originContent){
		genCon = exec Content from generateContent where time(timestamp)>= leftTime 
		genTime = exec time(timestamp) from generateContent where time(timestamp)>= leftTime 
		findGenTime = genTime[genCon.find(row.Content)]
		if (findGenTime==NULL){
			flag=false
			break
		} else { 
			leftTime=findGenTime
		}
	}
}
@testing: case = "Not In Order"
assert flag

如果上述校验不通过，可以减少比对的字段数量来定位具体有问题字段。校验不通过的原因主要有：

• 输入数据的预处理不正确。正确处理方式请参考第 2 章检查。
• 引擎输出结果与交易所 3s 快照的精度差异，比如引擎输出的总成交金额为小数，有一些数据源的总成交金额为整数。
• 空值和0的差异，上述样例脚本如果遇到空值和0比较时，则认为校验不通过。可以通过以下脚本，将快照数据中的空值全部置0，再进行校验：

originTick = nullFill(originTick, 0)
generateTick = nullFill(generateTick, 0)

引擎的可选参数 outputIntervalOffsetMap 为字典，用于指定输出表中股票被触发计算的时间偏移量。字典的 key 为字符串类型，表示标的 id，字典的 value 为整型，表示偏移量（单位：毫秒）。依然以合成 1s 频率 Orderbook 为例，假设有三支标的 id1、id2、id3，通过 outputIntervalOffsetMap 参数（dict(["id1","id2","id3"], [0, 50, 50])）可以实现下图的效果。

上图中两组标的在不同时间点产生快照，id1 这支标的的输出数据时间戳为 hh:MM:00.000，id2、id3 这两支标的的输出时间戳为 hh:MM:ss.050 ，即整秒过50ms。

合理使用本参数能够带来如下优化：一方面减少输出的数据量可以减少每批快照输出的耗时，更重要的是减少同一个时间点输出的标的数量，可以减少下游消费的压力，保证下游能更充费利用计算资源。否则总是在同一个时刻发送大量数据，对于下游消费来说可能会导致一段时间特别忙碌，一段时间特别空闲，不能合理利用资源。

示例代码，(#31-合成-1-秒频率 Orderbook)的代码做以下补充修改：

outputIntervalOffsetMap =dict(`300288.SZ`300122.SZ`300918.SZ, [50, 50, 50])
engine = createOrderBookSnapshotEngine(name="demo", exchange="XSHE", orderbookDepth=10, intervalInMilli=1000, date=2022.06.01, startTime=09:15:00.000, prevClose=prevClose, dummyTable=dummyOrderTrans, inputColMap=inputColMap, outputTable=outTable, outputIntervalOffsetMap=outputIntervalOffsetMap)

300288.SZ、300122.SZ、300918.SZ 三支股票将在整秒过 50ms 输出，其余股票因为未指定偏移量则仍然在整秒输出。

不是，通过参数 inputColMap 指定映射关系来识别计算所需的字段即可。

不是，通过参数 outputColMap 指定指定需要输出的字段。注意 outputTable 的表结构需要与之对齐。

引擎收到成交数据、撤单数据时会在其内部维护的 Orderbook 中找对应的委托，如果找不到，则认为发生异常。异常时会同时有两种提示，一是会在日志中报错，二是会将之后的输出结果中该股票的 abnormal 字段全部设置为 true。日志报错如下：

如果 abnormal 为 true ，建议排查是否发生了以下任意一种情况：

• 排查是否发生了逐笔数据乱序或者丢失。这可能造成成交或撤单数据到达引擎之前，对应的委托数据并没有到达；
• 排查 inputColMap 对应的列是否有异常，比如买卖单号为空等异常情况，这可能造成成交数据中的委托单号和原始委托号并不能对应上。

委托、撤单的 BSFlag 是必须的，Orderbook 结果的正确性依赖委托和撤单的 BSFlag 字段。成交的 BSFlag 不是必须的，但是也建议包含成交的 BSFlag。

若您的原始逐笔数据里撤单和成交都没有 BSFlag 字段，可以通过以下逻辑补充出引擎所需的 BSFlag：

• 撤单：卖单撤单则 BSFlag 为2，买单撤单则 BSFlag 为1；
• 成交：卖方主动成交则 BSFlag 为2，买方主动成交则 BSFlag 为1。

以深交所为例，假设您的撤单记录中有 BuyNo 和 SellNo，其中一方为委托单号，另一方为 0，则在 2.2 小节预处理输入数据方法的基础上，可以增加如下对 BSFlag 的判断。对成交记录同样适用，对于 BSFlag 为 N （未知）也适用。

iif(SellNo>BuyNo, 2, 1) as BSFlag

有两种情况可能造成上述现象：

• 情况1：若设置了 orderBySeq=true（注意，对于上交所股票该参数默认为 true，其余默认为 false），可能因为输入数据的 seqColumn 不连续造成以上现象。此时，日志里有异常提示。日志示例如下，省略号（...）为具体异常内容，timestamp 指的是合成出的那一条快照的时间戳。

expected seq num: ...,  unordered buffer size: ..., the last seq num get: ...

• 情况2：若设置了 skipCrossedMarket=true（注意，2.00.11.2及以上版本该参数默认为 true）， 当买一卖一价倒挂时（bidPrice1 >= askPrice1），该条 Orderbook 将不会输出。为了方便排查这种情况，在 2.00.12 及以上版本，日志里增加了对应的异常提示。日志示例如下，省略号（...）为具体异常内容：

orderBook engine abnormal snapshot.symbol: ... ,ask price ... ,bids price: ... ,timestamp:...);