Command Line Interface
The Command Line Interface (CLI) for interacting with Packages is fully integrated with the kxi CLI
as outlined here. The package
command within the kxi CLI
allows a user to create, package and manage packages locally and within a KX Insights installation. Installation of the kxi 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 Info
--artifact-store DIRECTORY Directory in which to store package
artifact;[default] $KX_ARTIFACT_PATH
--pkg-lib DIRECTORY Directory in which packages will be
installed;[default] $KX_PACKAGE_PATH
--debug Enable stacktrace prints for easier debugging
--help Show this message and exit
Commands:
When pulling/pushing to a remote deployment, use these commands:
pull Download an artifact from a running service to your local dir
push Publish a package artifact to a running service
remote-list List all installed packages or artifacts on the remote system
remote-remove Remove packages/artifacts from remote service specified as
'name/ver' and...
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
packit Create a package artifact given source code directory
uninstall Locally remove packages/artifacts packages can be specified as
'name/ver'...
Interactions with packages are local or remote with the storage of packages and their associated artifacts with a user defined path at KX_PACKAGE_PATH
and KX_ARTIFACT_PATH
respectively both locally and on an Insights Installation.
Quickstart
This quickstart provides a step-by-step guide to:
- Initialise 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 a user has:
- Installed the kxicli package (version >= 1.0.0) following the instructions here
Generate a simple package locally
-
Create and define the artifact and package paths.
$ mkdir -p /tmp/packages $ mkdir -p /tmp/artifacts $ export KX_PACKAGE_PATH=/tmp/packages $ export KX_ARTIFACT_PATH=/tmp/artifacts
-
Initialize a package with minimal content.
$ kxi package init qpackage Creating package at location: qpackage Creating: manifest.json { "name": "qpackage", "version": "0.0.1", "entrypoints": { "default": "init.q" }, "metadata": { "description": "", "authors": { "username": { "email": null } } }, "dependencies": {} } Creating: init.q qpackage ├── init.q └── manifest.json
-
Create a file
src/sp.q
which 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 }
-
Update the
init.q
file to load thesrc/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 command line.
Note
If the package has multiple dependencies you may want to specify
--all-deps
to create an archive with all of the sub-dependencies included.$ cd .. $ kxi package packit qpackage --version 1.0.0 --tag Creating package from /Users/username/qpackage Package created: /tmp/artifacts/qpackage-1.0.0.kxi { "qpackage-1.0.0.kxi": "CREATED" }
-
Install the package locally such that it can be loaded into processes using Python/q locally.
$ kxi package install qpackage-1.0.0.kxi Installing /tmp/artifacts/qpackage-1.0.0.kxi Getting qcode=1.0.0 from [local] /tmp/artifacts/qpackage-1.0.0.kxi Unpacking qcode: /tmp/packages/qpackage/1.0.0 Successfully installed qpackage { "qpackage": [ { "version": "1.0.0", "_status": "InstallationStatus.SUCCESS" } ] }
-
List the current artifacts available locally.
$ kxi package list --artifacts Listing artifacts at: /tmp/artifacts { "qpackage": [ "1.0.0" ] }