Metadata builders

For convenience, we have a set of meta building APIs for defining metadata. A description of each API is given below, and examples are given in (Examples).

The meta-building APIs create entries to populate the metadata fields of APIs and aggregation functions. They live in the .kxi namespace.

.kxi.metaDescription - Creates a description entry for an API/aggregation function's metadata. Parameters:
- descr - string - Description.
.kxi.metaParam - Creates a parameter entry for an API/aggregation function's metadata. Parameters:
- param -dictionary - Dictionary containing any subset of the following keys:
  - name - symbol - Name of the parameter.
  - type - short|short[] - Possible type(s) for the parameter.
  - isReq - boolean - Whether the parameter is required (this is only meaningful for APIs).
  - default - any - Default value of the parameter if it is not required (this is only meaningful for APIs).
  - description - string - Plain text description of the parameter.
.kxi.metaReturn - Creates a return entry for an API/aggregation function's metadata. Parameters:
- return - dictionary - Dictionary containing any subset of the following keys:
  - type - short|short[] - Possible type(s) for the return.
  - description - string - Plain text description of the return value.
.kxi.metaMisc - Creates a miscellaneous metadata entry. Parameters:
- misc - dictionary - Dictionary containing any subset of the supported misc fields:
  - safe - boolean - True if API can be retried safely in the event of a failure, false otherwise.

Examples

//--------------------------------------------------------------------------------
// Metadata using JSON.
//--------------------------------------------------------------------------------
// API.
apiMetaData:()!()
apiMetaData[`description]:"Simple 'select ... from ... where ...' API."
apiMetaData[`param]:flip
 (`name ,`type ,`required ,`default ,`descr)!flip(
 (`table ;98h ;1b ;() ;"Table to query");
 (`filter ;0 10h ;0b ;() ;"Filter (in functional or string form).");
 (`col ;11 -11h;0b ;`sym`time ;"Column(s) to select.")
 )
apiMetaData[`return]:`type`description!(98;"Result of the select.")
.da.registerAPI[`myAPI;apiMetaData] // Or, equivalently ...
.da.registerAPI[`myAPI;.j.j apiDescr] // Stringed
// Agg function.
aggMetaData:()!()
aggMetaData[`description]:"Takes the sum."
aggMetaData[`param]:`name`type`descr!(`x;2 4 5 6 7 8 9h;"Some list of summable vectors.")
.sgagg.registerAggFn[`myAggFn;aggDescr;()] // Or equivalently ...
.sgagg.registerAggFn[`myAggFn;.j.j aggDescr;()] // Stringed
//--------------------------------------------------------------------------------
// Description using just a plain string. This populates just the `description`
// field. This offers a quick way to minimally describe how an API/agg function
// should be used.
// These calls would be equivalent to just using the `description` key in the
// examples above.
//--------------------------------------------------------------------------------
.da.registerAPI[`myAPI;"Simple 'select ... from ... where ...' API."]
.sgagg.registerAggFn[`myAggFn;"Takes the sum.";()]
//--------------------------------------------------------------------------------
// Metadata using a default dictionary. This only populates the `params` field.
// Also note that it marks all parameters optional.
//--------------------------------------------------------------------------------
.da.registerAPI[`myAPI;`table`filter`col!(`trade;();`sym`time)]
//--------------------------------------------------------------------------------
// Metadata using the meta-building APIs.
//--------------------------------------------------------------------------------
.da.registerAPI[`myAPI;
 .kxi.metaDescription["Simple 'select ... from ... where ...' API."],
 .kxi.metaParam[`name`type`isReq`description!(`table;-11h;1b;"Table to query")],
 .kxi.metaParam[`name`type`isReq`default`description!(`filter;0 10h;0b;();"Filter (in functional or string form).")],
 .kxi.metaParam[`name`type`isReq`default`description!(`col;11 -11h;0b;`sym`time;"Column(s) to select.")],
 .kxi.metaReturn[`type`description!(98h;"Result of the select.")],
 .kxi.metaMisc[enlist[`safe]!enlist 1b]
 ]
// Note: Can only have 1 parameter for an agg function.
.sgagg.registerAggFn[`myAggFn;
 .kxi.metaDescription["Takes the sum."],
 .kxi.metaParam[`type`description!(2 4 5 6 7 8 9h;"Some list of summable vectors.")],
 .kxi.metaReturn[`type`description!(6 7 8 9h;"The sum of the lists.")];
 ()
 ]
//--------------------------------------------------------------------------------
// No description at all.
//--------------------------------------------------------------------------------
.da.registerAPI[`myAPI;()]
.sgagg.registerAggFn[`myAggFn;();()]