Using the kdb Insights C SDK
Beta Feature
This feature is in beta stage and subject to change.
This section details how to get started with the C SDK. For examples on how to use it to publish data into kdb Insights Enterprise, see sample program.
Downloading the C SDK
If you would like to try the C SDK please contact KX Support using the KX Support Portal. It will be available soon from the kdb Insights Nexus registry.
The kxi-c-sdk-${VERSION}.zip
file contains everything required to use the C SDK. No installation is required, you can just download the zip file and unzip.
Supported Operating Systems
The driver is supported on the following operating systems:
- CentOS 8 or later
- Red Hat Enterprise Linux (RHEL) 8 or later
- Ubuntu 18.04 or later
Note
The SDKs are only supported on Linux running on x86 architectures. We currently do not support Windows or OsX.
Files extracted
├── include
│ └── rt_helper
│ ├── kdb
│ │ ├── k.h
│ │ └── kk.h
│ ├── ksvc_direct_c.h
│ ├── ksvcrt_c.h
│ └── rt_params.h
├── librt_helper.so
├── push_client
├── replicator_static.so
└── rt_helper_app
Prerequisites
Before building a program that uses the C SDK you need:
- C SDK
cmake
packagelibssl
packagelibcurl
packagelibcsv
package
Using the C SDK in your own application
To publish data to kdb Insights Enterprise using the C SDK as part of your own application, use the rt_helper
. This reads all the information needed to connect to the kdb Insights Enterprise from the variables provided and publishes the data into the system.
Do one of the following:
- Extract the details from the sample program
- Follow the sections below that describe how to publish data
Sample illustration
An example usage of the C SDK to publish to the sdk_sample_assembly
is as follows:
Pre-requisites
- Download the assembly
sdk_sample_assembly
following the instructions here. - Make sure that the assembly is deployed in your kdb Insights Enterprise instance.
- Ensure you have an authenticated kdb Insights Enterprise client URL.
- Make sure that the kdb Insights Enterprise ingest endpoints (as defined by the
KXI_CONFIG_URL
) are accessible.
Initializing
-
Start the
rt_helper
, passing theKXI_CONFIG_URL
and logging level as parameters. A list of all parameters is available here. -
Define the schema. For the
sdk_sample_assembly
you must define the trace table schema as "sensorID:int,captureTS:ts,readTS:ts,valFloat:float,qual:byte,alarm:byte".
#include <rt_helper/kdb/kk.h>
#include <rt_helper/ksvcrt_c.h>
#include <rt_helper/rt_params.h>
RT_Params params = {.configUrl = "{KXI_CONFIG_URL}", .logLevel = "info"};
void *h = ksvcrtc_start(¶ms);
//Define the schema
Schema *schema = ParseSchema("sensorID:int,captureTS:ts,readTS:ts,valFloat:float,qual:byte,alarm:byte");
Parameters
The following parameters are available:
parameter | required | default | description |
---|---|---|---|
configUrl | Mandatory | none | KXI_CONFIG_URL |
configMaxAge | Optional | 300000 | Maximum age of configuration details in milliseconds. After this amount of time, if still unable to fetch a new configuration, the connection is considered to be broken and any subsequent attempts to send data to kdb Insights Enterprise will fail with a Not connected error. This is only needed when using the kdb Insights Enterprise Information Service to obtain the configuration details. |
consoleLogLevel | Optional | err | Console log level (info/warn/err/off) |
fetchConfigSleep | Optional | 5000 | Time in ms to sleep between reads of the configuration details |
localPersistencePeriod | Optional | 600000 | Local persistence period (in milliseconds) |
logLevel | Optional | info | Log level (info/warn/err/off) |
rtDir | Optional | /tmp/rt | RT directory |
queryTimeout | Optional | 2000 | Milliseconds to wait for the connection to be established |
Publishing data
To publish data: 1. Create the message 1. Publish the message
The example below takes a csv record and converts it to a kdb+ object before publishing:
//Create a dummy record
char csv_record[] = "10,2021.01.01D00:00:09.000000000,2021.01.01D00:00:09.000000000,97,1,0";
//Convert the CSV record to a kdb+ data type (this function is available in the sample program)
K k_record = convert_csv_record_to_k_record(schema, csv_record);
//Publish the message
ksvcrtc_insert(h, ks("trace"), k_record);
Terminating
Once you have finished publishing messages you must stop the rt_helper
:
//Stop the rt_helper
ksvcrtc_stop(h);