Semantic Layers

Semantic Layers define the business-ready meaning of data by modeling entities, metrics, dimensions, and relationships in a governed structure. This is the semantic contract between technical pipelines and business consumption: instead of every team reinterpreting tables independently, the platform centralizes definitions so reporting and analytics stay consistent across use cases.

In Data Studio, semantic modeling follows a versioned workflow with draft and published states, aligned with the ODA guidance on governed pipeline operations. Authors can evolve models in draft versions, manage entities and table relationships, and publish explicit versions when ready. The UI and backend enforce strong governance: only administrator-level users can create, edit, or publish layers, and deletion is blocked when a layer is referenced by active projects. This protects downstream consumers while still allowing controlled model evolution.

Semantic Layer Editor

Once you enter a semantic layer, the editor opens in draft state (shown as v1.0.0-draft in the top-right version indicator). The editor has a left panel for managing and searching the tables added to the layer, and a main canvas where each table appears as a card. You can add as many tables as needed to a single layer by clicking the + button in the left panel and picking from the OIDM tables picker. The left panel also includes a Search tables field to quickly locate any table already in the layer. When the layer definition is ready, clicking Publish (top right) transitions the version from draft to a published release (e.g. Version: v1.0.0) with a green Published badge visible in the top bar.

The Ask Optra button is available in both the Semantic Layers index and inside the layer editor itself, so you can ask questions about your semantic model or get guidance on table definitions at any point during the authoring process.

Create a Semantic Layer

To create a semantic layer, follow the steps below.

1. Open Data Studio > Semantic Layers.
2. Click Create (admin only).
3. The form starts with an auto-generated untitled name + timestamp.
4. Enter/update Layer name and Description.
5. Click Save.
6. You are taken to the semantic layer editor page.

Manage Versions and Publish

To manage a semantic layer after creation, follow the below-mentioned steps:

1. Open Data Studio > Semantic Layers and click the name of the layer you just created to enter the editor.
2. The editor opens in draft state — the version indicator in the top-right shows v1.0.0-draft and the Publish button is visible.
3. Add tables to the layer:
   • In the left panel, click the + button next to Search tables.
   • A Search OIDM tables picker appears listing all available business entities (e.g. Case, CaseLifecycle, Customer, Device, DeviceEvent, Sales, ServiceRequest, and more).
   • Click any table name to add it to the canvas. You can add multiple tables to a single layer.
   • Each added table appears as a card on the canvas, displaying its primary key columns, data types, and a Show N more columns link for full column details.
   • A pencil icon on each table card lets you edit the table definition inline.
4. Search tables in the layer: Use the Search tables field in the left panel to quickly locate a table already added to the layer. The left panel lists all tables belonging to the current layer.
5. Adjust the canvas view: Use the +, -, and expand icons at the bottom-left of the canvas to zoom in, zoom out, or fit the table layout to screen.
6. Repeat steps 3–4 until all required tables are added. A single layer can contain multiple tables.
7. When your table definitions are complete, click Publish (top right).
8. Confirm the publish action. The version transitions from draft to a published release (e.g. Version: v1.0.0) and displays a green Published badge in the top bar.
9. To continue evolving the layer, add a new draft version and repeat the process — previous published versions remain accessible and stable.

Delete Behavior

To delete a semantic layer, follow the steps below.

1. Click trash icon on index row.
2. If the layer is not referenced by projects, delete confirmation appears.
3. If used by projects, an error modal lists projects using it and delete is blocked.

What the System Does Behind the Scenes

1. Lists semantic layers by account and optional search term.
2. Computes latest published version per layer.
3. Seeds a new layer with an initial draft VersionLayer.
4. Copies entities/columns/FK relationships when creating new draft versions.
5. Restricts create/edit/publish/delete to administrator role.