Command Line Interface

The Command Line Interface (CLI) for interacting with Packages is fully integrated with the kdb Insights CLI as outlined here. The package command within the kdb Insights CLI allows you to create, package and manage packages locally and within a kdb Insights Enterprise installation. Installation of the kdb Insights CLI can be achieved following the instructions outlined here.

The following is the list of available commands:

$ kxi package --help 
Usage: kxi package [OPTIONS] COMMAND [ARGS]...

  KX Package Import/Export CLI.

Options:
  --version                     Version information.
  --artifact-store DIRECTORY    Directory in which to store packed
                                artifacts;[default] $KX_ARTIFACT_PATH.
  --pkg-lib DIRECTORY           Directory in which packages will be
                                installed;[default] $KX_PACKAGE_PATH.
  --deployment-store DIRECTORY  Directory in which deployment data is
                                stored;[default] $KX_DEPLOYMENT_PATH.
  --debug                       Enable stacktrace print statements for easier
                                debugging.
  --help                        Show this message and exit.

Commands:

  When pulling/pushing to a kdb Insights package repository, use these commands:

    pull           Download an artifact from the running insights package
                   manager service to...
    push           Publish an artifact to the running insights package manager
                   service.
    remote-list    List all installed packages or artifacts on the running
                   insights package...
    remote-remove  Remove packages or artifacts from the running insights
                   package manager...

  For local development, use these commands:

    init       Creates a bare package at the specified target path.
    install    Install a package given a requirement or path.
    list       List all installed packages or artifacts.
    lock       Lock the q files within a source directory.
    packit     Create a package artifact given a source code directory.
    uninstall  Uninstall specified locally installed packages and artifacts.
    unpack     Unpack an artifact to a specified location.
    validate   Validate the contents of a source directory to ensure it is a
               valid package.

  For managing deployments & runtime of packages on kdb Insights, use these commands:

    deploy    Deploy a package to an insights instance
    teardown  Teardown a deployed packaged running on an insights instance

  For managing components added to package, use these commands:

    add      Add an entity to the specified package.
    copy     Copy an entity from the specified package.
    refresh  Refresh an entity of the specified package.
    rm       Remove an entity from the specified package.

Interactions with packages can be local or remote. Packages and their associated artifacts are stored in a location (either locally or on an kdb Insights Enterprise installation) specified by user-defined paths, KX_PACKAGE_PATH and KX_ARTIFACT_PATH respectively. This section does not cover interactions with an Insights installation. For details, follow the guide here.

Quickstart

This quickstart provides you with a step-by-step guide to:

Initialize a package locally.
Update this package to include user-defined code.
Package this entity to generate an artifact.
Install this package locally, allowing it to be loaded and used locally.

The quickstart assumes that you have:

Installed the kxicli package (version >= 1.0.0) following the instructions here.

Generate a simple package locally

Create and define custom artifact and package paths.

$ mkdir -p /tmp/test-packages
$ mkdir -p /tmp/test-artifacts
$ export KX_PACKAGE_PATH=/tmp/test-packages
$ export KX_ARTIFACT_PATH=/tmp/test-artifacts

Default values

The default values for these paths are as follows

$ echo $KX_PACKAGE_PATH
/tmp/packages
$ echo $KX_ARTIFACT_PATH
/tmp/artifacts

Initialize a package with minimal content. Run this command from a clean working directory, taking into account the following warning.

Warning

Both the KX_PACKAGE_PATH and KX_ARTIFACT_PATH locations are used as load and storage locations for installed local packages, the initialization of packages in either location can result in unexpected behavior and should be avoided.
```
$ kxi package init qpackage
Creating package at location: qpackage
Writing qpackage/manifest.json

$ tree qpackage
qpackage
├── init.q
└── manifest.json
```
Create a file src/sp.q within the qpackage folder created by the initialization of the package outlined above. This file contains a User-Defined Function (UDF) and variable. Documentation outlining the structure for this UDF is provided here.
```
$ cat src/sp.q
.test.variable:1b

// @udf.name("sp_map")
// @udf.tag("sp")
// @udf.category("map")
.test.sp.map:{[table;params]
   select from table where x<10
   }
```

You can now update the init.q file to load the src/sp.q file.

$ cat init.q
// Load the src/sp.q file relative to package root
.kxi.packages.file.load["src/sp.q"]

Package the artifact defining the version of the package on the command line. Run this command from the original directory where you initialized the package qpackage.

$ kxi package packit qpackage --version 1.0.0 --tag
Creating package from qpackage
Package created: /tmp/artifacts/qpackage-1.0.0.kxi
qpackage-1.0.0.kxi

Install the package locally such that it can be loaded into processes using Python/q locally.

$ kxi package install qpackage-1.0.0.kxi
{
    "qpackage": [
        {
            "version": "1.0.0",
            "_status": "InstallationStatus.SUCCESS"
        }
    ]
}

List the current artifacts available locally.

$ kxi package list --artifacts
{
    "qpackage": {
        "1.0.0": {}
    }
}

Once you have generated your package locally, you can follow the guide here to learn more about uploading and interacting with packages within kdb Insights Enterprise.