Package Manager

Package Manager API client.

Use PackageManagerClient to manage packages, artifacts, and deployments on a kdb Insights Enterprise instance. Always interact with the client through its attributes (client.packages, client.artifacts, client.deployments, etc.) rather than using lower-level classes directly.

Example

Connect and run a full package lifecycle:

from pathlib import Path
from kxi.package_manager import PackageManagerClient

client = PackageManagerClient(host="https://<host>")

# Upload a compiled package binary
client.artifacts.push(Path("my_package.kxi"))

# Validate and register the package definition
client.packages.validate(my_package_model)
client.packages.create(my_package_model)

# Deploy the package
client.deployments.create(pkg_name="my_package", version="1.0.0")

# Bounce (restart) all components in the deployment
client.deployments.bounce(pkg_name="my_package")

# Tear down the deployment and remove persisted data
client.deployments.delete("my_package", cleanup=True)

Classes:

PackageManagerClient – REST client for the Package Manager v2 API.
V2Base – Base class for all Package Manager v2 API sub-clients.
V2Components – Generic CRUD operations for a Package Manager v2 API component.
V2Packages – Package CRUD and validation operations for the v2 API.
V2Artifacts – Binary artifact push/pull operations for the v2 API.
V2Migration – Assembly-to-package migration/conversion operations for the v2 API.
V2Deployments – Deployment lifecycle operations for the v2 API.

`PackageManagerClient`¶

PackageManagerClient(host=None, session=None, **kwargs)

Bases: PackageManagerRestClientBase

REST client for the Package Manager v2 API.

Always use this class (and its attributes) rather than the lower-level sub-client classes directly. Each attribute exposes a focused set of operations for one resource type.

Attributes:

packages (V2Packages) – Package CRUD and validation.
artifacts (V2Artifacts) – Binary artifact push/pull.
databases (V2Components) – Database component CRUD.
pipelines (V2Components) – Pipeline component CRUD.
views (V2Components) – View component CRUD.
udfs (V2Components) – UDF component CRUD.
workloads (V2Components) – Workload component CRUD.
deployments (V2Deployments) – Deployment lifecycle — create, bounce, delete, patch.
migrations (V2Migration) – Convert legacy assembly YAMLs to package binaries.

Example

Full package lifecycle — push, validate, deploy, bounce, tear down:

from pathlib import Path
from kxi.package_manager import PackageManagerClient

client = PackageManagerClient(host="https://<host>")

# Upload a compiled package binary
client.artifacts.push(Path("my_package.kxi"))

# Validate the package definition model before persisting
client.packages.validate(my_package_model)

# Create the package record, then deploy it
client.packages.create(my_package_model)
client.deployments.create("my_package", version="1.0.0")

# Restart all running components in the deployment
client.deployments.bounce("my_package")

# Tear down and remove persisted data
client.deployments.delete("my_package", cleanup=True)

Example

Query packages, pipelines, and databases:

# List all packages
pkgs = client.packages.list()

# Get a specific package by name
pkg = client.packages.get("my_package")

# List pipelines belonging to a package
pipelines = client.pipelines.list("my_package")

# Get a specific pipeline inside a package
pipeline = client.pipelines.get("my_package", "my_pipeline")

# Delete a pipeline from a package
client.pipelines.delete("my_package", "my_pipeline")

Example

Granular deployment operations:

# Deploy only specific components
client.deployments.create(
    "my_package",
    version="1.0.0",
    entities=[{"type": "pipeline", "name": "ingest_pipeline"}],
)

# Bounce a single pipeline without affecting other components
client.deployments.bounce(
    "my_package",
    entities=[{"type": "pipeline", "name": "ingest_pipeline"}],
)

# Hot-load a new package version into a running deployment
client.deployments.patch_deployment_runtime(
    package="my_package",
    deployment="deploy-uuid",
    targets=["ingest_pipeline", "query_pipeline"],
    version="1.1.0",
)

Example

Artifact management and legacy migration:

from pathlib import Path

# Download a package artifact
binary = client.artifacts.pull("my_package")

# Convert a legacy kxi-controller assembly YAML to a package binary
result = client.migrations.convert(Path("assembly.yaml"), install=True)

See Connection Parameters for shared constructor arguments.

`V2Base`¶

V2Base(client, *, base='packages', component=None)

Base class for all Package Manager v2 API sub-clients.

Subclasses are exposed as attributes of PackageManagerClient (e.g. client.packages, client.deployments) and share URL-building logic via url.

Attributes:

client (PackageManagerClient) – Parent client used for HTTP calls.
base (str) – Resource base path segment (e.g. "packages", "artifacts").
component (str | None) – Component sub-path segment (e.g. "databases").

Note

Do not instantiate sub-clients directly. Access them through PackageManagerClient attributes:

from kxi.package_manager import PackageManagerClient

client = PackageManagerClient(host="https://<host>")

# Use sub-clients via client attributes
client.packages.list()
client.artifacts.push(path)
client.deployments.create("my_package", version="1.0.0")

Functions:

url – Build a v2 API URL from path segments.

`url`¶

url(base_id=None, component=None, item_id=None)

Build a v2 API URL from path segments.

Segments are appended only when provided, following the pattern /v2/{base}/{base_id}/{component}/{item_id}.

Parameters:

base_id (str | UUID | None) – Parent resource identifier (e.g. package name or UUID).
component (str | None) – Sub-resource type to append after base_id.
item_id (str | UUID | None) – Specific item identifier within the component.

Returns:

str – Fully constructed URL path string.

`V2Components`¶

Bases: V2Base

Generic CRUD operations for a Package Manager v2 API component.

Operates on the URL pattern /v2/{base}/{base_id}/{component}/{item_id} where component is fixed at construction time (e.g. "databases", "pipelines").

This class backs client.pipelines, client.databases, client.views, client.udfs, and client.workloads. Use those attributes — do not instantiate this class directly.

Example

Pipeline CRUD via client.pipelines:

# List all pipelines across all packages
all_pipelines = client.pipelines.list()

# List pipelines belonging to a specific package
pkg_pipelines = client.pipelines.list("my_package")

# Create a pipeline inside a package
client.pipelines.create(pipeline_model, "my_package", version="1.0.0")

# Retrieve a specific pipeline
pipeline = client.pipelines.get("my_package", "ingest_pipeline")

# Delete a pipeline from a package
client.pipelines.delete("my_package", "ingest_pipeline")

Example

The same pattern applies to client.databases, client.views, client.udfs, and client.workloads:

# List all databases
client.databases.list()

# Get a specific UDF inside a package
client.udfs.get("my_package", "my_udf")

# Delete a workload
client.workloads.delete("my_package", "my_workload")

Functions:

create – Create a component resource.
delete – Delete a component resource.
get – Retrieve a single component resource.
list – List component resources.

`create`¶

create(item, *, base_id=None, version=None, relationships=None, **params)

Create a component resource.

Parameters:

item (BaseModel) – Pydantic model to serialise and POST.
base_id (str | None) – Parent resource identifier (e.g. package name or ID).
version (str | None) – Resource version string.
relationships (Sequence[RelationType] | None) – JSON:API relationship types to include in the response.
*params* – Extra query parameters forwarded to the request.

Returns:

Value – API response wrapped in a Value model.

`delete`¶

delete(base_id, version=None, *, relationships=None, item_id=None, **params)

Delete a component resource.

Parameters:

base_id (str) – Parent resource identifier (e.g. package name or ID).
version (str | None) – Resource version string.
relationships (Sequence[RelationType] | None) – JSON:API relationship types to include in the response.
item_id (str | UUID | None) – Child item identifier within the component.
*params* – Extra query parameters forwarded to the request.

Returns:

Value – API response wrapped in a Value model.

`get`¶

get(base_id, version=None, *, relationships=None, item_id=None, **params)

Retrieve a single component resource.

Parameters:

base_id (str | UUID) – Parent resource identifier (e.g. package name or ID).
version (str | None) – Resource version string.
relationships (Sequence[RelationType] | None) – JSON:API relationship types to include in the response.
item_id (str | UUID | None) – Child item identifier within the component.
*params* – Extra query parameters forwarded to the request.

Returns:

Value – API response wrapped in a Value model.

`list`¶

list(base_id=None, version=None, *, relationships=None, **params)

List component resources.

Parameters:

base_id (str | None) – Parent resource identifier. When omitted, lists all resources of this component type.
version (str | None) – Filter by resource version.
relationships (Sequence[RelationType] | None) – JSON:API relationship types to include in the response.
*params* – Extra query parameters forwarded to the request.

Returns:

Value – API response wrapped in a Value model.

`V2Packages`¶

Bases: V2Components

Package CRUD and validation operations for the v2 API.

Accessed via client.packages. Do not instantiate directly.

Example

# Validate a package definition without persisting it
client.packages.validate(my_package_model)

# Create (register) a package
client.packages.create(my_package_model)

# List all packages
pkgs = client.packages.list()

# Get a specific package by name
pkg = client.packages.get("my_package")

# Delete a package
client.packages.delete("my_package")

Functions:

validate – Validate a package without persisting it.

`validate`¶

validate(item, *, relationships=None, **params)

Validate a package without persisting it.

Parameters:

item (BaseModel) – Pydantic model representing the package to validate.
relationships (Sequence[RelationType] | None) – JSON:API relationship types to include in the response.
*params* – Extra query parameters forwarded to the request.

Returns:

Value – Validation result wrapped in a Value model.

`V2Artifacts`¶

Bases: V2Base

Binary artifact push/pull operations for the v2 API.

Accessed via client.artifacts. Do not instantiate directly.

Example

from pathlib import Path

# Upload a compiled package binary; force=True overwrites an existing artifact
client.artifacts.push(Path("my_package.kxi"), force=True)

# Download an artifact by package name or UUID
binary: bytes = client.artifacts.pull("my_package")

# Save the downloaded artifact to disk
Path("my_package.kxi").write_bytes(binary)

Functions:

pull – Download a binary artifact.
push – Upload a binary artifact file.

`pull`¶

pull(pkg_id, **_)

Download a binary artifact.

Parameters:

pkg_id (str | UUID) – Package identifier (name or UUID) of the artifact to download.

Returns:

bytes – Raw artifact bytes.

`push`¶

push(path, *, force=False, **_)

Upload a binary artifact file.

Parameters:

path (Path) – Local filesystem path to the artifact file.
force (bool) – Overwrite an existing artifact with the same name.

Returns:

Value – Upload result wrapped in a Value model.

`V2Migration`¶

Bases: V2Base

Assembly-to-package migration/conversion operations for the v2 API.

Accessed via client.migrations. Do not instantiate directly.

Example

from pathlib import Path

# Convert a legacy kxi-controller assembly YAML and install it immediately
result = client.migrations.convert(Path("assembly.yaml"), install=True)

# Convert and return individual spec files instead of a combined binary
result = client.migrations.convert(Path("assembly.yaml"), spec_files=True)

Functions:

convert – Convert a kxi-controller assembly YAML into a package binary.

`convert`¶

convert(assembly_file, install=False, spec_files=False)

Convert a kxi-controller assembly YAML into a package binary.

Parameters:

assembly_file (Path) – Path to the assembly YAML file.
install (bool) – Install the converted package immediately after conversion.
spec_files (bool) – Return individual spec files instead of a combined binary.

Returns:

Value – Conversion result wrapped in a Value model.

`V2Deployments`¶

V2Deployments(client)

Bases: V2Components

Deployment lifecycle operations for the v2 API.

Accessed via client.deployments. Do not instantiate directly.

Example

Create, bounce, and tear down a deployment:

# Deploy a package (all components)
client.deployments.create(pkg_name="my_package", version="1.0.0")

# Deploy only specific components
client.deployments.create(
    pkg_name="my_package",
    version="1.0.0",
    entities=[{"type": "pipeline", "name": "ingest_pipeline"}],
)

# Restart all components in a deployment
client.deployments.bounce(pkg_name="my_package")

# Restart a single component
client.deployments.bounce(
    pkg_name="my_package",
    entities=[{"type": "pipeline", "name": "ingest_pipeline"}],
)

# Delete a deployment and remove persisted data
client.deployments.delete("my_package", cleanup=True)

# Delete only a specific pipeline component within a deployment
client.deployments.delete(
    "my_package", component="pipelines", component_id="ingest_pipeline"
)

# Remove persisted data without tearing down the deployment
client.deployments.cleanup("my_package")

Example

Hot-load a package into a running deployment:

# Load a new package version into specific targets without restarting
client.deployments.patch_deployment_runtime(
    package="my_package",
    deployment="deploy-uuid",
    targets=["ingest_pipeline", "query_pipeline"],
    version="1.1.0",
)

# Load a package into global processes
client.deployments.patch_global_proc_runtime(
    package="my_package",
    global_processes=["proc-1", "proc-2"],
    version="1.1.0",
)

Functions:

bounce – Restart running components in a deployment.
cleanup – Remove persisted data for a deployment.
create – Create a deployment from a package or explicit component entities.
create_from_package – Create a deployment from a single package reference.
delete – Delete a deployment or one of its sub-components.
patch_deployment_runtime – Hot-load a package into a running deployment.
patch_global_proc_runtime – Hot-load a package into global processes.

`bounce`¶

bounce(pkg_id=None, pkg_name=None, *, entities=(), **_)

Restart running components in a deployment.

Parameters:

pkg_id (UUID | str | None) – Package UUID or name identifying the deployment.
pkg_name (str | None) – Human-readable package name identifying the deployment.
entities (Iterable[BounceEntity]) – Components to bounce. When empty, bounces all components. Each entry must follow the BounceEntity shape.

Returns:

Value – Bounce result wrapped in a Value model.

`cleanup`¶

cleanup(id, *, wait=False, relationships=None, **_)

Remove persisted data for a deployment.

Parameters:

id (str) – Deployment identifier.
wait (bool) – Block until the cleanup is complete.
relationships (Sequence[RelationType] | None) – JSON:API relationship types to include in the response.

Returns:

Value – Cleanup result wrapped in a Value model.

`create`¶

create(pkg_id=None, pkg_name=None, *, entities=(), version=None, relationships=None, **_)

Create a deployment from a package or explicit component entities.

When entities is empty, delegates to create_from_package using pkg_id and pkg_name.

Parameters:

pkg_id (UUID | str | None) – Package UUID or name (used when entities is empty).
pkg_name (str | None) – Human-readable package name (used when entities is empty).
entities (Iterable[DeployEntity]) – Explicit component entities to deploy. Each entry must follow the DeployEntity shape.
version (str | None) – Package version to deploy.
relationships (Sequence[RelationType] | None) – JSON:API relationship types to include in the response.

Returns:

Value – Created deployment wrapped in a Value model.

`create_from_package`¶

create_from_package(pkg_id=None, pkg_name=None, *, version=None, env=None, relationships=None, **_)

Create a deployment from a single package reference.

Parameters:

pkg_id (UUID | str | None) – Package UUID or name to deploy.
pkg_name (str | None) – Human-readable package name.
version (str | None) – Package version to deploy.
env (dict | None) – Environment variables to inject, keyed by component name.
relationships (Sequence[RelationType] | None) – JSON:API relationship types to include in the response.

Returns:

Value – Created deployment wrapped in a Value model.

`delete`¶

delete(id, component=None, component_id=None, *, wait=False, cleanup=False, relationships=None, **_)

Delete a deployment or one of its sub-components.

Parameters:

id (str) – Deployment identifier.
component (Literal['pipelines', 'databases'] | None) – Limit deletion to a specific component type ("pipelines" or "databases"). Deletes the whole deployment when None.
component_id (str | UUID | None) – Identifier of the specific component instance to delete.
wait (bool) – Block until the deletion is complete.
cleanup (bool) – Remove persisted data alongside the deployment.
relationships (Sequence[RelationType] | None) – JSON:API relationship types to include in the response.

Returns:

Value – Deletion result wrapped in a Value model.

`patch_deployment_runtime`¶

patch_deployment_runtime(package, deployment, targets, *, version=None, **params)

Hot-load a package into a running deployment.

Parameters:

package (str | UUID) – Package name or UUID to load.
deployment (str | UUID) – Target deployment UUID or identifier.
targets (list) – List of target names (e.g. pipeline or database names) to load the package into.
version (str | None) – Package version to load.
*params* – Extra query parameters forwarded to the request.

Returns:

Value – Patch result wrapped in a Value model.

`patch_global_proc_runtime`¶

patch_global_proc_runtime(package, global_processes, *, version=None, **params)

Hot-load a package into global processes.

Parameters:

package (str | UUID) – Package name or UUID to load.
global_processes (list) – List of global process identifiers to load the package into.
version (str | None) – Package version to load.
*params* – Extra query parameters forwarded to the request.

Returns:

Value – Patch result wrapped in a Value model.

Package Manager

PackageManagerClient¶

V2Base¶

url¶

V2Components¶

create¶

delete¶

get¶

list¶

V2Packages¶

validate¶

V2Artifacts¶

pull¶

push¶

V2Migration¶

convert¶

V2Deployments¶

bounce¶

cleanup¶

create¶

create_from_package¶

delete¶

patch_deployment_runtime¶

patch_global_proc_runtime¶

`PackageManagerClient`¶

`V2Base`¶

`url`¶

`V2Components`¶

`create`¶

`delete`¶

`get`¶

`list`¶

`V2Packages`¶

`validate`¶

`V2Artifacts`¶

`pull`¶

`push`¶

`V2Migration`¶

`convert`¶

`V2Deployments`¶

`bounce`¶

`cleanup`¶

`create`¶

`create_from_package`¶

`delete`¶

`patch_deployment_runtime`¶

`patch_global_proc_runtime`¶