M↓ View as Markdown ↗

Import Semantic Layer & Agents¶

You can import a file to create or update the semantic layer and AI analysts in a Workspace. Use imports to restore a backup, copy a semantic layer from another Workspace or organization, or apply changes you keep under version control.

An import always writes into one Workspace: the one currently selected in the Workspace switcher. To import into a different Workspace, switch to it first.

Availability

Who can do this: members with the Edit capability in the active Workspace. The Editor and Administrator presets grant Edit only in the organization's default Workspace; for other Workspaces, Edit must be granted in that Workspace.
Plan: imports that would exceed your plan's AI analyst limits are refused.
Deployment: Actian SaaS and self-managed deployments.

Import applies immediately

There is no preview step. When you click Import, the changes are applied straight away. Export the Workspace first so you have a backup to return to. See Export Semantic Layer & Agents.

What can be imported¶

Models: source, data connection, grain, dimensions, measures and filters.
Relationships: joins between models.
Metrics: expression, anchor model, time dimension and grains, unit and precision, joins, and available fields.
Glossary terms: definitions, synonyms and mappings. Terms synced from a data catalog are never overwritten or deleted.
AI analysts: instructions, model and glossary access, deployment state, audience, suggestions and saved prompts, subject to your plan's AI analyst limits.

Which of these a file can contain depends on its format.

Accepted files¶

Format	File	What it imports
Lossless	`.zip` containing four YAML or four JSON files, as exported	Models, relationships, metrics, glossary terms and AI analysts. See Import Actian AI Analyst Format (YAML / JSON).
Open Semantic Interchange	`.yaml`	Models, relationships and metrics. See Import OSI Format.
Previous-version export	A single `.yaml` / `.yml` file, or the previous version's four-file `.zip`	Files exported from the previous version of the app. Some fields are not imported. See Older exports.

AI Analyst detects the format from the file's contents. The upload accepts one .zip, .yaml or .yml file of up to 16 MB. Excel files are not supported.

Before you start¶

Data connections must already exist. Each model names its data connection, and the import matches it by name. The import never creates connections. Create any missing connection first, with exactly the same name, and make sure it is available in the Workspace you are importing into. See Workspaces.
Choose the right Workspace in the Workspace switcher.
Export a backup of the Workspace.

Import a file¶

Switch to the Workspace you want to import into.
Open Settings (from Studio or Explorer) and, under Environment, select Import / export.
Click Import.
Under Upload, choose one .zip or .yaml file.
Choose how to handle entities that are in the Workspace but not in the file:
- Keep orphaned (default): leave them as they are.
- Delete orphaned: delete them. See Orphaned entities.
Click Import.

The dialog closes and the import appears at the top of the history table on the Import / export page. Its Summary shows how many entities were created, updated, deleted and unchanged, followed by any Warnings.

How matching works¶

Entities are matched by name:

If an entity with the same name exists in the Workspace, it is updated.
Otherwise, it is created.

IDs in the file are ignored. If you rename an entity in the file, the import creates a new entity with the new name. The entity with the old name stays, unless you choose Delete orphaned, in which case it is deleted.

Updates merge into what is already there rather than replacing it:

A model's dimensions, measures and filters are matched by name. Fields that the file leaves out are kept.
Glossary mappings in the file are added. Existing mappings are not removed.
For an AI analyst, only the settings present in the file are changed. If the file includes suggestions or saved prompts, they replace the analyst's existing ones. Model, field and tag names that don't match anything in the Workspace are skipped.
An existing model's data connection and source (table or custom query) are not changed by an import. If the file names a different connection or source, the change is skipped and reported as a warning.

Order and transaction¶

The import applies changes in dependency order: models → relationships → metrics → glossary terms → AI analysts.

All changes are applied in a single transaction. If anything fails, nothing is applied and the Workspace stays as it was.

Orphaned entities¶

An orphaned entity is one that exists in the Workspace but is not named in the file.

File type	What Delete orphaned deletes
Lossless or previous-version export	Every model, metric, glossary term and AI analyst the file does not name. Glossary terms synced from a data catalog are never deleted.
Open Semantic Interchange	Only models and metrics the file does not name. Glossary terms and AI analysts are not touched.

Warning

With a Lossless or previous-version file, a missing or empty list deletes every entity of that type. For example, if the agents file contains no AI analysts, Delete orphaned deletes all AI analysts in the Workspace.

When an import fails¶

If an import fails, nothing is applied. The reason appears as an error message, and the dialog stays open so you can choose a corrected file. The failed attempt is listed with status Failed and no summary in the history after you reload the page.

Note

The product's messages call a Workspace's contents an Environment. In these docs that means the active Workspace.

Message	Cause	What to do
Import was not applied. These data sources are missing: …	The file names data connections that don't exist in your organization. For an OSI dataset that names no connection, the dataset name is listed instead.	Create the connections with exactly these names, or correct the names in the file.
Import was not applied. This data connection is not attached to the active Workspace	A new model uses a connection that exists but is not available in this Workspace.	Make the connection available in the Workspace, then try again.
Import was not applied. Creating AI analyst "…" would exceed this Environment's plan limit.	The file would create more AI analysts than your plan allows.	Remove AI analysts from the file, or delete unused ones from the Workspace.
Import was not applied. AI analyst "…" would exceed this Environment's models-per-analyst plan limit.	An AI analyst with manual model access lists more models than your plan allows per analyst. The analyst name in this message may show as a dash.	Reduce the number of models in that analyst's `model_access`.
Nothing was imported. This file isn't a recognized Environment export, or it contains no importable entities.	The file is not a Lossless, OSI or previous-version export, or it contains nothing to import.	Check that you uploaded the right file.
Import was not applied. followed by a detail, such as missing agents.yaml	The file was recognized but is not valid, for example a Lossless zip with a missing or extra file.	Fix the file as described in the detail. See Supported files.

Warnings¶

Some problems don't stop the import. The import completes, and each problem is listed under Warnings in the history:

Warning	Meaning
Metric "…" join "…" could not be resolved to a relationship and was dropped.	A metric join names a relationship that doesn't exist. The metric is imported without that join.
… on … "…" has no equivalent and was dropped.	A field in the file has no equivalent in AI Analyst, for example metric tags in a previous-version export, or a changed data connection or source on an existing model.
Metric "…" was not imported because this OSI document does not name exactly one dataset.	A new metric in an OSI file can't be anchored to a model. See Import OSI Format.

Import with the Public API¶

You can also import with the Public API, for example from a CI/CD pipeline.

An API key is bound to one Workspace, and the import always writes into that Workspace. Creating API keys requires the Manage organization capability.
Send PUT /api/public/v1/environment with the key as a Bearer token and the file's raw bytes as the request body (up to 16 MB).
Set the orphaned query parameter to keep (default) or delete.
A successful import returns the created, updated, deleted and unchanged counts and any warnings as JSON. A missing data connection returns HTTP 422 with the missing names. A plan limit returns HTTP 402.
The Public API is rate-limited. When you exceed the limit, it returns HTTP 429 with a Retry-After header.

curl -X PUT \
  -H "Authorization: Bearer <API_TOKEN>" \
  --data-binary @ai-analyst-export.zip \
  "https://<your-ai-analyst-host>/api/public/v1/environment?orphaned=keep"

API imports appear in the Workspace's import history, with the member who created the API key under Started by. Every import, from Settings or the Public API, is also recorded in the organization's audit log as environment.import.

For the full reference, click Public API docs on the Import / export page.