Replace the #raw directive in custom SQL

The #raw directive in custom SQL is deprecated. Replace it with the #identifier directive, as described below.

🚧

The #raw directive in custom SQL is deprecated. After December 1, 2026, Sigma will no longer support the #raw directive, and queries that use it will fail to run. To avoid query errors, update any custom SQL that uses #raw to use the #identifier directive before that date.

About the change

When you reference a control or parameter value in custom SQL, Sigma passes the value into your query wrapped in single quotation marks. Previously, you could remove these quotation marks to pass raw text entries by using the #raw directive on the control:

{{#raw control-id}}

Sigma has introduced the #identifier directive as the supported replacement:

{{#identifier [control-id]}}

The #identifier directive isn't a one-to-one replacement for #raw. Unlike #raw, #identifier always produces a quoted identifier. In many data platforms, quoted identifiers are case-sensitive, so you might need to make additional changes to your query to account for this difference.

Identify custom SQL that uses #raw

To manually review the custom SQL statements in a document:

1. Open a workbook or data model for editing.

2. Click Lineage (), then search for SQL to list the custom SQL elements in the document.

3. For each Custom SQL element, select the element and review the SQL query for the {{#raw ...}} directive.

For more details about locating and editing custom SQL, see Update custom SQL.

Identify custom SQL that uses #raw programmatically

To programmatically review workbooks in an organization for the #raw directive:

1. Use the list workbooks endpoint to retrieve a list of workbooks in your organization.
2. Use the workbookId returned by the list workbooks endpoint with the list workbook sources endpoint to get a list of sources for any workbook in your organization.
3. In each response, review the listed sources for any with a type of custom-sql.
4. For each custom-sql source, review the definition - which contains the custom SQL statement - for the #raw directive.

To programmatically review data models in an organization for the #raw directive:

1. Use the list data models endpoint to retrieve a list of data models in your organization.
2. Use the dataModelId returned by the list data models endpoint with the list data model sources endpoint to get a list of sources for any data model in your organization.
3. In each response, review the listed sources for any with a type of custom-sql.
4. For each custom-sql source, review the definition - which contains the custom SQL statement - for the #raw directive.

Update #raw to #identifier

For each custom SQL statement that uses #raw, replace the directive with #identifier.

For more examples of the #identifier directive, see Return rows based on a schema text selector.

Replace schema selection

For statements where a control or user attribute value was used to dynamically select a schema, replace the #raw directive with #identifier.

In the following example query, schema is the control ID of the control used to select the schema:

SELECT *
FROM EXAMPLES.{{#raw schema}}.STATIONS

Update the statement to use the #identifier directive instead:

SELECT *
FROM EXAMPLES.{{#identifier [schema]}}.STATIONS

If the schema was previously selected using a user attribute, you can use the #identifier directive along with the CurrentUserAttributeText function to read the attribute as an identifier. For example, if a user attribute called schema is used to select the schema, you can write a custom SQL query like the following:

SELECT *
FROM EXAMPLES.{{#identifier CurrentUserAttributeText('schema')}}.TRIP

After you update the statement, run the SQL and confirm that the query returns the expected results, then publish the document.

Replace database and schema selection

For statements where a single control value or user attribute was used to identify both the database and schema, you must separate the database and schema selection.

📘

Unlike the #raw directive, #identifier treats strings containing the . character as a single identifier containing the literal ., rather than treating it as the separator syntax for a name path in SQL. Because of this difference, you must separate the identifiers when performing dynamic schema selection in custom SQL.

In the following example, a control with the control-id database-and-schema is used to select both the database and schema with the #raw directive. If the control contained the text EXAMPLES.BIKES, the query would select all columns from the EXAMPLES.BIKES.STATIONS table.

SELECT *
FROM {{#raw database-and-schema}}.STATIONS

To update this query to use the #identifier directive, you can use separate controls - database and schema - instead:

SELECT *
FROM {{#identifier [database]}}.{{#identifier [schema]}}.STATIONS

Alternatively, you can parse the contents of a single control into multiple statements using the SplitPart function. In this example, a control called database-and-schema with contents EXAMPLES.BIKES is parsed into two separate statements:

SELECT *
FROM {{#identifier SplitPart([database-and-schema], '.', 1)}}.{{#identifier SplitPart([database-and-schema], '.', 2)}}.STATIONS

If the database and schema were previously selected using a user attribute, you can parse the user attribute into two identifiers. For example, if a user attribute called database-and-schema is used to select the database and schema, you can write a custom SQL query like the following:

SELECT *
FROM {{#identifier SplitPart(CurrentUserAttributeText('database-and-schema'), '.', 1)}}.{{#identifier SplitPart(CurrentUserAttributeText('database-and-schema'), '.', 2)}}.STATIONS

After you update the statement, run the SQL and confirm that the query returns the expected results, then publish the document.