Redshift unit test limitation

website/docs/docs/build/unit-tests.md

@@ -26,8 +26,8 @@ With dbt Core v1.8 and dbt Cloud environments that opt to "Keep on latest versio
 - You must specify all fields in a BigQuery STRUCT in a unit test. You cannot use only a subset of fields in a STRUCT.
 - If your model has multiple versions, by default the unit test will run on *all* versions of your model. Read [unit testing versioned models](#unit-testing-versioned-models) for more information.
 - Unit tests must be defined in a YML file in your `models/` directory.
-- Available to dbt Cloud customers who have selected ["Keep on latest version"](/docs/dbt-versions/upgrade-dbt-version-in-cloud#keep-on-latest-version) and  dbt Core v1.8.0 or later.
 - Table names must be [aliased](/docs/build/custom-aliases) in order to unit test `join` logic.
+- Redshift customers need to be aware of a [limitation when building unit tests](/reference/resource-configs/redshift-configs#unit-test-limitations) that requires a workaround. 
 
 Read the [reference doc](/reference/resource-properties/unit-tests) for more details about formatting your unit tests.
 

website/docs/reference/resource-configs/redshift-configs.md

@@ -257,3 +257,88 @@ The workaround is to execute `DROP MATERIALIZED VIEW my_mv CASCADE` on the data
 </VersionBlock>
 
 </VersionBlock>
+
+<VersionBlock firstVersion="1.8">
+
+## Unit test limitations
+
+Unit tests aren't supported on Redshift if the SQL in the common table expression (CTE) contains functions such as `LISTAGG`, `MEDIAN`, `PERCENTILE_CONT`, etc. Those functions must be executed against a user-created table. dbt combines given rows to be part of the CTE, which is unsupported by Redshift. You can try the following SQL:
+
+```sql
+
+create temporary table "test_tmpxxxxx" as (
+   with test_fixture as (
+       select
+         cast(1000 as integer) as id,
+         cast('menu1' as character varying(500)) as name,
+         cast( 1 as integer) as quantity
+      union all
+      select
+         cast(1001 as integer) as id,
+         cast('menu2' as character varying(500)) as name,
+         cast( 1 as integer) as quantity
+      union all
+      select
+         cast(1003 as integer) as id,
+         cast('menu1' as character varying(500)) as name,
+         cast( 1 as integer) as quantity
+   ),
+   agg as (
+      SELECT
+         LISTAGG(name || ' x ' || quantity, ',') AS option_name_list,
+         id
+      FROM test_fixture
+      GROUP BY id
+   )
+   select * from agg
+);
+
+```
+This results in the error: 
+
+```bash
+
+[XX000] ERROR: One or more of the used functions must be applied on at least one user created tables. Examples of user table only functions are LISTAGG, MEDIAN, PERCENTILE_CONT, etc
+
+```
+
+However, the following query works as expected:
+
+```sql
+
+create temporary table "test_tmp1234" as (
+   SELECT
+      cast(1000 as integer) as id,
+      cast('menu1' as character varying(500)) as name,
+      cast( 1 as integer) as quantity
+   union all
+   select
+      cast(1001 as integer) as id,
+      cast('menu2' as character varying(500)) as name,
+      cast( 1 as integer) as quantity
+   union all
+   select
+      cast(1000 as integer) as id,
+      cast('menu1' as character varying(500)) as name,
+      cast( 1 as integer) as quantity
+);
+
+with agg as (
+   SELECT
+      LISTAGG(name || ' x ' || quantity, ',') AS option_name_list,
+      id
+   FROM test_tmp1234
+   GROUP BY id
+)
+select * from agg;
+
+```
+
+If all given rows are created as a temporary table first, then running the test by referring to it will result in a successful run.
+
+In short, separate the unit tests into two steps:
+1. Prepare test fixtures by creating temporary tables.
+2. Run unit test query by referring to the temporary tables.
+
+</VersionBlock>
+