Build a dataset

Pick tables or write a query, name the fields, save a version and try it in the explorer.

By the end of this guide you'll have a dataset with fields named for people, saved as its first version and ready to chart.

Before you start

A connection that discovery has read, or uploaded files. See Connections and Upload files.
The Create datasets permission. Owners, Admins, Builders and Analysts have it by default. Starting from a query also needs Write custom SQL, which Analysts don't have by default.
A workspace you can edit. The dataset goes there, and who can use it follows that workspace's sharing.

Start from tables

Open Datasets and choose New dataset.
In the Tables panel, choose a connection, then pick the main table. Every row of the dataset comes from this table, so for revenue by region, pick orders rather than regions.
Pick any tables to join. Halo joins them along the relationships discovery found. A table with no known relationship is left out, and a warning says so.
Read What you'll get. It counts the dimensions, measures and hidden keys, and lists each join and its relationship. If your main table points to lookup tables, it offers to add them, since their names group better than ids.
Give the dataset a Name, choose its Workspace and choose Create dataset.

Halo makes a field of every column, in a folder per table. Numbers become summed measures unless they look like keys, years or places, and a dbt key gives the table a count measure; everything else becomes a dimension. Keys used in joins are hidden, and a main table with one primary key gets a count of its rows, such as Number of orders. You can change all of this next.

Or start from a SQL query

On the New dataset page, choose SQL query at the top.
Choose a connection and write one SELECT in its dialect. Halo asks the source to check it as you type and underlines mistakes, without running it.
Read the Preview of the first rows and the fields in What you'll get. Each column becomes a field, and the first date becomes the default date field.
Give it a Name, choose a Workspace and choose Create dataset.

A table-based dataset only joins what each query needs, so prefer it when tables can say what you mean. Reach for SQL when joins can't, such as for a union or a window function.

Shape the fields

Open the Fields tab. Each row is a field, and most of what you need is right on it:

Label: click it to rename. Labels are safe to change; charts refer to the field's stable name.
Role: Dimension or Measure.
Aggregate: how a measure adds up by default, such as Sum or Average.
Format: for numbers, Automatic, Number, a currency, Percent, Basis points, Duration or a custom pattern.
Eye icon: hide a field from pickers without breaking anything that uses it.
More settings opens the rest: description, folder, semantic type, currency decimals, a custom format and, for timestamps, the zone they were recorded in.

Describe with Halo asks Halo AI to write descriptions for fields that don't have one. You choose which to keep. Descriptions show when people pick a field, and Halo AI reads them too.

To add a number or grouping the source doesn't have, choose Calculated field. See Calculated fields.

Dimensions, measures and field settings explains each setting.

Check the joins

For a table-based dataset, open the Joins tab and check each join:

Keep all rows keeps rows without a match. Only matches drops them.
The relationship says how the joined table's rows relate. Halo Data warns you when a one-to-many or many-to-many join could count rows more than once.

A SQL dataset has a SQL tab here instead, with the query. When you save a change to it, Halo asks the source to check it first.

Add drill paths and parameters

Below the field list on the Fields tab:

Drill paths set the steps a click on a chart follows in Halo Data, such as Region, then City. Dates drill by grain on their own.
Report parameters are values formulas read as @name, such as a growth target. Each has a label, a type and a default. See The formula language.

Save a version

Your changes stay on this page until you save. Add a note under "What changed?" if it would help the next person, then choose Save new version.

If charts, tables or reports use something you changed, Halo Data shows which ones and what would happen to them first. You can save anyway, or move them to a renamed field's replacement. A move changes a report's draft: what's published keeps the old field, so readers get an error there until you publish again, and Halo Data says which reports that is. If the source finds a mistake in custom SQL, or can't be reached, Halo Data says so and lets you decide.

Try it

Open the Explore tab.
Add a dimension and a measure, and a filter if you like.
Choose Chart these results to carry them into the chart editor.

If a number looks wrong, check for a join that repeats rows, then the field's aggregate.