Datasets
What a dataset is, the ways to build one, how versions keep your changes, and how it reads live or from an extract.
A dataset is what people in Halo ask questions of. It takes tables from a connection and turns them into fields that read like your business: Revenue and Region, not ord_amt_usd and rgn_cd. Charts, reports, exports and Halo AI all query datasets, and Halo Engine turns each question into SQL for the source.
What a dataset holds
| Part | What it is | Tab in Halo Data |
|---|---|---|
| Source | A main table and its joins, or a SQL query | Joins, or SQL |
| Fields | Dimensions, measures and calculated fields, with labels, descriptions and formats | Fields |
| Drill paths | The steps a click follows, such as country, then state, then city | Fields |
| Report parameters | Values formulas read as @name, such as a target | Fields |
| Row policies | Which rows each person sees | Access |
| Result cache and extract | How long answers are kept, and whether Halo keeps a copy of the rows | Settings |
| Goals | Targets for this dataset's measures | Goals |
| Insights | Measures Halo watches for changes, which Halo AI explains | Insights |
The Explore tab is where you try it: pick dimensions and measures, filter, and see the rows. Chart these results carries what you picked into the chart editor.
Three ways to build one
The first two choose where the rows come from. The third is what you shape on top of either.
Visually, from tables
New dataset starts here. You pick a main table, then any tables to join, and Halo joins them along the relationships discovery found. Queries only join the tables their fields need, so a chart over the main table doesn't pay for the others.
On the Joins tab, each join keeps all rows or only matches, and says how its rows relate: many to one, one to one, one to many or many to many. One-to-many and many-to-many joins repeat rows, so sums of the main table's fields count them more than once. Halo Data warns you when a dataset has one, and suggests counts or measures from the joined table instead.
With a SQL query
Members with the Write custom SQL permission can start from SQL query instead: one SELECT in the connection's dialect. Halo asks the source to check it as you type, without running it, makes a field of each column and previews the first rows. Everything downstream works the same, and row policies wrap around the query.
What people read
The fields are the part of a dataset people actually read: the fields, what each one means, how it adds up and how it displays. There's no separate starting point for it, because every dataset has one. It lives on the Fields tab, whichever way the rows arrive, and holds dimensions, measures, calculated fields, drill paths, default formats and each column's source time zone. See Dimensions, measures and field settings.
Whoever builds a report picks from these fields, and Halo AI reads them to answer questions, so the time you put into labels and descriptions pays off everywhere.
Versions
Every save is a new version. Change what you need, add an optional note under "What changed?" and choose Save new version. The page header shows the current version.
The History tab keeps them all:
Versions lists each save with its note. Restoring one saves it again as the newest, so nothing is lost.
Changes compares any two versions, field by field.
Recent queries shows what ran against the dataset, and which queries were slow or failed.
Before a save that changes fields something uses, and before every restore, Halo Data shows what would change and which charts would stop working. If you renamed a field, it offers to move those charts to the new one. Nothing is blocked: you can save anyway, and affected charts say what's wrong until someone fixes them.
Pin a report or chart to a version
Reports and charts read a dataset's latest version, so a change to the dataset reaches them at once. To keep one as it is while the dataset moves on, pin it:
A report: in the editor, select nothing to see the report's settings. Under Dataset versions, each dataset the report uses has Latest or a version to pick.
A saved chart: open it, and under Dataset version pick one.
A pinned report or chart keeps to that version's fields, formulas and joins everywhere it's read: in Halo Data, on public links and embeds, in snapshots and in PDFs. A report's pin comes before a chart's, for the same dataset.
Two things always come from the latest version, so a pin never shows more than the dataset does now:
Row policies. Tighten one, and a report pinned to an older version shows the tighter rows.
Hidden fields. A field hidden since stays hidden.
When a pin is behind, the report's settings say by how many versions, and which fields moving up would change. Pick Latest to move up: anything that uses a removed field shows what's missing, as it would after any change.
A pinned version reads the source live, since an extract holds the latest version's columns.
Live or extract
A dataset reads its source live by default. Each question becomes a live query, and answers stay in a result cache for 15 minutes unless you change that. Any dataset can also keep an extract: a copy of its rows that Halo refreshes on a schedule and queries with DuckDB, so reports don't wait on the source. A dataset that joins tables from two connections runs only on its extract.
Live queries, extracts and caching covers both, and when to pick which.
Who can use a dataset
A dataset lives in a workspace, and who can use it follows that workspace's sharing. People who can see it but not edit it get a View only badge, and can still explore and chart it.
By default, Owners, Admins, Builders and Analysts can create datasets, and Owners, Admins and Builders can write custom SQL. Roles and permissions has the full table.
Marketplace data your organization has arrives as read-only datasets: you explore and chart them like your own, and add your own filters, but their source, history, access and settings are Halo's.
Deleting a dataset moves it to the Trash for 30 days. Charts over it say so until it's restored.