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

Each call performs these steps, in order:

  1. Resets the session configuration to the packaged module defaults.
  2. Applies any recognized environment variables on top of the defaults. See Environment variables.
  3. Applies recognized keys from config, overriding both the defaults and the environment variables.
  4. Validates auth_type.
  5. Appends the standard REST URL suffix (/omdwebapi/rest/) to rest_url unless it's already present. See Custom REST paths.

Because the configuration is always reset first, you can call .otc.set_credentials repeatedly with partial dictionaries. Keys from an earlier call aren't carried over.

Parameters

Input: A dictionary containing zero or more recognized configuration keys.

Configuration keys

Key Type Description
`rest_url string OneTick REST host or full REST URL
`rest_path string Path appended to rest_url to form the full REST endpoint. See Custom REST paths.
`openid_url string OAuth 2.0 token endpoint URL (auth_type = "openid")
`client_id string OAuth 2.0 client ID (auth_type = "openid")
`client_secret string OAuth 2.0 client secret (auth_type = "openid")
`username string HTTP Basic auth username (auth_type = "httpbasic")
`password string HTTP Basic auth password (auth_type = "httpbasic")
`auth_type string Authentication mechanism. See Auth types.

Auth types

auth_type selects which credentials are mandatory and how the Authorization header is built. Valid values:

auth_type Header sent Mandatory keys
"openid" (default) Authorization: Bearer <token>, obtained through the OAuth 2.0 client credentials flow openid_url, rest_url, client_id, client_secret
"httpbasic" Authorization: Basic <base64(username:password)> rest_url, username, password
"anonymous" No Authorization header rest_url only

Setting auth_type to anything else raises an error listing the valid values.

You can also set auth_type with the OTP_AUTH_TYPE environment variable.

For "openid", the module caches the bearer token on the session and refreshes it automatically if a query gets a 401 response.

Custom REST paths

The module builds the full REST endpoint as rest_url + rest_path.

  • By default, rest_path is /omdwebapi/rest/, so a bare rest_url such as https://rest.cloud.onetick.com resolves to https://rest.cloud.onetick.com/omdwebapi/rest/.
  • To target a different API path on the same host, set rest_path explicitly or with the OTP_REST_PATH environment variable.
  • For backward compatibility, if rest_url already ends with the default suffix (/omdwebapi/rest/), the module clears rest_path so the suffix isn't duplicated. Existing code that passes a full URL in rest_url keeps working unchanged.

Credentials priority

Lowest to highest precedence:

  1. Module defaults ("openid" auth against the OneTick Cloud URLs)
  2. Environment variables
  3. Keys passed directly into .otc.set_credentials[dict]

Return value

None. The function updates the module-level session configuration as a side effect. Resetting the configuration also discards any cached access token. The next query obtains a fresh token using the updated settings.

Usage examples

Protect credentials

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

Reset to defaults and environment variables:

.otc.set_credentials[()!()]

OAuth 2.0 (openid): override client credentials only:

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

OAuth 2.0 (openid): full override including a custom OneTick host:

.otc.set_credentials[`auth_type`rest_url`openid_url`client_id`client_secret!(
    "openid";
    "https://my-onetick-host.example.com";
    "https://my-auth-host.example.com/realms/OMD/protocol/openid-connect/token";
    "my-client-id";
    "my-client-secret")]

HTTP Basic auth (httpbasic):

.otc.set_credentials[`auth_type`rest_url`username`password!(
    "httpbasic";
    "https://my-onetick-host.example.com";
    "my-username";
    "my-password")]

Anonymous / no auth:

.otc.set_credentials[`auth_type`rest_url!("anonymous";"https://my-onetick-host.example.com")]

Custom REST path on a non-default host (any auth type):

// rest_url + rest_path is used as the full REST endpoint
.otc.set_credentials[`auth_type`rest_url`rest_path`username`password!(
    "httpbasic";
    "https://my-onetick-host.example.com";
    "/custom/api/path/";
    "my-username";
    "my-password")]

Full URL already includes the default suffix (rest_path auto-cleared):

// rest_path is cleared automatically because rest_url already ends in /omdwebapi/rest/
.otc.set_credentials[`auth_type`rest_url!(
    "anonymous";
    "https://my-onetick-host.example.com/omdwebapi/rest/")]

Via environment variables (for example, HTTP Basic auth against a custom path):

export OTP_AUTH_TYPE=httpbasic
export OTP_HTTP_ADDRESS=https://my-onetick-host.example.com
export OTP_REST_PATH=/custom/api/path/
export OTP_USERNAME=my-username
export OTP_PASSWORD=my-password

.otc.set_credentials[()!()]  // picks up the environment variables above

See also

  • .otc.get_credentials: returns the current session credentials.
  • .otc.sql_rest: executes a query using the current session credentials, or with opts overrides for a single call.

.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, password, 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
OTP_AUTH_TYPE auth_type Authentication mechanism. See Auth types.
OTP_REST_PATH rest_path Path appended to rest_url. See Custom REST paths.
OTP_USERNAME username HTTP Basic auth username
OTP_PASSWORD password HTTP Basic auth password

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"

Proxy settings

The module accepts the proxy-related environment variables that libcurl accepts:

Lowercase (takes precedence) Uppercase fallback Description
http_proxy Not accepted Proxy for http:// transfers. The module deliberately ignores uppercase HTTP_PROXY because in CGI environments an attacker could inject it through an HTTP_Proxy: request header ("httpoxy").
https_proxy HTTPS_PROXY Proxy for secure https:// transfers.
all_proxy ALL_PROXY Fallback proxy for any scheme that has no scheme-specific variable set.
no_proxy NO_PROXY Comma-separated list of hosts, or * for all hosts, that bypass the proxy.

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