Skip to content

Preview

The preview API is a lightweight data retrieval API which is able to fetch small samples of a table using minimal time and resources, for you to review or to use in testing software compatibility with a schema.

Parameters

name required type description
table yes symbol Name of table to retrieve data from.
startTS no timestamp Inclusive start time of the period of interest. This field is optional. By default the preview is from the full temporal range of the database. The timestamp must be midnight so the date range covers full days.
endTS no timestamp Exclusive end time of period of interest. This field is optional. By default the preview will be from the full temporal range of the database. The timestamp must be midnight so the date range covers full days.
limit no long Maximum number of rows to return. The default limit is 1000.

Result

The preview API returns up to limit rows from the specified table and time range. It is guaranteed to search all available data for results. If fewer than limit rows are returned, they contain all the available data. Beyond this there are no guarantees as to which particular rows are returned, and the choice is subject to arbitrary implementation details.

Example queries

Gateway URL

The GATEWAY variable in the following example is defined as an IPC connection to the Service Gateway. For example `:insights-qe-gateway:5050 connects to the query environment gateway within an insights namespace.

// API arguments dictionary.
args: (!) . flip (
    (`table;       `trade);
    (`startTS;     "p"$.z.d-5);
    (`endTS;       "p"$.z.d);
    (`limit;       500)
    );

GATEWAY (`.kxi.preview; args; `; ()!())

Gateway URL

Point the $GATEWAY variable at your kdb Insights install. For a microservice install, this is the hostname of the install using port 8080. For an enterprise install, this is your $INSIGHTS_HOSTNAME with /servicegateway as the URL prefix.

curl -X POST "$GATEWAY/preview" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "Authorization: Bearer $INSIGHTS_TOKEN" \
    -d "$(jq -n \
        '{
            table       : "trade",
            startTS     : "2023-12-06T00:00:00.000000000",
            endTS       : "2023-12-11T00:00:00.000000000",
            limit       : 500
        }' | jq -cr .)"