> ## 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.

<AgentInstructions>

## Submitting Feedback

If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:

POST https://docs.omni.co/feedback

```json
{
  "path": "/modeling/dimensions/parameters/sql",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

# sql

> The core declaration of the field definition using SQL.

The core declaration of the field definition. Best practice dictates using field references over raw database columns when calling other fields/dimensions. Note that dimensions can only be derived from other dimensions, unlike measures.

## Syntax

```yaml theme={null}
<dimension_name>:
  sql: <sql_expression>
```

## Properties

<ParamField path="dimension_name" type="object">
  The name of the dimension. Dimension names must:

  * Be unique within the view
  * Start with a letter
  * Contain only alphanumeric characters and underscores

  <Expandable title="dimension_name properties" defaultOpen="true">
    <ParamField path="sql" type="string">
      A SQL expression that defines the dimension. If the SQL includes protected words (e.g., `group`), include them with the following syntax: ``"`group`"``

      Field type is implicit in Omni, and defined based upon the underlying field's database type. To change the type, `CAST` the field (for example, `sql: ${zip_code}::string`).

      <Tip>
        When referencing other fields, use Omni field references (`${view.name}`) instead of the raw database name. For example, `${orders.id}`
      </Tip>
    </ParamField>
  </Expandable>
</ParamField>

## DO NOT PARSE (special argument)

`DO NOT PARSE` is a special argument used to stop Omni's parser from interpreting and validating the SQL. This should be used in the rare circumstance that Omni is not saving valid SQL in the model, which can happen when obscure, dialect-specific SQL is used.

```yaml DO NOT PARSE usage theme={null}
<dimension_name>:
  sql: |-
    -- DO NOT PARSE
    <sql_expression>
crazy_sql:
  sql: |-
    -- DO NOT PARSE
    function_that_is_weird(${field})
```

## Examples

```yaml Concatenated fields theme={null}
full_name:
  sql: CONCAT(${users.first_name}, ' ', ${users.last_name})
```

```yaml Calculated margin theme={null}
margin:
  sql: ${order_items.sale_price} - ${products.cost}
```

```yaml Case statement theme={null}
is_special_date:
  sql: |-
    CASE
      WHEN ${orders.created_at[date]} >= '2022-04-14' AND ${orders.created_at[date]} <= '2022-05-09'
      THEN 'Mothers Day 2022'
      WHEN ${orders.created_at[date]} >= '2022-05-26' AND ${orders.created_at[date]} <= '2022-06-20'
      THEN 'Fathers Day 2022'
      ELSE 'Other'
    END
```

```yaml DO NOT PARSE usage theme={null}
state_sentiment:
  sql: |-
    -- DO NOT PARSE
    SNOWFLAKE.CORTEX.SENTIMENT(${states.state})::float
```

```yaml Type casting theme={null}
zip_code_string:
  sql: ${zip_code}::string
```