> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cube.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Apache Ossie

> Convert Cube data models to and from Apache Ossie, the Open Semantic Interchange format.

> [!WARNING]
>
> Apache Ossie conversion is currently in preview. Reach out to the
> [Cube support team](https://docs.cube.dev/admin/account-billing/support.md) to activate it for your account.

[Apache Ossie (Open Semantic Interchange)](https://github.com/apache/ossie) is an open format
for exchanging semantic models between tools. Cube converts models in both directions with the
Apache Ossie Cube converter:

* **Export** converts a Cube data model to one Ossie model: the YAML data model of a deployment's
  latest successful build, or YAML files you upload, such as a local checkout.
* **Import** converts an Ossie model to Cube data model files.

[Converting Apache Ossie Models to Cube](https://www.youtube-nocookie.com/embed/rPracSftWnY)

Conversion runs in Cube through the [Platform API](https://docs.cube.dev/api-reference/introduction.md). Through the API
and the CLI, it does not change your deployment: an import returns files for you to add to your
data model. In the [IDE](#import), an import saves them to your development branch.

## What converts

| Cube | Apache Ossie |
| - | - |
| Cube | Dataset |
| Dimension | Field |
| Measure | Metric |
| Join | Relationship |
| View, in an export with `view` | The model's name, description and AI context |

An export with `view` converts only the public members of that view, under the names the view
gives them. A whole-model export keeps its views in the Ossie model's Cube extensions.

Cube features with no Ossie equivalent, such as segments, pre-aggregations, hierarchies, access
policies and view curation, are kept in the Ossie model's Cube extensions, so importing the model
back into Cube restores them. Other tools ignore them. On import, Ossie features with no Cube
equivalent are kept under `meta.ossie` where Cube has room for them and reported as warnings where
it does not.

## Issues

Every conversion returns a list of issues:

* `ERROR`: the conversion failed and returned no files, for example a cube that uses `extends`.
* `WARNING`: something was dropped or changed, for example a skipped Jinja-templated file or a
  measure whose value can change when a join fans out. `CUBE_CONTEXT_IN_SQL` marks SQL that calls
  `FILTER_PARAMS`, `FILTER_GROUP`, `SECURITY_CONTEXT`, `SQL_UTILS` or `COMPILE_CONTEXT`: only Cube
  can fill these in, so other tools can't run that expression.
* `INFO`: something was kept in another form, for example a `geo` dimension split into latitude
  and longitude fields.

A measure such as `sum` or `avg`, read through a join that fans out, converts with a warning, since
an Ossie expression cannot carry Cube's fan-out correction. Set `strictFanout` to `true` in the
conversion request to fail instead. It defaults to `true` for a view export and `false` otherwise.

## Jinja templates

An export of the deployment's data model renders its [Jinja-templated](https://docs.cube.dev/docs/data-modeling/dynamic/jinja.md)
YAML files (`.yml`, `.yaml`, `.yml.jinja`, or `.yaml.jinja`) in the deployment, as Cube compiles
them, and converts the result. A file that only defines macros is left out. Rendering requires
all of these:

* You have **Access SQL Runner** (`SqlRunnerRead`)
  [access](https://docs.cube.dev/admin/users-and-permissions/custom-roles.md) to the deployment.
* The deployment runs Cube v1.3.11 or later.
* The request does not come from an embedded analytics session.

Otherwise, the export skips templated files with a warning. Uploaded files, including the CLI's
`--from-dir`, are never rendered.

Templates render with the deployment's default context, so Jinja that branches on the security
context or `COMPILE_CONTEXT` exports only one variant.

If a file fails to render, the export fails and names the file. A rendered file can be up to 2 MiB,
the rendered data model up to 20 MiB, and rendering can take up to 2 minutes.

For a few minutes after a build succeeds, the deployment's Cube runtime can still serve the
previous build while it rolls out the new one. Until the rollout finishes, an export that renders
templates fails with `409` and names both builds, so that it never mixes files from the two. Try
again once the rollout finishes.

## Limits

* JavaScript models are skipped. Jinja-templated files convert as described in
  [Jinja templates](#jinja-templates).
* An upload holds at most 512 `.yml` or `.yaml` files: each file up to 2 MiB, and 20 MiB in total.
  An Ossie model is at most 2 MiB.
* Each conversion has 60 seconds to run. Conversions and their results are kept for at most
  one day.
* Each user can run two conversions at a time and start six a minute. Over either limit, the API
  answers `429` with a `Retry-After` header.

## Convert in the IDE

Open the deployment's **Data model** screen (the [IDE](https://docs.cube.dev/docs/data-modeling/data-model-ide.md)) and
choose **Integrations** → **Apache Ossie**.

### Export

Choose **Export**. Pick a view to export only its public members, or leave it empty to export the
whole data model, then click **Export**. The dialog shows the counts and issues, and on success lets
you download `ossie.yaml`.

The export uses the latest successful build, so changes in
[development mode](https://docs.cube.dev/docs/data-modeling/data-model-ide.md#development-mode) are not included.

### Import

Import saves files to your branch, so it is available only in
[development mode](https://docs.cube.dev/docs/data-modeling/data-model-ide.md#development-mode).

Choose **Import**, upload an Ossie model as a YAML file, and click **Convert**. The dialog shows the
counts and issues, then lists each file the import will save:

* **New**: no file exists at this path.
* **Replaces existing**: the import overwrites a file at this path.
* **Unsaved changes**: the file has unsaved edits in the editor. **Add to data model** stays
  disabled until you save or discard them and import the file again.

Click **Add to data model** to save the files to your development branch, inside the deployment's
data model folder. They appear as uncommitted changes for you to
[review](https://docs.cube.dev/docs/data-modeling/data-model-ide.md#reviewing-changes) and commit.

## Convert with the CLI

The [Cube CLI](https://docs.cube.dev/reference/cli.md#apache-ossie) runs a conversion through these endpoints, waits for
it, prints its counts and issues, and writes the files:

```bash theme={"dark"}
cube ossie export DEPLOYMENT_ID --wait --out ossie.yaml
cube ossie export DEPLOYMENT_ID --from-dir . --wait --out ossie.yaml
cube ossie import DEPLOYMENT_ID --file ossie.yaml --out .
```

`--from-dir` exports your local project instead of the deployed model, `--view` exports one view,
and `--strict-fanout` sets `strictFanout`. `import --check` compares the files with what is on
disk instead of writing them, and exits non-zero on any difference, for use in CI.

## Convert with the Platform API

Use a [Platform API key](https://docs.cube.dev/api-reference/authentication.md) with `SchemaRead` or `SchemaUpdate`
[access](https://docs.cube.dev/admin/users-and-permissions/custom-roles.md) to the deployment. The endpoints are under
`/api/v1/deployments/{deploymentId}/ossie-conversions`. To export a data model with
[Jinja templates](#jinja-templates), the key also needs `SqlRunnerRead`; without it, the export
succeeds but skips the templated files with a warning.

Start a conversion with `POST`. For an export of the deployment's data model, send
`{"direction": "export"}`, and add `"view": "<name>"` to export one view. To export your own files,
send `"source": "files"` and `files`, a map of relative paths to YAML. For an import, send
`{"direction": "import", "ossieYaml": "<document>"}`. On import, `dialect` picks which warehouse SQL
to take from the Ossie model, and defaults to the dialect of the deployment's default data source.

The response is `202` with a `conversionId`, a `statusUrl` and a `resultUrl`. An export that
renders [Jinja templates](#jinja-templates) answers `409` instead while the deployment rolls out a
new build; retry it until the rollout finishes. Poll `GET` on the
`statusUrl` until the status is no longer `QUEUED` or `RUNNING`:

* `COMPLETED`: the conversion produced a result. Its `outcome` is `success` or `failed`.
* `FAILED`: the conversion ended without a result; `error` says why.
* `CANCELLED`: the conversion was cancelled with `DELETE` on the `statusUrl`.

`GET` on the `resultUrl` returns the counts and issues, and `GET …/{conversionId}/files` returns
the files: `ossie.yaml` for an export, or the Cube data model files for an import. Both answer
`409` until the conversion's result is available, which can be a moment after the status first
reads `COMPLETED`, so retry a `409` briefly.

This example exports the deployment's data model and requires `curl` and `jq`. Set `CUBE_API_URL`
to your tenant host without a trailing slash, `DEPLOYMENT_ID` to the deployment, and
`CUBE_API_TOKEN` to the API key.

```bash theme={"dark"}
set -euo pipefail

api="$CUBE_API_URL/api/v1/deployments/$DEPLOYMENT_ID/ossie-conversions"
auth="Authorization: Bearer $CUBE_API_TOKEN"

for _ in {1..30}; do
  code=$(curl --silent --show-error -o conversion.json -w '%{http_code}' -X POST -H "$auth" \
    -H 'Content-Type: application/json' -d '{"direction": "export"}' "$api")
  [[ "$code" == 409 ]] || break
  sleep 10
done
[[ "$code" == 202 ]] || { cat conversion.json; exit 1; }
id=$(jq -er '.conversionId' conversion.json)

while :; do
  status=$(curl --fail --silent --show-error -H "$auth" "$api/$id" | jq -r '.status')
  [[ "$status" == QUEUED || "$status" == RUNNING ]] || break
  sleep 5
done

if [[ "$status" != COMPLETED ]]; then
  curl --fail --silent --show-error -H "$auth" "$api/$id" | jq '{status, error}'
  exit 1
fi

fetch() {
  for _ in {1..15}; do
    code=$(curl --silent --show-error -o "$1.json" -w '%{http_code}' -H "$auth" "$api/$id/$1")
    [[ "$code" == 409 ]] || break
    sleep 2
  done
  [[ "$code" == 200 ]] || { cat "$1.json"; exit 1; }
}

fetch result
jq '{outcome, counts, issues}' result.json
[[ $(jq -r '.outcome' result.json) == success ]] || exit 1

fetch files
content=$(jq -er '.items[0].content' files.json)
printf '%s\n' "$content" > ossie.yaml
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.