Skip to main content
Apache Ossie conversion is currently in preview. Reach out to the Cube support team to activate it for your account.
Apache Ossie (Open Semantic Interchange) 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.
Conversion runs in Cube through the Platform API. 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, an import saves them to your development branch.

What converts

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 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 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.
  • 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) 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 are not included.

Import

Import saves files to your branch, so it is available only in 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 and commit.

Convert with the CLI

The Cube CLI runs a conversion through these endpoints, waits for it, prints its counts and issues, and writes the files:
--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 with SchemaRead or SchemaUpdate access to the deployment. The endpoints are under /api/v1/deployments/{deploymentId}/ossie-conversions. To export a data model with 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 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.