M↓ View as Markdown ↗

Import OSI Format¶

You can bring models, relationships and metrics described in an Open Semantic Interchange (OSI) YAML file into a Workspace in two ways:

Method	Best for
Direct import on Settings → Import / export	OSI files exported from AI Analyst, or OSI files that name an existing data connection for every dataset
Import with Steward	OSI files from other tools that don't name a data connection, or when you want Steward to fill in details OSI doesn't carry, such as types, grain and descriptions

Availability

Who can do this: members with the Edit capability in the active Workspace.
Deployment: Actian SaaS and self-managed deployments.

Direct import¶

Requirements¶

Every dataset must name an existing data connection. AI Analyst reads the connection name from a custom_extensions entry with vendor_name: AI_ANALYST. Files exported from AI Analyst already include it:
```
custom_extensions:
  - vendor_name: AI_ANALYST
    data: '{"data_source_name":"PostgreSQL DB"}'
```
The connection must exist in your organization with exactly that name and be available in the Workspace. If a dataset has no such entry, the import fails and the dataset's name is listed in the These data sources are missing message.
The file must have a semantic_model root. AI Analyst reads the first semantic_model entry.

Steps¶

Switch to the Workspace you want to import into.
Go to Settings → Import / export and click Import.
Under Upload, choose the .yaml file.
Choose Keep orphaned or Delete orphaned. For OSI files, Delete orphaned deletes only models and metrics that the file does not name.
Click Import.

The import applies immediately, in a single transaction. See Import Semantic Layer & Agents for matching, history and error messages.

How OSI content is imported¶

OSI	Becomes	Notes
Dataset	Model	Matched by name. New models are created as table-based models, with the table path taken from `source` (the connection-name prefix is removed).
Dataset `ai_context.instructions`	Model agent guidance
Field	Dimension or measure	A field whose `expression` is a valid aggregate, such as `SUM(amount)`, becomes a measure. Every other field becomes a dimension.
Relationship	Relationship	Created as a many-to-one relationship with a left join.
Metric	Metric	See below.

Metrics:

A new metric is created only when the file contains exactly one dataset, because OSI does not say which model a metric belongs to. Otherwise the metric is skipped with the warning Metric "…" was not imported because this OSI document does not name exactly one dataset.
For an existing metric, only its description is updated.

OSI imports never create, change or delete glossary terms or AI analysts.

Tip

OSI carries less detail than AI Analyst stores, such as types, grain, filters, units and metric anchors. Models based on a custom SQL query don't round-trip through OSI either. To move a semantic layer between Workspaces or organizations without losing detail, use the Lossless format.

Import with Steward¶

Use Steward when an OSI file from another tool doesn't name a data connection, or when you want help filling in the gaps.

In Studio, open the Steward panel on the right.
Click Attach files (paperclip) and add your OSI .yaml file. Each file can be up to 8 MB.
Ask Steward to import the semantic model, and tell it which data connection to use.
Steward drafts the edits and shows you a diff. Review it and approve it to apply the changes. By default Steward asks for your approval before it applies edits. If your administrator has set this tool to Always allow, Steward applies them without asking.

Approving Steward edits to the semantic layer also requires the Edit capability. See Using Steward.

Example prompt¶

"Please import this OSI file and create models in my semantic layer. Map the datasets to my PostgreSQL data source."