Installing User Defined Analytics

This page explains how to deploy an example UDA in kdb Insights Enterprise.

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

Permission to call UDAs

You must have the insights.query.custom permission, which is included in the Viewer Composite role, to call UDAs.

Prerequisites

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

Access to a kdb Insights instance
The kxi CLI is installed and configured on your system.

Preparing the UDA

Prepare the UDA package by following the UDA creation guide.
Add the UDA to a package by following the How to add a UDA to a package guide.

Understanding Packaging in kdb Insights Enterprise

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 documentation for more information.

Deploying the UDA

If you have an aggregation function defined as part of the UDA you need to decide where the aggregation is executed. The options are:

The global Aggregator: This is deployed as part of kdb Insights Enterprise. This can traverse all databases in packages that also include the UDA.

To deploy the UDA using this aggregator, ensure you have kubectl access.
The dedicated Aggregator: This is deployed as part of a package which can only query the database in the package.

When calling this UDA you must specify the scope parameter as the query needs to be routed to this aggregator.
If the package requires a dedicated Aggregator, ensure both an Aggregator and a Resource Coordinator are included. If they are not included in the package you can add them as follows:
```
kxi package add --to mypackage agg
kxi package add --to mypackage rc
```
Push and deploy the package(s) to kdb Insights Enterprise.
1. Refer to the Authentication documentation for authentication details.
2. Use the KXI CLI to create users, and assign roles, if they are not already present. For more information on the CLI, refer to the kdb Insights Command Line documentation.
  
  Administrator password
  
  The administrator password below is defined during the installation of your kdb Insights Enterprise deployment. For more information, refer to the Administration Passwords documentation.
  
  The example below adds a user and gives them the insights.role.maintainer role:
```
# Create a user
kxi user create user@domain.com --password <myPassword> --admin-password <adminPassword> --not-temporary
INSIGHTS_ROLES="insights.role.maintainer"
kxi user assign-roles user@domain.com --roles $INSIGHTS_ROLES --admin-password <adminPassword> 
```
3. Use the kxi pm push command to upload your package(s):
```
kxi pm push mypackage
```
  When configured correctly, kdb Insights Enterprise displays a confirmation that the push command succeeded.
  
  Code-only package
  
  If you have defined your UDA as part of a code-only package you must push both the database package and the code-only package to kdb Insights Enterprise.
4. Use the kxi pm deploy command to deploy your database package:
```
kxi pm deploy mypackage
```
  Only deploy database package
  
  You only need to deploy the database package. The environment variables added to the database package ensure any UDAs in the code-only package are loaded.
5. If you are using the global Aggregator included in the kdb Insights Enterprise base installation, you must also load the aggregation function into the global Aggregator(s).
  
  All packages created through the web interface use the global Aggregator.
  
  The following steps requires cluster access to edit the stateful set. Add the KXI_PACKAGES environment variable to the list of environment variables in spec.template.spec.containers.env for the global Aggregator components:
  1. Update the main query path Aggregator:
```
kubectl edit sts insights-aggregator
```
    Add KXI_PACKAGES to the list of environment variables in spec.template.spec.containers.env:
```
- name: KXI_PACKAGES
value: mypackage
```
  2. If Query Environments are enabled, update the QE Aggregator, used for exploratory queries:
```
kubectl edit sts insights-qe-aggregator
```
    Add KXI_PACKAGES to the list of environment variables in spec.template.spec.containers.env:
```
- name: KXI_PACKAGES
value: mypackage
```
Test the UDA

To test the UDA, you can call the UDA in the following ways:
- Query window
- Views
- REST

Handling Unsuccessful Deployments

Identify Errors

If the deployment fails, review error messages and logs to identify the cause. Common issues include missing dependencies, incorrect configurations, or permission errors.

Roll Back Changes

If necessary, roll back the deployment to the last known stable state to avoid disruptions in production.

Troubleshoot and Redeploy

Identify and troubleshoot issues, correct any errors, and attempt the deployment again.