Move a BI workflow to Querio

Start with one report your team uses and a result you trust. unshackle exports its definitions into your Git repository and translates the parts it supports. A coding agent can then use Querio CLI to rebuild the analysis in Querio. Compare the executed result before sharing it as a replacement.

This is a port, not a native import. Exported notebooks, semantic models and policies are source material for the agent; they do not become Querio notebooks, context or access rules on their own.

1. Choose a report and baseline

Pick a representative source report with its important metrics, filters and charts. Make sure you can export its definitions and identify the data it reads.

Save a trusted result from that report, or an independently checked query. Record its date range, filters, timezone, currency, data snapshot and user or row-level access scope. You will use these conditions to judge the Querio result, not just its headline total.

You also need an analytics Git repository. Install unshackle using its current README; use the CLI repository when you reach the porting step. Keep source credentials out of tracked files and agent prompts.

2. Export definitions with unshackle

Run unshackle from your analytics repository. For a downloaded Tableau workbook:

unshackle init
unshackle import tableau "Saved Report.twbx"
unshackle build tableau
unshackle todo

Replace the filename with your workbook. Tableau file import also accepts .twb, .tds, .tdsx and folders containing them. If the workbook packages data needed to run its exported notebooks locally, the Tableau guide explains --with-data. That copy does not connect the data to Querio. Re-importing replaces earlier raw files for that source, so include every input you intend to keep.

With Tableau API access, you can scope extraction to a workbook ID from inventory:

unshackle check tableau --prompt
unshackle inventory tableau
unshackle migrate tableau --only workbook:WORKBOOK_ID
unshackle todo

Replace WORKBOOK_ID with the selected ID. migrate initializes the repository, inventories the source, extracts the selected work and builds the files. Check its dependencies and extraction errors: the source account can export only what it can access. For another BI tool, follow its guide from the unshackle README for supported API or file input and scope.

3. Review extraction gaps

Read migration/report.md and the relevant TODO(unshackle) markers. Check warnings, failed or skipped extraction and unsupported translations. Keep the original expression beside an unresolved translation; deleting a marker does not fix its meaning. Run unshackle todo again as you resolve items.

These are unshackle's default paths; unshackle.toml can change them, and dbt projects have different semantic output defaults. They are not Querio's context layout. Use Context files and Add and improve context when selecting definitions to carry over.

Review files before committing them through your normal Git workflow. Raw exports may contain data or identities you should keep out of the repository. Give the agent the selected report's files, baseline and open gaps.

4. Port the report with a coding agent

Create a Querio account if needed, connect the relevant data, and complete CLI setup. Run a small query against the connected datasource before porting the report. The connection guide owns datasource setup and access checks.

Have the agent read the CLI's workflow and notebook-authoring guidance:

querio code skill
querio code skill --reference notebook-authoring

Give it a bounded task, replacing the placeholders with your report, workspace ID and datasource slug:

Port REPORT from this repository to Querio workspace WORKSPACE_ID
using Querio CLI and datasource DATASOURCE_SLUG.

Read the source definitions, migration/report.md, relevant exported
queries/notebook, and unresolved TODOs. Read Querio's workflow and
notebook-authoring reference before writing cells.

Rebuild only this report as visible Querio notebook cells. Preserve its
metric definition, filters, timezone, grain, currency, and chart meaning.
Keep source references and unresolved differences with the analysis.
Do not guess unsupported expressions or treat exported policies as
applied Querio access rules.

Run and inspect the actual cells. Compare their rows and totals with
the supplied independent baseline under the same filters and access scope.
Confirm saving and return the notebook ID, comparison, and remaining gaps.

The agent uses an editable notebook session and Code Mode through querio code exec. It must replace the exported notebook's standalone warehouse connection with queries against the configured Querio datasource. Naming the slug in the task does not select it for the session or grant access; follow the CLI reference.

Move only vetted descriptions and business rules into supported Querio context. Exported Cedar policies and row filters do not create Querio users, roles, groups or credentials. Configure access separately and check effective query access as intended users.

5. Compare the executed result

Inspect the executed query and calculation cells, errors and outputs. Compare row counts, keys, column meanings, subtotals and final totals under the baseline's data snapshot, dates, filters, timezone and access scope. Agree any numeric tolerance before accepting a difference. Record deliberate exclusions and unsupported behavior.

For repeatable checks of exported SQL, unshackle can run cases in migration/parity/*.yaml with unshackle verify and a configured warehouse connection. Its pass, differs and not checked results assess the export, not the Querio cells. Compare the actual Querio output too; Check and correct an answer covers that workflow.

If results differ, inspect filters, aggregation grain, joins, null handling and access scope. Correct the analysis and rerun affected cells before changing the baseline. Confirm which cells ran; an earlier output may still be visible after a source edit.

6. Save and share the replacement

Confirm saving succeeded, then inspect the saved notebook with the ID returned by the agent:

querio notebook get NOTEBOOK_ID --json

Reopen the Explore and check its saved cells and results. A stored result is not a fresh query against current data; Analyze your data explains that distinction.

Keep the source report reference, repository revision, comparison conditions and remaining TODOs with the handover. Review the charts and controls with the intended reader, then share the Explore or board and check access as that recipient. Keep the source report available until the replacement passes your agreed checks.

After saving, close only the session and environment created for this task. If saving fails, inspect the existing work and resolve the error before retrying authoring; see Execution reference.