> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omni.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Dimensions

> A dimension is an attribute that describes a row of data.

Dimensions are used as the primary segmentation and grouping when querying. They can be date/time, strings, booleans, or numbers. Omni also has helpers for working with [nested dimensions like JSON](#creating-fields-from-json).

By default, when a model is generated, Omni will use the schema model to create dimensions for every column in the database.

## Ordering fields

Fields in the Omni model do not currently allow free-form ordering but instead operate in the following framework:

| Object                           | Order                 | Re-arrangeable? |
| -------------------------------- | --------------------- | --------------- |
| View columns (schema dimensions) | Database column order | No              |
| Shared model dimensions          | Saved by default      | Yes, on save    |
| Workbook/branch model fields     | Saved by default      | Yes, on save    |
| Measures                         | Saved by default      | Yes, on save    |
| Filters                          | Saved by default      | Yes, on save    |

<Note>
  Interleaving between these groupings is not currently supported.
</Note>

## Naming dimensions

Dimension names must be unique within any given view (no same names). Names may use characters a-z (no capital letters), 0-9, or underscores, and start with a letter.

Additional [parameters](/modeling/dimensions/parameters/index) are nested under the dimension with one tab (two spaces) of indention, for example:

```yaml title="Field naming" highlight={2,6} theme={null}
dimensions:
  first_name:               # the name of the field/dimension
    label: Full Name
    sql: CONCAT(${first_name}, ' ' ${last_name})

  is_from_california:
    sql: ${state} = 'California'
```

## Permissing field values with user attributes

There may be situations where you need to control who sees the values for specific fields. To accomplish this, use [user attributes](/administration/users/attributes) in a dimension's [`sql`](/modeling/dimensions/parameters/sql) definition to mask or hide values as needed:

```yaml title="Hiding field values" theme={null}
name:
  sql: ${users.full_name}

name_hidden:
  sql: |+
    CASE
      WHEN {{omni_attributes.see_names}} = 'true'
      THEN ${users.name}
      ELSE 'No Access'
    END
```

```yaml title="Hashing field values" theme={null}
name:
  sql: ${users.full_name}

name_hashed:
  sql: |+
    CASE
      WHEN {{omni_attributes.see_names}} = 'true'
      THEN ${users.state}
      ELSE MD5(${users.name})
    END
```

## Filter-only fields

Filter-only fields are often used alongside [templated filters](/modeling/templated-filters) to create fields for more specific use cases that only operate as filters, often to dynamically filter fact tables or subqueries.

## Handling schema field adjustments

Raw schema field names may need to be adjusted to work correctly in Omni for analytics. This can happen due to type casing issues, timezone adjustments, or other complex reasons. You can account for this by creating an additional field, for example:

```yaml title="Creating a new adjusted field" theme={null}
string_that_should_be_number: {}

adjusted_field:
  sql: ${string_that_should_be_number}::bigint
```

If you want to keep the raw field name and adjust the field in place, modify the SQL on the base field. Note that the following example doesn't use `${}` syntax:

```yaml title="Adjusting field in place" theme={null}
string_that_should_be_number:
  sql: string_that_should_be_number::bigint

created_at:
  sql: DATETIME(created_at, 'America/Los_Angeles')
```

## Creating fields from JSON

<Note>
  This section only applies to modeled fields. Fields defined in raw SQL are not supported.
</Note>

Fields recognized as JSON - both true JSON and stringified JSON - can be parsed in Omni's UI. In the workbook's **Results** tab, right-click a row in the results table and then **Create fields from JSON**:

<img src="https://mintcdn.com/omni-e7402367/9t1yQdiHpH1adDvI/modeling/dimensions/images/json-parsing.gif?s=bd5b25914c511e44935b8ae72e8ea848" alt="JSON parsing" width="1257" height="810" data-path="modeling/dimensions/images/json-parsing.gif" />

Omni will parse the JSON and create new fields in the workbook.

<Note>
  When parsing JSON, you may need to manually cast fields to the correct data type after they are created. For example, timestamp fields may be created as strings.
</Note>

## Level of Detail (LoD) Fields

Level of Detail (LoD) fields let you control the exact granularity at which an aggregation is computed, independent of how the rest of the query is grouped. Use the [`level_of_detail`](/modeling/dimensions/parameters/level-of-detail) parameter on a dimension to define it as an LoD field.