Skip to main content

# DIMENSION

Declares a dimension: a value on each row that a reader groups by and filters by.

{/* Written by apps/landing-page/scripts/docs/write_kater_functions.py from the compiler's function registry, kater_sql/function_docs.py and scripts/docs/sql-language.md. Do not edit it by hand: change those, then run the script. */}

**Family:** [Field declarations](https://kater.ai/docs/sql-reference/functions/field-declarations/)

The first argument is the field's name, and the `AS` alias is its label.

## Syntax

```sql
DIMENSION('name', expression) AS "Label"
```

## Arguments

| Argument | Description |
| --- | --- |
| `name` | The field's name, in quotes. No other field in this SELECT, or in the models it reads, can have it, in any letter case. |
| `expression` | The value for each row. It reads the row's own values, such as `orders.amount`, and has no aggregate. |

## Returns

A dimension, with the type of its expression.

## Usage notes

- Write it only in the model's final SELECT, as a whole column. It cannot go in a CTE, a subquery, a clause or one branch of a union.
- The formula decides the kind. An aggregate is a measure, so `DIMENSION` around an aggregate gets a warning and a fix.
- The label comes from `AS`. A field takes no `@label` comment.

## Example

This Sandbox query reads the sample shop's orders. The table shows the rows that Kater gave.

```sql {2}
SELECT
  DIMENSION('amount_band', CASE WHEN orders.amount >= 200 THEN 'Over 200' ELSE '200 or less' END) AS "Amount Band",
  EVAL(orders.count_distinct__order_id) AS "Orders"
FROM kater_dataset.orders AS orders
GROUP BY
  1
ORDER BY
  1
```

| Amount Band | Orders |
| --- | --- |
| 200 or less | 2,167 |
| Over 200 | 833 |

## See also

- [Fields](https://kater.ai/docs/model/fields/)
- Other functions in [Field declarations](https://kater.ai/docs/sql-reference/functions/field-declarations/): [`MEASURE`](https://kater.ai/docs/sql-reference/functions/measure/), [`CUSTOM_CALCULATION`](https://kater.ai/docs/sql-reference/functions/custom_calculation/), [`NOT_ADDITIVE_ACROSS`](https://kater.ai/docs/sql-reference/functions/not_additive_across/), [`EXCEL`](https://kater.ai/docs/sql-reference/functions/excel/)

On this page

Syntax
Arguments
Returns
Usage notes
Example
See also

Kater SQL Functions Field declarations

DIMENSION

Declares a dimension: a value on each row that a reader groups by and filters by.

Family: Field declarations

The first argument is the field’s name, and the AS alias is its label.

Syntax

1
DIMENSION('name', expression) AS "Label"

Arguments

Argument	Description
`name`	The field’s name, in quotes. No other field in this SELECT, or in the models it reads, can have it, in any letter case.
`expression`	The value for each row. It reads the row’s own values, such as `orders.amount`, and has no aggregate.

Returns

A dimension, with the type of its expression.

Usage notes

Write it only in the model’s final SELECT, as a whole column. It cannot go in a CTE, a subquery, a clause or one branch of a union.
The formula decides the kind. An aggregate is a measure, so DIMENSION around an aggregate gets a warning and a fix.
The label comes from AS. A field takes no @label comment.

Example

This Sandbox query reads the sample shop’s orders. The table shows the rows that Kater gave.

1
SELECT
2
  DIMENSION('amount_band', CASE WHEN orders.amount >= 200 THEN 'Over 200' ELSE '200 or less' END) AS "Amount Band",
3
  EVAL(orders.count_distinct__order_id) AS "Orders"
4
FROM kater_dataset.orders AS orders
5
GROUP BY
6
  1
7
ORDER BY
8
  1

Amount Band	Orders
200 or less	2,167
Over 200	833

See also

Fields
Other functions in Field declarations: MEASURE, CUSTOM_CALCULATION, NOT_ADDITIVE_ACROSS, EXCEL