M↓ View as Markdown ↗

Import Actian AI Analyst Format (YAML / JSON)¶

The native Lossless format (YAML or JSON) is the most complete import format. It covers models, relationships, metrics, glossary terms and AI analysts, matched to existing entities by name.

Use it to restore a backup, to copy a semantic layer from one Workspace or organization to another, or to apply changes you keep under version control.

For how to run an import, how matching works and what each message means, see Import Semantic Layer & Agents.

Availability

Who can do this: members with the Edit capability in the active Workspace.
Plan: imports that would exceed your plan's AI analyst limits are refused.
Deployment: Actian SaaS and self-managed deployments.

Copy a semantic layer to another Workspace¶

In the source Workspace, go to Settings → Import / export, click Export, choose Lossless and click Download.
Make sure every data connection the models use exists in the target organization, with the same names, and is available in the target Workspace.
Switch to the target Workspace.
Go to Settings → Import / export, click Import, choose the .zip file under Upload, and click Import.

Keep Keep orphaned selected unless you want the target Workspace to match the file exactly. Delete orphaned deletes every model, metric, glossary term and AI analyst that the file does not name.

Supported files¶

A Lossless .zip, as produced by the Lossless export. It must contain exactly four files, models, metrics, glossary and agents, either all with the .yaml extension or all with .json.
A previous-version export: a single .yaml / .yml file, or the previous version's four-file .zip. See Older exports.

Files can be up to 16 MB. In Settings, the upload accepts .zip, .yaml and .yml files, so JSON is supported inside a Lossless zip.

Rules for a Lossless zip¶

If you edit an export and zip it again, follow these rules, or the import fails with Import was not applied. and a detail such as missing agents.yaml:

Include all four files: models, metrics, glossary and agents.
Use one encoding for all four files. Mixing YAML and JSON files is not allowed.
Use the .yaml extension, not .yml, inside the zip.
Don't add any other file. Hidden files that some operating systems add when compressing a folder, such as a __MACOSX folder or .DS_Store, also cause the import to fail.
The four files can be at the root of the zip or inside one folder, but not deeper.

For example, from a folder that contains the four files:

zip -X ai-analyst-export.zip models.yaml metrics.yaml glossary.yaml agents.yaml

File structure¶

Lossless files use the structure described in Actian AI Analyst Lossless Format. In summary:

File	Top-level keys	Entities identified by
`models`	`models`, `relationships`	Model `name`; dimension, measure and filter `name` within the model; relationship `name`
`metrics`	`metrics`	Metric `name`. The anchor model is `model`, and joins name a relationship.
`glossary`	`glossary`	Glossary `term`
`agents`	`agents`	AI analyst `name`

Each file must start with the header the export writes: version: "1.0", exported_at (an ISO 8601 date and time) and environment with a name. A file without this header is not a valid Lossless file.

Entities have no id field. If a file contains IDs, they are ignored.

A minimal models file:

version: "1.0"
exported_at: "2026-01-28T00:00:00.000Z"
environment:
  name: Production
models:
  - name: Orders
    description: All customer orders
    agent_guidance: Use this model for order-related questions
    data_source: PostgreSQL DB          # must match an existing data connection name
    source_type: TABLE                  # TABLE or CUSTOM_QUERY
    source_path: [public, orders]
    source_query: null
    grain:
      description: One row per order
      column_names: [id]
    dimensions:
      - name: Order ID
        expression: id
        type: NUMBER
        primary_key: true
      - name: Status
        expression: status
        type: STRING
    measures:
      - name: Total Amount
        expression: SUM(amount)
        unit: USD
        precision: 2
    filters: []
relationships:
  - name: Orders to Customers
    from_model: Orders
    from_key: customer_id
    to_model: Customers
    to_key: id
    type: MANY_TO_ONE
    join_type: LEFT

Allowed values¶

Enum values are case-sensitive and must be uppercase.

Field	Allowed values
Model `source_type`	`TABLE`, `CUSTOM_QUERY`
Dimension `type`	`STRING`, `NUMBER`, `BOOLEAN`, `TIMESTAMP`, `DATE`, `ENUM`
Relationship `type`	`ONE_TO_ONE`, `ONE_TO_MANY`, `MANY_TO_ONE`
Relationship `join_type`	`INNER`, `LEFT`, `RIGHT`, `FULL`
Metric `time_grains`	`hour`, `day`, `week`, `month`, `quarter`, `year` (lowercase)
AI analyst `deployment_state`	`DRAFT`, `DEPLOYED`
AI analyst `audience`	`EVERYONE`, `RESTRICTED`
`model_access.mode`	`MANUAL`, `ONLY_TAGS`, `EXCLUDE_TAGS`
`glossary_access.mode`	`UNRESTRICTED`, `ONLY_GROUPS`, `EXCLUDE_GROUPS`
Glossary mapping `target`	`model`, `dimension`, `measure`, `filter`, `metric` (lowercase)

What happens with a value that isn't allowed:

An unknown source_type, deployment_state, audience or access mode makes the whole file invalid, and nothing is imported.
An unknown dimension type is ignored. A new dimension is created as STRING, and an existing dimension keeps its current type.
A relationship with an unknown type is skipped without a warning. For example, type: many_to_one in lowercase means the relationship is not imported.

What an import changes¶

Models: new models are created. For existing models, dimensions, measures and filters in the file are added or updated by name, and ones the file leaves out are kept. An existing model's data connection and source are not changed; a difference is reported as a warning.
Metrics: a metric whose anchor model doesn't exist is not imported. Joins that don't match a relationship are dropped with a warning. Available dimensions, measures and filters that don't match a field are dropped.
Glossary terms: mappings in the file are added to the term. Terms synced from a data catalog are never changed.
AI analysts: only the settings present in the file are changed. Suggestions and saved prompts in the file replace the analyst's existing ones. Model, field and tag names that don't match anything in the Workspace are skipped.

Older exports¶

Single-file YAML exports, and four-file zips, from the previous version of the app can still be imported. AI Analyst converts them to the Lossless format:

IDs are ignored, and entities are matched by name.
Metric tags and metric filters, AI analysts' metric access (semantic_layer_access.metrics) and per-model filter access are not imported. Each produces a warning in the import summary.
Metric joins that don't match a relationship are dropped with a warning.
group_by_dimensions, glossary term tags, a VIEW source type, and older AI analyst deployment and audience settings are ignored without a warning.
Enum values are not converted. In older files, a dimension type or relationship type that isn't uppercase is ignored without a warning: the dimension is imported as STRING, and the relationship is skipped.
Old glossary access modes are converted: ALL → UNRESTRICTED, INCLUDE_TAGS → ONLY_GROUPS, EXCLUDE_TAGS → EXCLUDE_GROUPS.

After importing an older file, review the Warnings in the import history and check the imported metrics and AI analysts.

Import with the Public API¶

Send the same .zip file as the raw body of PUT /api/public/v1/environment, using an API key bound to the target Workspace. See Import with the Public API.