Skip to content

Installing User Defined Analytics

User Defined Analytics (UDAs) allow you to define new APIs for databases to enable data querying and aggregation.

This section explains how to deploy a UDA in kdb Insights SDK that counts the number of records for specified columns and tables within a selected time range, as defined in the Creating a UDA and How to add a UDA to a package documentation.

Info

Users who need to call UDAs must have the insights.query.custom permission.

Prerequisites

Before deploying a package containing a UDA, ensure the following prerequisites are met:

Preparing the UDA

  1. Prepare the UDA package by following the UDA creation guide.

  2. Add the UDA to a package following the How to add a UDA to a package guide.

Note

If you are unfamiliar with how packaging works in kdb Insights Enterprise, it is recommended to review this topic before continuing. This foundational knowledge is essential for understanding how UDAs are packaged and deployed. Refer to the Packaging Overview for more information.

Ensure the package is loaded

  1. Set the necessary environment variables for each component to locate and load the package:

Each component loading custom code from a package must have the KXI_PACKAGES and KX_PACKAGE_PATH environment variables set.

env:
  - name: KXI_PACKAGES
    value: "mypackage"
  - name: KX_PACKAGE_PATH
    value: "/opt/kx/packages"

Mount the package

  1. Mount the package as a volume to the folder specified in KX_PACKAGE_PATH.

Use -v to supply a volume:

docker run -e KX_PACKAGE_PATH=/opt/kx/packages\
  -e KXI_PACKAGES="mypackage"\
  -v /path/to/package:/opt/kx/packages

Set volumes and environment:

services:
  rdb:
    image: dap
    command: -p 5000
    environment:
      - KXI_PACKAGES=mypackage:1.0.0
      - KX_PACKAGE_PATH=/opt/kx/packages/
    volumes:
      - /path/to/package:/opt/kx/packages

Mount a volume under the container:

hostPath is used an example. This may be a persistent volume of any type.

spec:
  spec:
    containers:
      - name: dap
        image: dap
        env:
          - name: KXI_PACKAGES
            value: "mypackage:1.0.0"
          - name: KX_PACKAGE_PATH
            value: "/opt/kx/packages"
        volumeMounts:
        - mountPath: /opt/kx/packages
          name: mypackage-mount
    volumes:
      - name: mypackage-mount
        hostPath:
          path: /opt/kx/packages

Test the UDA

To test the UDA, refer to the example UDAs documentation for examples of queries.

Note

You can use a UDA to modify the end-of-interval (EOI) or end-of-day (EOD) behavior, for example, by adding end-of-execution (EOX) hooks.

The following example package layout includes entrypoints for querying data using the data-access and aggregator components, and an entrypoint for modifying write down behavior using the storage-manager.

Where manifest.json would be:

{
    "name": "example",
    "version": "1.0.0",
    "dependencies": [],
    "metadata": {
        "authors": [
            {
                "name": "author"
            }
        ]
    },
    "entrypoints": {
        "aggregator": "agg.q",
        "data-access": "da.q",
        "storage-manager": "sm.q"
    }
}