Top函数

针对时间序列数据最常见的查询之一是找出表现最佳的前 N 个工具。

“表现最佳”可能意味着不同的条件或聚合。为了满足 C 和 C++ API 的这一需求，会为所有序列字段生成一个 *_top() 函数。除了为类、字段和索引生成的常规函数外，对于包含一个或多个序列字段的类，mcocomp 会生成函数 classname_fieldname_top()。此 API 允许应用程序避免编写循环来扫描类中的所有对象并计算每个对象的聚合。

请注意，由于此函数会扫描类中的所有对象，因此它可能是一个耗时的函数调用。

对于标量字段，生成的函数原型为：

    MCO_RET classname_fieldname_top( 
    	mco_trans_h trans,
        mco_cursor_h cursor, 
        /*IN-OUT*/ 	mco_size_t* n,
        /*OUT*/		<TYPE>* keys, 
        /*OUT*/		double* aggregates,
        MCO_RET (*aggregate)( 
        	mco_trans_h t, 
        	Security* handle, 
        	/*OUT*/	double* result, 
        	void* ctx),
        MCO_RET (*filter)( 
        	mco_trans_h t, 
        	mco_cursor_h cursor, 
        	void* ctx
        ),
        void* ctx);

函数参数如下：

trans

mco_trans_h

当前事务句柄。

cursor

mco_cursor_h

一个打开且非空的游标（假定调用方首先检查状态码 MCO_S_CURSOR_EMPTY）。

n

mco_size_t*

输入：要接收的最多顶部结果数量；
输出：实际的顶级结果数量；

keys

<TYPE>

一个大小为 n 的数组，用于存储字段名的前 n 个值。

aggregates

double*

一个大小为 N 的数组，用于存储前 n 个聚合值。

aggregate

执行当前记录序列聚合操作的函数，其返回值为：

MCO_S_OK 表示正常完成
MCO_S_NOTFOUND 表示序列为空或由于某种原因无法执行聚合操作，应跳过此对象；
MCO_E_*（任何其他错误代码）表示异常终止。

此函数具有以下参数：

t：当前的事务处理句柄。
handle：当前对象的对象句柄的地址。
result：聚合结果的地址（必须为 double 类型）。
ctx：传递给 _top() 函数的可选用户定义上下文的地址。

filter

一个可选的筛选函数，用于检查当前对象是否满足查询条件。通常需要此函数是因为索引搜索将游标定位到正确的位置，但之后可以在任何方向上导航到结果集的末尾；调用此筛选函数是必要的，以检查查询条件是否仍然满足。如果此参数为 NULL，则会一直遍历到游标的末尾。过滤函数返回：

MCO_S_OK 表示正常完成；
MCO_S_NOTFOUND 表示序列为空或由于某种原因无法执行聚合操作，应跳过此对象；
MCO_S_CURSOR_END 表示没有更多符合查询条件的记录（因此应停止迭代）
MCO_E_*（任何其他错误代码）表示异常终止。

此函数具有以下参数：

t：当前的事务处理句柄。
cursor：一个打开且非空的游标（假定调用方首先检查状态码 MCO_S_CURSOR_EMPTY）。
ctx：传递给 _top() 函数的可选用户定义上下文的地址。

ctx

void*

可选的用户定义上下文的地址。

对于固定大小的字符字段（char， nchar和wchar），原型是：

    MCO_RET classname_fieldname_top(
        mco_trans_h t, 
        mco_cursor_h cursor, 
        /*IN-OUT*/ mco_size_t* n,
        /*OUT*/ <TYPE> keys[][SIZE_OF_TYPE],
        /*OUT*/ double* aggregates,
        MCO_RET (*aggregate)( 
        	mco_trans_h t, 
        	Security* handle, 
        	/*OUT*/	double* result, 
        	void* ctx
        ),
        MCO_RET (*filter)( 
        	mco_trans_h t, 
        	mco_cursor_h cursor, 
        	void* ctx
        ),
        void* ctx
    );

请注意，原型与标量字段相同，只是 keys 参数是一个二维数组，其中最后一个维度的大小等于类型大小。

对于可变长度字符串字段（string、nstring 和 wstring），原型为：

    MCO_RET classname_fieldname_top( 
    	mco_trans_h t, 
    	mco_cursor_h cursor, 
    	/*IN-OUT*/ mco_size_t* n,
        /*OUT*/ <TYPE>** keys, 
        uint2 max_key_len, 
        <TYPE>* buf,
        /*OUT*/ double* aggregates,
        MCO_RET (*aggregate)( 
        	mco_trans_h t, 
        	Security* handle, 
        	/*OUT*/	double* result, 
        	void* ctx
        ),
        MCO_RET (*filter)(
        	mco_trans_h t, 
        	mco_cursor_h cursor, 
        	void* ctx
        ),
        void* ctx
    );

请注意，除以下参数外，参数与标量相同：