ODA User Guide
Data Studio
Organize workspaces, build data pipelines, manage semantic layers, and run and monitor jobs in Data Studio.
Data Studio is Optra's hub for building and running data pipelines. It brings together workspaces, projects, semantic layers, and jobs to turn source data into governed, business-ready outputs.
For first steps, see Orientation: Getting Started in the ODA User Guide. See UI Overview for navigation, page behavior, and shared Ask Optra access.
At a Glance
Primary Areas
Workspaces
Organize projects and team-owned domains.
Semantic Layers
Govern business meaning with versioned definitions.
Jobs
Schedule, run, and monitor operational execution.
Role Model
manage_data: create/editWorkspaces,Projects, andJobs.administrator: create/edit/publishSemantic Layers.- Reader roles: view/search with write actions hidden.
Navigation Routes
/data-accelerator/data-accelerator/workspaces/:id/data-accelerator/projects/:id/data-accelerator/semantic-layers/data-accelerator/jobs
Workspaces
Workspaces are the primary organizational container in Data Studio. They group related projects so teams can manage data initiatives by domain, product line, or business unit while keeping context and ownership clear. The UI supports both rapid discovery and day-to-day navigation through recents, search, sort, and personal starring, so frequently used workspaces and projects are easy to return to.
Operationally, Workspaces are not just folders; they are account-bound entities that anchor project lifecycle actions. When a workspace is opened, Data Studio resolves its related projects, recent activity, and user-specific stars, then updates this view dynamically as users search, sort, create, or edit descriptions. This gives teams a stable collaboration surface for organizing ingestion, transformations, and downstream delivery work.
How to Create a Workspace
To create a workspace, follow the below-mentioned steps:
- Open
Data Studio > Workspacesfrom the left sidebar. - Click
Createin the top-right corner of the Workspaces page. - In the
Create new workspacemodal, enter a workspaceName(required). - Optionally enter a
Descriptionto help other users understand the workspace purpose. - Click
Saveto create the workspace.
After creating or when browsing existing workspaces, use the Search workspaces... field on the right side of the page to quickly find the desired workspace by name.
Inside a Workspace: Projects, Search, Create, and Import
Once a workspace is created, open it to view all projects that belong to that workspace. The workspace page shows recent projects and a project library list, so you can quickly continue existing work.
Use the Search projects... field on the right side of the workspace page to find your desired project by name.
To create a project inside a workspace, follow the below-mentioned steps:
- Open the target workspace from
Data Studio > Workspaces. - Click
Createin the top-right corner of the workspace page. - In the
Create new projectmodal, enter a projectName(required). - Optionally enter a project
Description. - Click
Saveto create the project.
To import a project inside a workspace, follow the below-mentioned steps:
- Open the target workspace from
Data Studio > Workspaces. - Click
Importin the top-right corner of the workspace page. - In the
Import Projectmodal, drag and drop your YAML export file, or clickChoose Fileto browse locally. - Select a supported file type (
.yamlor.yml). - Confirm the import to add the project into the workspace.
Setting up a System
A System is a saved source connection that you add to a project as the starting point for a data pipeline. The project's central Add system item opens a picker of existing connections. Create new connections at account level under Settings > Secrets, then return to the picker and select the connection to add it to the project. The picker lists enabled supported data connections for the selected account; it does not create credentials itself. Databricks credentials are used by Labs and are configured separately from the project System list.
Select an Existing System
- Open the project. If the canvas is empty, click the central Add system item. This is a clickable item on the canvas (not a button in the page header) and opens the Select a system side panel.
- If the canvas already contains nodes, open System in the project side navigation to show the system selector.
- In Select a system, optionally enter part of the connection name in Search systems.
- Click the desired existing System in the list. The picker adds it as a node to the project canvas; selecting an entry is the action that adds it to the project.
- Continue to Inspect a System in the Project to review its connection details and use it in the pipeline graph.
Only enabled data connections of supported types for the selected account appear in the picker. A user without permission to edit the project can view the list but cannot add a System. If the connection is missing, ask an administrator to enable an existing connection or follow the next procedure to create one.
Adding a PostgreSQL Source
A PostgreSQL source is a project Source node that reads data from a saved Postgres secret using a specific database, schema, and SQL query. Unlike simple file-based systems, clicking a Postgres connection in the picker does not place a node on the canvas right away—Optra first opens a configuration panel so you can define what to query.
- Open the project's Select a system panel: click the central Add system item on an empty canvas, or System in the project side navigation if the canvas already has nodes.
- Optionally type part of the connection name into Search systems to find your Postgres connection.
- Click the existing system to add it. Because its secret type is Postgres, Optra opens the Add Postgres Source panel instead of adding a node directly—this is where you define the database, schema, and query for this source. If no Postgres connection exists yet, click Add a system and follow Create a Connected System, choosing Postgres as the secret type and supplying its
hostname,database,username, andpasswordvalues on the secret's detail page. - In the Add Postgres Source panel, complete the form:
- Postgres Secret — shows the connection selected in the picker. This panel only offers that one secret, so there is nothing else to choose here.
- Database — the name of the Postgres database to query. It is pre-filled from the secret's saved
databasevalue when available, otherwise from the secret's name; you can override it. Required. - Schema — the name of the Postgres schema to use. A schema is the named group of tables inside a Postgres database (for example
public). Defaults topublic. Required. - Query — a SQL statement, entered in the code editor, that Optra runs against the database and schema above to pull data for this source. Required.
- Click Test to verify connectivity and the query before saving—see Testing a PostgreSQL Source's Connectivity below.
- Click Save. Save stays disabled until Database, Schema, and Query are all filled in. Saving creates a new Source node named
pg-<database>on the canvas, connected to the Postgres system node, and shows a confirmation message ("Postgres source added successfully."). The panel also keeps a running count of sources added in the current session, so you can add more than one query-based source from the same Postgres connection without reopening the picker.
Viewing Data Available in a PostgreSQL Source
After a Postgres source is added, select its Source node (not the System node it is attached to) on the canvas to open its details panel and review what is configured:
- Database section — a read-only Database field showing the database name saved for this source.
- Schema section — a read-only Schema field showing the schema name saved for this source (shown only when a schema was saved).
- Query — a read-only field showing the saved SQL query.
- Viewing table names available — Optra's Postgres source does not browse a live catalog of database tables; the data "available" from this source is whatever the saved Query returns. Click Refresh Schema to run that query and display:
- A Schema results table listing each returned column's Field Name and Type—effectively the structure of the table(s) your query exposes.
- A Sample data preview below it with a handful of actual rows, using those same column names as headers, so you can confirm the query returns the expected data before continuing the pipeline.
- If the query fails, an error message appears in place of the schema table; if it succeeds but returns no columns, Optra shows "No schema available".
Testing a PostgreSQL Source's Connectivity
Verify that Optra can reach the Postgres database and run the configured query at two points in the pipeline: while first adding the source, and again on its downstream Ingestion node.
While adding the source:
- In the Add Postgres Source panel, fill in Database, Schema, and Query.
- Click Test. Optra validates the Postgres secret, then runs the entered SQL query against the database and schema.
- On success, a message such as "Connection successful! Query returned N rows." appears.
- On failure, an error message with the reason appears (for example, a missing secret, an empty database name, an empty query, or the database driver's error).
- If the test fails, update the Query (or Database/Schema) and click Test again.
- Once the test succeeds, click Save to add the Source node. Updating the query and re-testing does not save anything by itself; you must click Save afterward to persist the change.
On the Ingestion node, after the source is added:
- Select the project's Ingestion node for this source, and configure its Projection (the columns to include from the source's schema).
- Click Test in the footer. This button stays disabled until at least one column is selected in Projection.
- Optra switches to a connectivity test view and runs a lightweight check (
SELECT 1) against the same database using the saved secret and credentials.- Success shows "Successfully connected to datasource." (or a more specific message).
- Failure shows "Connection failed." together with the underlying reason.
- Click Back to return to the Ingestion panel from the test result view.
Deleting an extra connection:
- Open account Settings > Secrets. Each row lists one saved connection (a secret), including its Name, Type, Status (Enabled/Disabled), Expiration, and Validated state.
- Click the trash icon in the row of the extra or duplicate Postgres connection you no longer need. This action requires an account role permitted to manage secrets; without it, the trash icon is not shown.
- In the Confirm Deletion of Secret dialog, review the warning that this action cannot be undone, then confirm to delete it.
- Deleting a secret does not check whether a project is still using it as a System or Postgres Source. If a project node still references the deleted connection, its Secret field shows "No secret found," and clicking Test on that Source or its Ingestion node fails (for example, "Failed to load secret."). Remove or re-point the affected System/Source nodes in any project that used the deleted connection.
Modifying an existing connection:
- Open account Settings > Secrets and click the row of the Postgres connection to edit (this navigates to the secret's detail page). This also requires permission to manage secrets; read-only users can view but not edit the fields.
- Under General Information, update the Name or the Enabled toggle if needed.
- Under Values, update any of the saved attributes—hostname, database, username, or password. Click the eye icon beside a field to reveal its current value before changing it.
- Click Save. Saved attribute changes apply immediately to every project System/Source built on this connection; Optra also invalidates any cached connection token so the next test uses the new values right away.
- Return to the project and re-verify connectivity with the updated credentials—open the Postgres Source's Add Postgres Source/inspect panel or its Ingestion node and click Test again, following the same steps as Testing a PostgreSQL Source's Connectivity above. Editing the secret's values does not automatically re-test or re-save any source that already uses it.
Create a Connected System
- Open the project's Select a system panel by clicking the central Add system item on an empty canvas, or System in the project side navigation if the canvas already has nodes.
- In the panel, click Add a system. It appears in the empty state when there are no connections, or at the bottom of the panel when connections are listed. Account Settings > Secrets opens in a new browser tab.
- In Settings > Secrets, choose Create secret.
- Enter a recognizable name and select the connection type for your source (for example, Azure Data Lake, Azure Event Hub, AWS S3, Postgres, Snowflake, TDS, or Delta Sharing, depending on what is enabled in your deployment), then create the secret.
- On the new secret's detail page, enter the connection-specific values requested by the form—such as the endpoint and required account/database details and credentials—then save. The exact fields depend on the selected source type.
- Return to the project tab. In the Select a system panel, search for the new connection if needed, then click it. Creating a secret does not add it to the project automatically; selecting it in the picker adds the System node to the canvas.
Do not add secrets to a project description or expose credential values in prompts or documentation. If a reader cannot see or use Add a system, ask an administrator to create or enable the connection and grant the required project access.
Inspect a System in the Project
- In the project, select the system node you added. Its System panel shows the system name, connection type, and saved attributes.
- Select the external-link icon beside General Information to open that secret's configuration in account settings. Treat displayed values as sensitive.
- Use the project canvas to connect the system node to the next pipeline step. A system is only the source connection; it does not by itself define or run the rest of the pipeline.
- To remove the node, use its delete control only when the graph allows deletion. Nodes with dependent downstream steps may need those connections removed first.
Ask Optra about Systems
Open Ask Optra from the Data Studio page and ask: "tell me about adding a system to a project for a pipeline". For broader orientation, you can also ask: "tell me about systems in Optra". Chat availability depends on the selected account. Use the project System picker and Settings > Secrets for the actual connection setup; Ask Optra does not create or reveal credentials.
Setting up a Full Ingestion from PostgreSQL
Ingestion is the pipeline step that pulls a defined set of columns from a Source node into the project on each run. A Full ingestion reloads the entire result of the source's query every run and replaces the previous data, unlike the Incremental/Incremental Insert/Incremental CDC types, which use a watermark column to pull only new or changed rows. This procedure continues from an already-added PostgreSQL Source.
Refresh Schema
Before configuring ingestion, make sure the Source node's schema reflects the columns your query actually returns:
- Select the Postgres Source node on the canvas to open its panel.
- Click Refresh Schema. Optra re-runs the source's saved SQL query and loads the resulting Field Name/Type list and a Sample data preview. This button is only enabled once the source has both a Database and a Query saved, which a Postgres source always has after it is created.
- Review the refreshed schema and sample rows to confirm the query still returns the columns you expect.
Saving Source
- After clicking Refresh Schema (or changing any field on the Source node), click Save in the panel footer. Save stays disabled until either you have unsaved field changes or a schema refresh has completed, so a refresh alone is enough to enable it even with no other edits.
- Saving persists the node and its refreshed schema so the Ingestion node below can offer the correct columns to choose from.
Selecting columns
- On the canvas, click the quick-add (
+) control on the Postgres Source node to add its Ingestion node. If an Ingestion node already exists for this source, the same control opens it instead of creating a new one. - A new Ingestion node is created with its Ingestion type already defaulted to Full. Confirm that Full is selected in the Ingestion type dropdown. Choosing any Incremental option instead reveals a Watermark column picker, which Full ingestion does not use.
- In the Projection box, choose which of the Source's schema columns to ingest:
- Click Select All to check every available column.
- Click Clear to uncheck all columns and start over. You can click Select All and Clear any number of times while adjusting the selection, and individual column checkboxes can still be toggled one at a time.
- At least one column must remain selected; the panel shows "At least one field must be selected" and disables Save when Projection is empty.
- Review the Schema table below Projection—it lists the Field Name and Type of only the columns currently selected, so you can confirm your projection before saving.
- Click Save in the panel footer. Saving the Ingestion node also cascades the column selection to any downstream pipeline steps already built on it, adding or removing their columns to match.
- Click Test in the footer to verify Optra can still connect with this projection. This button stays disabled until Projection has at least one column selected. Optra switches to a connectivity test view and runs a lightweight check (
SELECT 1) against the source's database using its saved secret.- Success shows "Successfully connected to datasource." (or a more specific message).
- Failure shows "Connection failed." together with the underlying reason.
- Click Back to return from the test result view to the main Ingestion panel, where Projection and Ingestion type remain as you left them.
- Click Test again at any point to re-verify connectivity—for example after changing the Projection or after the source's credentials have been modified—following the same steps above.
Observing Data via Zone Explorer
Zone Explorer is a project-scoped page for browsing the tables produced by a pipeline's medallion zones (Raw, Bronze, Silver, Gold) and running ad hoc SQL against them, separate from the Data Studio canvas used to build the pipeline.
Open Zone Explorer
- Open the project in Data Studio.
- Click Zone explorer in the project page header (next to Data studio). Optra navigates to the project's Zone Explorer page, which lists Data Layers (Raw, Bronze, Silver, Gold) on the left and a SQL Editor with results on the right.
- If the project's latest pipeline run did not succeed, a banner warns that you may need to run the pipeline to see the latest data, and that a failing query may mean the pipeline needs to run first.
Browse the Raw Zone
- In the Data Layers list, click Raw to expand it. Optra loads and lists the tables available in the Raw zone (showing "Loading tables..." while it fetches them, or "No tables found" if there are none yet).
- A table tagged Importing or Stopping is still being populated by an in-progress or stopping pipeline run; it is visible from zone metadata but may not be fully queryable until that run completes.
- Click a table's name to expand it and list its columns with their types; click again to collapse it.
- To copy a table name, hover the table row and click the copy icon that appears. Optra copies the fully qualified reference—
<Layer>.<table name>(for exampleRaw.my_table)—to the clipboard and shows a "Table name copied" confirmation, so you can paste it directly into aFROMclause in the SQL Editor.
Run Query
- In the SQL Editor, write or paste a SQL query that references a zone table as
"<Layer>"."<table name>"(for exampleSELECT * FROM Raw.my_table)—pasting a copied table name already matches this format. - Click Run. Optra infers which zone to query from the layer named in your
FROMclause, flushes the editor content, and executes the query; the button shows a spinner and "Running..." while it works. - Review the results below the editor. If the query fails and the pipeline-status banner was showing, re-run the project's pipeline and try again.
- If the query targets the Gold layer and returns rows, a Publish as Service button becomes available for publishing that query as a governed service endpoint—this is a separate workflow from running the query itself.
For example, after creating a Transformation node named "Transformation" whose output lands in the Bronze zone, select * from Bronze.Transformation is a valid query: Bronze is the layer and Transformation is that zone node's name, copied exactly as shown by the table's copy-table-name control.
Renaming Zone Layer Tables
A zone node's name is also the table name you query for it in Zone Explorer (Optra sanitizes it—replacing anything that isn't a letter, digit, or underscore with _—to build the actual queryable table/entity name). Renaming the node therefore renames the table.
- Select the Zone node on the canvas to open its panel.
- Hover over the node name at the top of the panel until a pencil icon appears, then click it to start editing.
- Type the new name and either click Save or press Enter to confirm, or press Escape/click Cancel to discard the change.
- The rename takes effect immediately on the node; because the table name derives from this property, any existing SQL in Zone Explorer or a published service that referenced the old name (for example
Bronze.Transformation) must be updated to the new name, and you should run the pipeline again so the zone's data is available under the new table name.
Error Investigation
When a query against a zone table fails in Zone Explorer, use Ask Optra to understand why, then confirm the fix by re-running the query—going back to Data Studio to run the pipeline first if the data simply isn't there yet.
Ask Optra About Query Errors
- In Zone Explorer, click Ask Optra in the page header to open the chat panel if it is not already open.
- Type your question—for example, "Why does my query to select from the raw zone fail?"—into the message box at the bottom of the panel, then press Enter to send it (Shift+Enter inserts a new line instead of sending).
- While Optra is responding, the panel shows a "Searching" indicator. Optra sends your question, recent chat history, and the project's available layer/table schema to the AI assistant and replies with an explanation in the chat thread.
- Two common root causes for a failing Raw-zone query, independent of SQL syntax, are: the project has no successful pipeline run yet ("Zone Explorer needs at least one successful pipeline run for this project"), or a run just finished and its snapshot is still being prepared ("Zone Explorer is still preparing a snapshot of the latest pipeline run. Large projects can take several minutes; please try again shortly."). Ask Optra's reply may point to one of these, or to a problem in the query itself (for example the wrong layer/table name or missing quoting).
- If Optra's reply includes a corrected SQL query, a Use SQL in editor button appears beneath that message.
Retry the Query
- Copy the corrected query from Optra's reply—either click Use SQL in editor to load it automatically, or select the SQL text in the chat message and paste it into the SQL Editor yourself, replacing what was there.
- Click Run to execute the corrected query.
- If the query still fails—for example because the project genuinely has no successful pipeline run yet—re-running the same query from the SQL Editor does not fix a missing pipeline run; you need to produce that data first, as described next.
Run the Pipeline and Retry Zone Explorer
- Click Data studio in the Zone Explorer page header to return to the project canvas.
- Run the project's pipeline so the Raw zone has data to query—open Jobs, find or create a job for this project, and use Run Now for an immediate execution (see Run and Monitor Jobs). Wait for the run to complete successfully.
- Click Zone explorer again in the project page header to return to the SQL Editor; your previous SQL and chat history are not preserved across this navigation, since Zone Explorer reloads fresh for the project.
- Paste the same corrected query back into the SQL Editor and click Run again. With a successful pipeline run now in place, the query against the Raw zone table succeeds.
Publish as Service
Building on Run Query, Publish as Service turns a successful Gold-zone query into a governed MCP service through a 3-step wizard (see What does "Publish as Service" mean? for the concept).
- In Zone Explorer, run a query against the Gold layer that returns at least one row. The Publish as Service button only appears next to Run once those conditions are met, and only for a user with the
manage_datarole. Click Publish as Service to open the wizard. - Step 1 of 3 — Metadata: enter a Slug (lowercase letters, digits, and hyphens only, no leading/trailing hyphen—this becomes the MCP tool name), a Display Name, and an optional Description. Click Next: Parameters.
- Step 2 of 3 — Parameters: click + Add parameter for each named parameter your SQL uses (for example
start_date), setting its Name, Type (string,integer,number,boolean,date, ordatetime), optional Description, and whether it is Required. Click Remove to delete a parameter row, or leave this step empty if your query has no parameters. Click Next: Review, or Back to return to Metadata. - Step 3 of 3 — Review: Optra re-validates the SQL (normalizing any literal
account_id = '...'or other literal equality conditions to?placeholders first) and shows a pass/fail check-list. Fix any reported issues—or click Back to adjust parameters/metadata—then submit. - Submitting creates a draft service version and immediately submits it for review; Optra closes the wizard once this succeeds. This is a governed workflow, not an instant public release—review/approval is separate from authoring the query.
Labs
Labs is a side panel inside an open Data Studio project, not a separate page or route. Open a project, then select Labs (the flask icon) in the project side navigation. The panel currently provides two capabilities: Catalog Registration for registering zone data in Databricks Unity Catalog, and Zone to Device Registry for configuring fields that a pipeline can mirror to the Device Registry.
Labs needs a Databricks secret matching the selected account. If none exists, it displays a No Databricks Secret message and the Labs configuration cards—including Zone to Device Registry—are not shown. Add the connection under Settings > Secrets, then reopen Labs.
Catalog Registration: Register Zone Tables in Databricks
Catalog Registration registers zone data as Databricks Unity Catalog external Parquet tables; it does not copy the data into a new Databricks-managed table.
- Ensure the project has zone data available. If a zone has not produced data yet, run the pipeline before registering it. Your deployment may also require a preconfigured Unity Catalog External Location for its storage (for example, ADLS).
- Open Labs in the project side navigation. If the panel says No Databricks Secret, add a Databricks connection under Settings > Secrets and return to Labs. The project System selector does not list Databricks connections for this workflow.
- In Catalog Registration, select the appropriate Databricks Secret, then click Save to associate it with the project.
- Locate the zone and node to register under Raw, Bronze, Silver, or Gold. A zone only appears here when it has eligible nodes.
- Turn on the toggle for the individual node. The panel shows a registering indicator while work is in progress, then displays the resulting table name and registration time, or an error to investigate.
- Repeat for other nodes as needed. Review each node's latest status in Labs; a failed registration is shown with its error message.
To stop active registration, turn off the node's toggle. This deactivates the registration but does not drop the Databricks table. Labs presents SQL for removing the table/schema manually in the Databricks SQL warehouse. Review the generated SQL carefully before running it; dropping a schema with CASCADE can remove other objects in that schema.
Zone to Device Registry
This configuration tells a subsequent pipeline run which zone rows and fields to mirror into the Device Registry. Saving the configuration alone does not perform the mirror.
- In the Zone to Device Registry card, choose a Zone node. Choose a zone with available schema/data for the fields you want to map.
- Set the device identifier. If Labs recognizes a column named like
deviceIdormachineId, it displays that column as the detected Device ID. Otherwise, choose the appropriate Device ID Column from the list. - If timestamp columns are available and relevant, select the Telemetry Timestamp Field. This is optional; the field choices come from the selected node's schema.
- Choose which additional Fields to include. The device ID field is always included and cannot be unchecked. Use select all or clear to adjust the other fields, then make any individual selections needed.
- Click Save. To change the mapping later, select a different zone/field configuration and save again. Clearing the Zone selection clears the saved mapping.
- Run the project pipeline that writes the selected zone. The configured rows are mirrored during that pipeline run; check the run outcome if the expected Device Registry records do not appear.
If the selected zone has no supported timestamp column, the panel indicates that no timestamp field was found; leave timestamp unset if it is optional for your use case. Saving changes requires an account role that can edit Data Studio projects.
Ask Optra about Labs
Open Ask Optra from the Data Studio page and ask: "tell me about labs". Chat availability depends on the selected account. Use the Labs panel for the actual Databricks registration and Device Registry configuration actions.
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. Authors can evolve models in draft versions, manage entities and table relationships, and publish explicit versions when ready. 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.
How to Create and Publish Semantic Layers
To create and publish semantic layers, follow the steps below.
- Open
Data Studio > Semantic Layers. - Click
Create(admin only). - The form starts with an auto-generated untitled name + timestamp.
- Enter/update
Layer nameandDescription. - Click
Save. - You are taken to the semantic layer editor page.
Semantic Layer Editor
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. Use the procedure below to add tables, inspect and edit their definitions, adjust the canvas, and publish a version.
For questions about your semantic model or guidance on table definitions during authoring, use Ask Optra.
Manage Versions and Publish
To manage a semantic layer after creation, follow the below-mentioned steps:
- Open
Data Studio > Semantic Layersand click the name of the layer you just created to enter the editor. - The editor opens in draft state — the version indicator in the top-right shows
v1.0.0-draftand thePublishbutton is visible. - Add tables to the layer:
- In the left panel, click the
+button next toSearch tables. - A
Search OIDM tablespicker 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 columnslink for full column details. - A pencil icon on each table card lets you edit the table definition inline.
- In the left panel, click the
- Search tables in the layer: Use the
Search tablesfield 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. - 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. - Repeat steps 3–4 until all required tables are added. A single layer can contain multiple tables.
- When your table definitions are complete, click
Publish(top right) and optionally set the version bump. - Confirm the publish action. The version transitions from draft to a published release (e.g.
Version: v1.0.0, followingvX.Y.Z) and displays a greenPublishedbadge in the top bar. - To continue evolving the layer, open the
Versionmenu, add a new draft version, and repeat the process — previous published versions remain accessible and stable.
Delete Behavior
To understand deletion behavior and constraints, follow the steps below.
- Click trash icon on index row.
- If the layer is not referenced by projects, delete confirmation appears.
- If used by projects, an error modal lists projects using it and delete is blocked.
Jobs
Jobs are the execution and orchestration layer of Data Studio. They package pipeline intent into runnable units that can be triggered manually or on schedule, with optional notifications and tags for logical grouping. This mirrors ODA's operational model where tagging, scheduling, and monitoring are central to managing end-to-end data pipelines.
From a system perspective, the Jobs experience is split into configured jobs and execution history (runs). The All Jobs view focuses on job definitions, ownership, trigger mode, and latest run health, while the Runs view provides run-by-run observability with status, timestamps, duration, and searchable history. Data Studio continuously reconciles job metadata with latest pipeline activity so operators can quickly detect failures, review logs, and take corrective actions without leaving the platform.
For pipeline questions, run diagnostics, or guidance while working in the execution view, use Ask Optra.
How to Configure and Run Jobs
To configure and operate jobs, follow the steps below.
- Open
Data Studio > Jobs. - Stay on
All Jobstab. - Click
Create. - Fill in required fields:
Name,Project, andTags. - Optionally enable:
Schedule,Notifications, andRun job on creation. - Click
Create.
Run and Monitor Jobs
To run and monitor jobs, follow the steps below.
- Click any row to open job details modal.
Overviewtab shows project, tags, schedule, created time.- Click
Run Nowfor immediate execution. Runstab shows run history/status.Settingstab lets editable users pause/resume/remove schedule and manage notifications.
Use Runs Tab (Global)
To use the global Runs tab, follow the steps below.
- Switch to
Runstab. - Search by run attributes.
- Adjust date range.
- Click a run row to open run log modal.
Running the Pipeline
Running the pipeline executes every connected node in the project—Systems, Sources, Ingestions, Transformations, and Zones—in dependency order, and is required before Zone Explorer or any downstream Zone has data to show.
Select Job
- Open the project. In the project side navigation, click Job to open the Job side panel. It opens on the Runs tab by default, showing a Run pipeline button and a Recent Pipeline Runs table; the All Jobs tab instead lists any scheduled/named jobs for this project, each with its own Run now button.
- Run pipeline (and each job's Run now) is disabled with a "Pipeline is not complete" tooltip when the project has a Transformation node that is not yet connected to a downstream step. Connect or remove that node before running.
Start a Pipeline Run
- With the Runs tab open, click Run pipeline. Optra starts a new pipeline run in the background and immediately shows the button as Running... with a spinner while a run is in progress.
- The new run appears at the top of Recent Pipeline Runs with a status badge (for example "running"), a started timestamp, duration, and a Trigger column (manual run vs. the job that triggered it). While a run is in progress, a Stop now control lets you cancel it.
Review a Pipeline Run
- Click anywhere on a row in Recent Pipeline Runs to open the Pipeline run Log modal for that run.
- The modal header repeats the run's Status, Started at time, and either Finished at time or "In progress".
- Below that, each pipeline node that participated in the run is listed with its kind and name, the zone it belongs to (if any), its STARTED timestamp, and—once finished—its status and FINISHED timestamp with duration. A node that is still running shows "RUNNING ... In progress" instead. A failed node is highlighted in red and shows its error message; nodes that produced analytics (for example row counts) list those details as well.
Review the Complete Run Log
- The run's node-by-node log is contained in a scrollable area. Review the full log to see every node in the run, especially on runs with many pipeline steps.
- Close the modal (its close control) once you've reviewed the log.
Run the Pipeline Again
- Back on the Runs tab, click Run pipeline again to start another run—for example after fixing a failed node shown in the log, or after changing a Source/Ingestion/Transformation configuration. Each click only works while no run is currently in progress (the button is disabled and reads "Running..." during an active run).
- The table of Recent Pipeline Runs grows with each run, so you can compare the latest attempt against previous ones.
Event Hub Source
Running the pipeline behaves differently when a Source reads from an Azure Event Hub connection instead of a database or file source, because Event Hub ingestion is continuous rather than a single query per run.
- To add one, click an Azure Event Hub System in the Select a system panel; Optra opens the Add Event Hub Source panel with just the Event Hub Secret (already selected) and an info note: "Each run collects up to 10 minutes of Event Hub data." Click Save to add it—there is no Database/Schema/Query or Test button here, since Event Hub streams messages rather than being queried.
- On the Event Hub Source's Ingestion node, a Max ingestion duration (Event Hub) slider lets you choose a duration from 1 to 60 minutes. It replaces the Ingestion type/Watermark column/Projection controls used by database sources and sets how long each pipeline run collects messages.
- Incoming messages are safely recorded during ingestion, helping prevent data loss or duplication if processing is interrupted.
- Unlike a Full ingestion (which reloads and replaces all data every run), an Event Hub source's Raw-zone data accumulates run over run—Zone Explorer effectively unions every run's captured messages together rather than showing only the latest run's snapshot.
Purpose
This guide explains how users interact with the ODA Data Studio area in Optra, with special focus on:
WorkspacesSemantic LayersJobs
This guide reflects the current Data Studio experience.
Who Can Do What
- Users with
manage_datacan create/editWorkspaces,Projects, andJobs. - Users with
administratorrole can create/edit/publishSemantic Layers. - Reader users can still view pages, search, and inspect records, but create/edit actions are hidden.
How To Reach Data Studio
- Sign in and select your account from the left panel.
- In the left navigation under
Data Studio, open one of these pages:Workspaces,Semantic Layers, orJobs.
Routes used by the app:
/data-accelerator/data-accelerator/semantic-layers/data-accelerator/jobs
Practical User Flow (End-to-End)
- Create a
Workspace. - Open workspace and create/import a
Project. - Create
Semantic Layer(admin), model entities, publish a version. - In project transformations, map to semantic layer where needed.
- Create
Jobwith relevant tags and optional schedule. - Track run results in
Jobs > Runsand job modal run history.
Common Questions
Why do I not see the Create button?
- You likely have reader-level access.
Workspaces/Jobscreate actions needmanage_data.Semantic Layerscreate/publish needsadministrator.
Why is semantic layer delete blocked?
- The layer is used by one or more projects.
- The app intentionally prevents deleting in-use semantic models.
Why does Ask Optra say chat is not enabled?
- The selected account does not have chat enabled.
- Contact your administrator to enable this feature.