Ossiectl CLI

ossiectl is an optional model-authoring helper. It runs on a workstation, reads metadata, writes a YAML file, and exits. You can also write the same file by hand. It never runs inside the cluster and it is never in the query path.

ossiectl uses the local credentials of the person running it.

Ossiectl generates physical structure. A person still certifies business metrics and policy.

Authoring is a one-way flow into a file. No component in the cluster ever calls back out to Glue, DataHub, or Polaris.

What it does

Generate a model

derive reads your catalog and writes a complete, schema valid model. Datasets and fields arrive populated. Date and timestamp columns have dimension.is_time set. Other fields remain non-dimensional until an author adds dimension: {} after semantic review. Candidate joins are inferred from key naming conventions and left commented out for a human to confirm. Metrics, primary keys, governance, and views are left as clearly marked placeholders.

Two sources of physical structure ship. Use the engine source when an engine is available. It sees the schema and permissions that queries will use. The Glue source is an offline bootstrap option for authoring before an engine is available.

# Preferred connected workflow. Reads the live engine's information_schema.
# Works for any catalog the engine
# mounts, including Polaris, Hive Metastore, Unity, and Glue.
export SQL_DIALECT=trino ENGINE_HOST=127.0.0.1 ENGINE_PORT=8080
ossiectl derive -source engine -catalog polaris -database sales -out model.yaml

# Offline bootstrap workflow. Reads AWS Glue over the AWS SDK.
# No query engine or cluster is required.
ossiectl derive -source glue -region us-west-2 -database sales -out model.yaml

Both produce the same Ossie dataset and field shape for equivalent source metadata. Engine introspection remains preferable because it reflects what the deployed engine can resolve.

Import business meaning

-enrich adds the meaning a data steward already curated somewhere else, so you write less by hand.

export DATAHUB_TOKEN=<personal access token>
ossiectl derive -source engine -catalog polaris -database sales \
  -enrich datahub -datahub-url http://localhost:8080 \
  -datahub-platform trino -datahub-dataset-prefix polaris \
  -out model.yaml

Enrichment maps catalog metadata onto model fields:

• descriptions become field documentation,
• glossary terms become dataset and field synonyms that help an agent select dimensions and understand the model,
• PII and sensitivity tags become denyFields entries, so a request for a classified column fails to compile,
• deprecated datasets are flagged for review rather than dropped silently.

ossiectl does not import metrics, because a person must review and certify each formula.

Physical structure always comes from -source, never from the metadata platform. A metadata platform serves an ingested copy of the schema that can lag reality, and a model built on stale structure fails its first drift check.

Validate offline

ossiectl validate -f model.yaml

Structural checks plus a compile dry run, with no cluster involved. Wire it into CI for early feedback.

Convert between formats

unwrap extracts the supported Apache Ossie document from a Kubernetes resource. wrap does the reverse. The round trip preserves the typed model semantics, but YAML formatting, comments, quoting, and field ordering are not preserved because both commands parse and marshal the document.

Access it needs

Target	Access	Why
AWS Glue	Read metadata	Lists tables and columns for -source glue. Uses your local AWS credential chain.
Query engine	Read metadata	-source engine reads information_schema.
DataHub	Read metadata	-enrich datahub imports descriptions, terms, and tags.
Kubernetes	Apply, as you	Only for kubectl apply of the finished model. validate needs no cluster.

It never needs table data, never writes to a catalog or engine, and has no in cluster identity of its own.

Next

Authoring a model walks through the full loop, from generated scaffold to certified metrics and governance.