Import from Sigma¶

Sigma is a great partner to dbt, and this importer is not meant to replace it. It keeps a copy of your Sigma work in dbt Charts' open format, in git next to your dbt project, so CI can catch model changes that would break it, lineage covers it, and AI agents can read exactly what it computes. See Why import.

This walkthrough moves one Sigma workbook into a dbt Charts board. Read Import from other BI tools first for the overall flow.

1. Create Sigma API credentials¶

In Sigma, open Administration → Developer Access. Creating credentials needs a Sigma admin.
Choose Create New, with REST API access.
Copy the Client ID and Client Secret.

2. Set your API region¶

Sigma's API address depends on the cloud your organization runs in, and cannot be read from a workbook URL, so it is always required. Sigma's API documentation lists the address for each cloud and region; for AWS US it is:

SIGMA_API_BASE='https://aws-api.sigmacomputing.com'

Add it to your gitignored .env with the credentials:

SIGMA_CLIENT_ID='...'
SIGMA_CLIENT_SECRET='...'
SIGMA_API_BASE='https://aws-api.sigmacomputing.com'

3. Find the workbook¶

Copy the workbook URL from your browser, or search the workbooks the credentials can see. The text after --list filters on name and folder path:

set -a; . ./.env; set +a; dct import sigma --list revenue

Each line shows the last update date, the name, the folder path, and the URL.

4. Import the workbook¶

set -a; . ./.env; set +a; dct import sigma https://app.sigmacomputing.com/acme/workbook/AbC123

A workbook's url id or workbook id works too:

dct import sigma AbC123

The command writes ./sigma-abc123/ (the id, lowercased). Use --out for another folder and --force to refresh an existing bundle.

What you get¶

Path	From Sigma
`contents.json`	The workbook definition, with every page and element
`outline.md`	Pages and elements in layout order, with columns, filters, controls, and formats
`queries/`	The SQL Sigma compiles for each element
`kpi/`	The current value of each single-value element
`png/`	Sigma's render of each page, numbered in page order
`source.json`	The fetch record

An export Sigma reports as failed is listed in outline.md under Not fetched; the rest of the bundle is written. An export that does not finish in time fails the import; rerun it.

5. Migrate it¶

Migrate ./sigma-abc123 into a dbt Charts board.

See Migrate the bundle for what the agent does.

Sigma-specific notes¶

Workbooks are multi-page. Each Sigma page becomes a section or tab in the board, in the same order.
Controls reach specific elements. The outline says which elements each control filters, and the board wires its variable to exactly those charts.
Workbook-wide filters live in the SQL. Filters that apply to a whole data element do not always show in the outline; the agent reads them from queries/.

Troubleshooting¶

Message	Fix
`SIGMA_CLIENT_... not set`	Load your `.env` in the same command
`the Sigma API base depends on your cloud region`	Set `SIGMA_API_BASE` for your region (step 2)
`... is not a Sigma workbook URL`	Copy the URL from a workbook page, which contains `/workbook/`
`Sigma export ... did not finish in time`	Sigma was slow to export; rerun the import
`no workbook matching ... is visible to these credentials`	Share the workbook with the user the credentials belong to, or check the id