Every field in Kater is a dimension, a measure or a custom calculation. A dimension is a value to group or filter by. A measure is a recipe for a total, which each reader works out again at its own grouping. A custom calculation is a value worked out over a query’s result rows, such as a rank. Declare a field once, and every query, app and agent reads it by its name.

Three kinds of field

How the three kinds differ

This query of the sample shop has one field of each kind. Region is a dimension, Orders is a measure, and Orders (Rank) is a custom calculation:

1
SELECT
2
  shop.region,
3
  shop.count_distinct__order_id,
4
  CUSTOM_CALCULATION(
5
    'rank__count_distinct__order_id',
6
    KATER__RANK(shop.count_distinct__order_id, 'desc') OVER ()
7
  ) AS "Orders (Rank)"
8
FROM workspace.shop AS shop
9
GROUP BY
10
  shop.region
11
ORDER BY
12
  3

Each kind behaves in its own way when another model reads this query:

• Region stays a value. A reader groups or filters by it.
• Orders stays a recipe. The query passes the measure through, so a reader that shows Orders with no grouping counts the orders again from the order rows. It never adds up these five rows.
• Orders (Rank) stays a finished value. The rank was worked out over these five rows. A reader gets 1 to 5 as they are, and cannot work the rank out again at its own grouping.

Which kind do you need?

The formula decides the kind, not the wrapper. A formula with no aggregate and no measure inside it is a dimension. A window is never a measure. A wrapper that disagrees with its formula gets a warning, and a fix that swaps it.

Declare a field

1
  -- @description Order amount before discounts.
2
  -- @format currency(currency, 2)
3
  MEASURE('sum__amount', KATER__SUM(orders.amount), NOT_ADDITIVE_ACROSS(currency)) AS "Revenue",

• Declarations are outermost. A DIMENSION, MEASURE or CUSTOM_CALCULATION sits in the final SELECT, never inside a CTE, a subquery or a union branch.
• A new field needs a new name. It cannot take the name of any field in scope, from any model the SELECT reads, in any letter case.
• A field you read keeps its name. shop.region or shop.sum__amount on its own passes the source’s field through. See Pass through, evaluate or declare.

Names, labels and identity

• The name is the field’s identity. Queries, apps, tests and agents read a field by its name, so it never changes by accident.
• The label is for people. Change it freely. Nothing that reads the field changes.
• See how a field is computed. The Definitions view shows a card per field, and kater model explain FIELD --relation semantic.shop prints it.
• Find what reads a field. kater references FIELD --relation semantic.shop.
• Rename through the menu. Rename in the field menu updates references in the same model. A model elsewhere that reads the field blocks it.

Fields in the Shared models editor

In a semantic model or Kater dataset, you add, change and describe fields without writing SQL. Each change writes the SQL shown on these pages.

The field list

The Fields tab of the sidebar groups fields by the source they come from.

• A folder per source. Each shows the source’s label and alias, and how many of its fields are in the model. The base comes first and says Base. The order matches the workspace’s field picker for the same model.
• Ticks. A ticked field is in the model. Tick a field to pass it through, and untick it to take it out. ⌘Z undoes either.
• Made here. A field this model declares says Made here.
• Not in the model. Under each folder, the source’s other fields wait unticked.
• Measures are blue. Wherever a field is named, a measure’s name is blue. A dimension’s mark says what it is.
• Search and add. Search fields (/) finds a field. The + beside it makes a new field, and Add source after the folders adds a source.

In a Kater dataset, the table’s columns are locked in, and fields you add show under Made in this dataset. See Kater datasets.

The field panel

Click a field to open its panel. It shows where the field comes from, the source and then the field, and an In the model switch. Then you edit:

• Label and Name. A field whose label is still its SQL name says No label.
• Computes, for a field made here: its formula.
• Description and AI context.
• Format and Values, each Automatic until you set it.
• Tags and Business questions.

Show in SQL opens the SQL pane at the field. Delete field removes a field made here. A field passed through from a source offers Take out of the model in its place.

The field menu

Right-click a field in the list, or a column in Rows. The menu names the field, its source and its expression, with Search operations under them.

A new field from an operation

An operation under Make a new field from it, or the + beside Search fields, opens the new-field dialog. Select Measure or Dimension, and Prompt AI or Manual. On Manual:

1. Start with. The field the new one reads, such as Session Start Date.
2. Turn it into. What to make of it, such as Day of week.
3. Settings. Options for that operation, when it has any.
4. Name it. Optional: Name, SQL name and Description.

The dialog shows the Kater SQL it writes, a preview of the new field’s values and its definition. Select Add to the model.

The Fields sheet

Select Fields above the grid. The sheet has one row per field: Field (its mark and label), Name, Source (the alias), Description, Format, Values and AI context. Click a cell to edit it in place. Paste a column, such as twelve descriptions, and it saves as one change. The header counts the fields with no label, and Write labels with Ask opens Ask with a prompt for your agent that lists them.

Add fields without writing SQL

• In a shared model. Use the field list, the field menu and the new-field dialog above. New › Field and Edit › Add field open the same dialog.
• In a workspace query. Right-click a field in the field list. Its categories are Filters, Sort, Aggregations, Windows, Compare with, Derive, Calculate at, Timeframe, Format and Edit. Each offers only what fits that field and that model. File › New › Field opens New measure, New dimension, New calculation or New filter. See Queries.
• The terminal. kater new field --path QUERY.sql walks the same steps for a query. kater model edit changes any model.
• Your agent. Ask in words. It shows you the field and saves it after your yes.

kater new field --path QUERY.sql --kind calculation --from sum__spend \
  --make previous_period --set output=percent_change --write

Operations name what they add, such as sum__amount or count__status, with a label such as “Status (Count)”. They also write a format: a count gets number(0) and a share of total gets percent(1).

Common errors

These apply to every kind of field. Each kind’s page lists its own.

Next steps