- 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 usesextends.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_SQLmarks SQL that callsFILTER_PARAMS,FILTER_GROUP,SECURITY_CONTEXT,SQL_UTILSorCOMPILE_CONTEXT: only Cube can fill these in, so other tools can’t run that expression.INFO: something was kept in another form, for example ageodimension split into latitude and longitude fields.
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.
--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
.ymlor.yamlfiles: 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
429with aRetry-Afterheader.
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 downloadossie.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.
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 withSchemaRead 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. Itsoutcomeissuccessorfailed.FAILED: the conversion ended without a result;errorsays why.CANCELLED: the conversion was cancelled withDELETEon thestatusUrl.
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.