Skip to content
sandadocs
Console Start free trial

Dimensions and filters

Dimensions are the columns you slice by. Named filters say which rows count. Categories give one word to a way of slicing across source systems.

View as Markdown

A metric says what to count. Three other kinds of definition say how to slice it and which rows to count:

  • A dimension is a column you slice by, such as customer name or issued date.
  • A category is one word for a way of slicing that several columns share, such as region.
  • A named filter is a condition your team says out loud, such as paid invoices, written down once.

Dimensions

"Revenue by region" needs a region. A dimension gives a column a name people use, other words for it, and, for a date, a grain and a roll-up.

You do not have to make a dimension of a column to slice by it. In the workbench you can pick any column on the map. A dimension is for the columns people actually ask about, so that a question phrased in your team's words finds the right one.

Add a dimension

Dimensions live in the list view. Press List, open the dimensions tab, and press Add dimension.

Field What to enter Example
Dimension The name customer name
Source column The column, in full: schema, table, column mapping.billing__customers.customer_name
Type Category, Time, Place, Yes / no or Number band Category
Grain For a time dimension, the finest unit day
Rolls up For a time dimension, the steps it rolls up through, finest first, separated by commas day, month, quarter, year
Table The table the column belongs to. Leave it empty for a dimension that any table carrying the column may use customers
Also called Other words, separated by commas client, account
Notes What it means to your team

You can also ask cherry: "make region a dimension on the customers table". A learn pass proposes dimensions too.

A column from the loader's own bookkeeping cannot be a dimension. It is not part of what sanda publishes.

One dimension per column

A column has one dimension. If a column already has one under a different name, sanda refuses the second and says which name it holds:

“customer city” already names mapping.billing__customers.customer_city. One column is one dimension: rename that one, or add “customer town” as a synonym of it.

A second name for one column is a synonym, and that is where it belongs. This is what stops the workbench listing customer city and customer_city as two things when they are one.

To rename a dimension, delete it in the list and add it again under the new name. Adding a dimension under its own existing name changes it in place, so to edit one, re-enter every field.

Time dimensions

Set Type to Time, give it a Grain, and list the steps it rolls up through under Rolls up, finest first: day, month, quarter, year. "By quarter" then becomes a lookup, not a guess about which date function to use.

In the workbench, a time dimension gets a grouping control: each row, day, week, month, quarter or year. Grouping a column that is not a date is refused with a sentence, not a warehouse error.

Synonyms

Also called words work like the aliases described in naming rules. A word finds a dimension only if it names exactly one. The workbench's search and the agent's lookups match them, and the agent's full text lists them after "Also called".

Categories

A dimension names one column. A category names the idea, so it can cover many columns. region in your billing system and ship_region in your shop would need two dimensions under two names, and nothing tells an agent they are the same question. As one category, region covers both, and "by region" works across the two systems.

Create a category and tag its columns

  1. Open categories. Press categories on the rail.
  2. Name it. Type in New category (for example region or channel) and press add category. Press the new category's name to open it.
  3. Say what it means. Under "What this way of slicing means to your team", write a note and press save. The agent reads it beside the column list.
  4. Tick the columns. Columns that carry it is on the left, and a finder on the right lists every column on the map. Search for region, zone or state and tick each column that carries the idea.

You can also tag from a card. Hover over a column, press the tag icon, and tick categories in the dialog, or create a new one there.

A column can carry more than one category, because a region column can also be territory. Hover over a category in the panel and every column it covers lights up on the map, so you can see that region is tagged on three tables and missed on a fourth.

What the agent gets is one instruction: "group by this, and here is every column that means it". A category whose tables are all off the map is left out.

Named filters

Every other kind says what a column is. None says which rows count. "Approved", "open" and "excluding staff accounts" would otherwise be re-explained in every question, or copied into one metric's condition and left to drift. Name the condition once and use it by name.

Name a condition

  1. Open filters. Press filters on the rail, then name a condition. You need a table on the map.
  2. Name it. For example approved invoices.
  3. Write the condition. In the field that reads "Only rows where", enter a SQL condition over the table's columns, such as status = 'AUTHORISED' and voided_at is null.
  4. Pick the table. The table is required. An unqualified condition means nothing until you know whose status it is.
  5. Add other words and notes if you want them. Then press save filter.

The condition must be a single SQL fragment: no semicolon and no comment, up to 1,000 characters.

To change a filter, press it in the list and press edit. Saving under the same name replaces it. There is no rename, because nothing builds a filter out of another filter: to rename one, save it under the new name and delete the old one.

Using a filter

  • In the workbench, filters have their own folder. Press one to add it to the question.
  • The agent is told that a named filter is your own definition of which rows count, and to use it by name. Its full text gives the condition to put in the where clause exactly as written.
  • If the filter's table leaves the map, the filter stops applying, and its row in the panel reads "table has gone".

Three ways to narrow rows

Belongs to Has a name Use it when
A metric's only counting rows where One metric No The condition is part of what that number means
A named filter The workspace Yes Many questions need the same condition
A condition in the workbench One question No You want to narrow a single question and move on

Conditions use a fixed set of operators and named date periods. See filters.

Something unclear or out of date? Tell us, and we will fix the page.