Skip to content

OneTick Cloud KDB-X Module Reference

This page documents the public APIs, configuration, authentication, and returned-data behavior of the OneTick Cloud KDB-X module.

Load the module

Import kx.onetickcloud into a namespace before calling its APIs:

.otc:use`kx.onetickcloud

The module exports:

Function Description
.otc.sql_rest Run OneTick SQL and return the main result as a q table
.otc.set_credentials Reset and update the active configuration
.otc.get_credentials Return the active configuration, including sensitive values

.otc.sql_rest

Run a OneTick SQL query.

.otc.sql_rest arg

Where arg is either:

  • A string containing a OneTick SQL statement. The time zone defaults to UTC.
  • A dictionary with the following keys:
Key Required Type Default Description
`sql Yes string None OneTick SQL statement to execute
`timezone No string or symbol "UTC" IANA timezone used to interpret epoch timestamps

Returns an unkeyed q table containing OneTick's main query-result message, PROCESS_EVENT.

Argument examples

sql:"select SYMBOL_NAME, TIMESTAMP, PRICE from LSE_SAMPLE.TRD where SYMBOL_NAME='VOD' and TIMESTAMP >= '2024-01-03 00:00:00 UTC' and TIMESTAMP < '2024-01-04 00:00:00 UTC' limit 10";
data:.otc.sql_rest[sql];

arg:(`sql`timezone)!(
    "select SYMBOL_NAME, TIMESTAMP, PRICE from LSE_SAMPLE.TRD where SYMBOL_NAME='VOD' and TIMESTAMP >= '2024-01-03 08:00:00' and TIMESTAMP < '2024-01-03 09:00:00' limit 10";
    "Europe/London");

data:.otc.sql_rest[arg];

If you omit `timezone, the module uses "UTC".

Returned-data conversion

The module converts the Arrow IPC response as follows:

OneTick response data Returned q data
Main PROCESS_EVENT message Unkeyed q table
Column name containing time, case-insensitive q timestamp
Zero epoch value in a time column Null timestamp 0Np
Character-list column Symbol column
COND or a column name ending in _ID String column
CALLBACK_ID Removed from the result

The module uses PROCESS_SYMBOL_NAME messages internally to populate SYMBOL_NAME when OneTick sends symbol mappings separately.

Request behavior

  • The request is synchronous.
  • The response format is Arrow IPC.
  • The module requests gzip when zlib is available to KDB-X; otherwise, it requests an uncompressed response and prints a warning.
  • The module obtains and caches an OAuth 2.0 access token using the client credentials grant.
  • After HTTP status 401, it refreshes the token and retries once.
  • Other non-200 responses signal an HTTP error.
  • The module exposes no public timeout or general retry parameters.

For KDB-X Community Edition, the module adds a kdb-x-community request header in accordance with the KDB-X telemetry setting.

Errors

The following conditions cause .otc.sql_rest to signal an error:

Condition Signaled error
arg is not a string or dictionary sql_rest: argument must be a string or a dictionary
Dictionary does not contain `sql `sql is mandatory
Required configuration is absent Error: Missing mandatory credentials for query: ...
OneTick returns no PROCESS_EVENT data No data returned.
OneTick reports a SQL exception OneTick exception text, including Invalid SQL statement when applicable
REST response status is not 200 after authentication handling HTTP error <status>: <response>

Use protected evaluation to capture signaled errors:

result:@[.otc.sql_rest;arg;{x}]

.otc.set_credentials

Reset and update the active OneTick configuration.

.otc.set_credentials config

Where config is a dictionary containing one or more recognized configuration keys, or an empty dictionary.

Key Type Description
`rest_url string OneTick REST host or full REST URL
`openid_url string OAuth 2.0 token endpoint URL
`client_id string OAuth 2.0 client ID
`client_secret string OAuth 2.0 client secret

Each call performs these operations in order:

  1. Resets the session to the packaged defaults.
  2. Applies non-empty environment variables.
  3. Applies recognized keys from config.
  4. Appends /omdwebapi/rest/ to rest_url if the suffix is absent.

Reset the configuration and reapply environment variables with:

.otc.set_credentials[()!()]

Override selected fields with placeholder values:

Protect credentials

With kxline enabled, q saves interactive commands to ~/.q_history. Do not enter a real secret directly in the following command. Use placeholders when experimenting interactively, and obtain production credentials through a secure mechanism when calling .otc.set_credentials programmatically.

.otc.set_credentials[(`client_id`client_secret)!("my-client-id";"my-client-secret")]

Resetting the configuration also discards the cached access token. The next query obtains a token using the updated settings.

.otc.get_credentials

Return the active OneTick configuration.

.otc.get_credentials[]

Returns a dictionary containing the active endpoint and credential values. After a successful authenticated request, the dictionary also contains the cached `token value.

config:.otc.get_credentials[]
key config

Sensitive values

The returned dictionary can contain client_secret and the active bearer token. Do not display it in shared consoles, write it to logs, or include it in support bundles.

Configure the module

Packaged defaults

Release archives contain demonstration credentials for accessing the sample datasets documented by OneTick. The built-in account provides access to tick data for trades, quotes, and NBBO (where available) from January 1–7, 2024. It also provides access to the BARS and DAILY sample databases for the first three months of 2024. Queries made with these credentials have a 10 MB response limit.

Setting Packaged default
rest_url https://rest.cloud.onetick.com/omdwebapi/rest/
openid_url https://cloud-auth.parent.onetick.com/realms/OMD/protocol/openid-connect/token
client_id ccf_kdbx_community_app_1
client_secret Packaged demonstration secret

Environment variables

The module reads environment variables when it loads and whenever you call set_credentials.

Environment variable Configuration key Description
OTP_HTTP_ADDRESS rest_url OneTick REST host or full REST URL
OTP_ACCESS_TOKEN_URL openid_url OAuth 2.0 token endpoint URL
OTP_CLIENT_ID client_id OAuth 2.0 client ID
OTP_CLIENT_SECRET client_secret OAuth 2.0 client secret

For example:

export OTP_HTTP_ADDRESS="https://rest.example.com"
export OTP_ACCESS_TOKEN_URL="https://auth.example.com/realms/example/protocol/openid-connect/token"
export OTP_CLIENT_ID="your-client-id"
export OTP_CLIENT_SECRET="your-client-secret"

Configuration precedence

The module applies configuration from lowest to highest precedence:

  1. Packaged defaults.
  2. Non-empty environment variables.
  3. Values passed to set_credentials.

Each layer replaces only the fields it supplies.

Response limits

OneTick applies server-side response limits based on the credentials:

Credentials Documented response limit
Packaged demonstration credentials 10 MB per query
Subscriber credentials 1 GB or 20 GB, depending on the subscription

Apply restrictive time ranges, field lists, and limit clauses to keep responses within the account limit.

Next steps