Invalid SQL syntax generated for clickhouse database on join keys when using tesseract

[BlueMagma2]

Describe the bug
Invalid SQL syntax generated for clickhouse database when grouping by joined cubes
Cubejs generate join key of the form: (table1.col1 = table2.col2 OR ((table1.col1 IS NULL) AND (table2.col2 IS NULL))), trying to match keys having null values,

Clickhouse doesn't support using "is null" in join keys

It also try to cast fields to STRING instead of String which also cause a syntax error on clickhouse (EDITED 02/04/26)

Clickhouse doesn't support using "is null" in join keys

To Reproduce
make a query involving a group by over a joined cube with clickhouse as the database backend

Expected behavior
Generate another equivalent syntax compatible with clickhouse, for exemple COALESCE(table1.col1, -1) = COALESCE(table2.col2, -1) works

Version:
cubejs:1.3, cubejs:1.6.7

*EDIT 02/04/26:
Relevant Configuration
CUBEJS_TESSERACT_SQL_PLANNER: "true" <= This gets fixed when tesseract is deactivated

[igorlukanin]

make a query involving a group by over a joined cube with clickhouse as the database backend

Hey @BlueMagma2 👋

Could you please submit a minimal data model example + a query that produce incorrect SQL?

I've tried to reproduce this myself but wasn't lucky enough so far.

[magno32]

@igorlukanin

This is affecting us too.

Attaching a cube yaml that causes the issue (executed against ClickHouse).

test_table.yml

This query fails:

{
  "measures": [
    "test_sales.units_prior_year",
    "test_sales.units"
  ],
  "dimensions": [
    "test_stores.name"
  ],
  "timeDimensions": [
    {
      "dimension": "test_sales.ts",
      "dateRange": "last year"
    }
  ]
}

This query works, if we do not induce a join:

{
  "measures": [
    "test_sales.units_prior_year",
    "test_sales.units"
  ],
  "dimensions": [],
  "timeDimensions": [
    {
      "dimension": "test_sales.ts",
      "dateRange": "last year"
    }
  ]
}

[igorlukanin]

Thanks for the data model @magno32 🙌

I see, you have Tesseract turned on, correct?

I've tested with v1.6.6. Without Tesseract:

WITH cte_0 AS (
  SELECT
    `test_stores`.name `test_stores__name`,
    sum(`test_sales`.units) `test_sales__units`
  FROM
    (
      SELECT
        1 as id,
        'store_1' as store_id,
        toDateTime('2025-01-01') as ts,
        100 as units
      UNION ALL
      SELECT
        2,
        'store_1',
        toDateTime('2024-01-01'),
        400
    ) AS `test_sales`
    LEFT JOIN (
      SELECT
        'store_1' as store_id,
        'Main Street Store' as name
    ) AS `test_stores` ON `test_sales`.store_id = `test_stores`.store_id
  WHERE
    (
      (addDate(`test_sales`.ts, INTERVAL 1 YEAR)) >= parseDateTimeBestEffort(?)
      AND (addDate(`test_sales`.ts, INTERVAL 1 YEAR)) <= parseDateTimeBestEffort(?)
    )
  GROUP BY
    `test_stores__name`
  ORDER BY
    `test_sales__units` DESC
),
cte_1 AS (
  SELECT
    `test_stores__name` `test_stores__name`,
    `test_sales__units` `test_sales__units_prior_year`
  FROM
    (
      SELECT
        q_0.`test_stores__name` `test_stores__name`,
        `test_sales__units` `test_sales__units`
      FROM
        cte_0 AS q_0
      ORDER BY
        `test_sales__units` DESC
    ) AS cte_1_join
)
SELECT
  q_0.`test_stores__name` `test_stores__name`,
  `test_sales__units_prior_year` `test_sales__units_prior_year`,
  `test_sales__units` `test_sales__units`
FROM
  (
    SELECT
      `main__test_stores`.name `test_stores__name`,
      sum(`main__test_sales`.units) `test_sales__units`
    FROM
      (
        SELECT
          1 as id,
          'store_1' as store_id,
          toDateTime('2025-01-01') as ts,
          100 as units
        UNION ALL
        SELECT
          2,
          'store_1',
          toDateTime('2024-01-01'),
          400
      ) AS `main__test_sales`
      LEFT JOIN (
        SELECT
          'store_1' as store_id,
          'Main Street Store' as name
      ) AS `main__test_stores` ON `main__test_sales`.store_id = `main__test_stores`.store_id
    WHERE
      (
        `main__test_sales`.ts >= parseDateTimeBestEffort(?)
        AND `main__test_sales`.ts <= parseDateTimeBestEffort(?)
      )
    GROUP BY
      `test_stores__name`
  ) AS q_0
  INNER JOIN (
    SELECT
      *
    FROM
      cte_1
  ) AS q_1 ON (
    assumeNotNull(q_0.`test_stores__name`) = assumeNotNull(q_1.`test_stores__name`)
  )
ORDER BY
  `test_sales__units_prior_year` DESC
LIMIT
  10000

With Tesseract:

WITH cte_0 AS (
  SELECT
    `test_stores`.name `test_stores__name`,
    sum(`test_sales`.units) `test_sales__units`
  FROM
    (
      SELECT
        1 as id,
        'store_1' as store_id,
        toDateTime('2025-01-01') as ts,
        100 as units
      UNION ALL
      SELECT
        2,
        'store_1',
        toDateTime('2024-01-01'),
        400
    ) AS `test_sales`
    LEFT JOIN (
      SELECT
        'store_1' as store_id,
        'Main Street Store' as name
    ) AS `test_stores` ON `test_sales`.store_id = `test_stores`.store_id
  WHERE
    (
      (addDate(`test_sales`.ts, INTERVAL 1 YEAR)) >= parseDateTimeBestEffort(?)
      AND (addDate(`test_sales`.ts, INTERVAL 1 YEAR)) <= parseDateTimeBestEffort(?)
    )
  GROUP BY
    1
  ORDER BY
    2 DESC
),
cte_1 AS (
  SELECT
    `fk_aggregate`.`test_stores__name` `test_stores__name`,
    `fk_aggregate`.`test_sales__units` `test_sales__units_prior_year`
  FROM
    (
      SELECT
        *
      FROM
        cte_0 AS `cte_0`
    ) AS `fk_aggregate`
)
SELECT
  `fk_aggregate_keys`.`test_stores__name` `test_stores__name`,
  `q_1`.`test_sales__units_prior_year` `test_sales__units_prior_year`,
  `q_0`.`test_sales__units` `test_sales__units`
FROM
  (
    SELECT
      DISTINCT `test_stores__name` `test_stores__name`
    FROM
      (
        SELECT
          `test_stores`.name `test_stores__name`
        FROM
          (
            SELECT
              1 as id,
              'store_1' as store_id,
              toDateTime('2025-01-01') as ts,
              100 as units
            UNION ALL
            SELECT
              2,
              'store_1',
              toDateTime('2024-01-01'),
              400
          ) AS `test_sales`
          LEFT JOIN (
            SELECT
              'store_1' as store_id,
              'Main Street Store' as name
          ) AS `test_stores` ON `test_sales`.store_id = `test_stores`.store_id
        WHERE
          (
            `test_sales`.ts >= parseDateTimeBestEffort(?)
            AND `test_sales`.ts <= parseDateTimeBestEffort(?)
          )
        GROUP BY
          1
        UNION ALL
        SELECT
          DISTINCT `test_stores__name` `test_stores__name`
        FROM
          cte_1 AS `cte_1`
      ) AS `pk_aggregate_keys_source`
  ) AS `fk_aggregate_keys`
  LEFT JOIN (
    SELECT
      `test_stores`.name `test_stores__name`,
      sum(`test_sales`.units) `test_sales__units`
    FROM
      (
        SELECT
          1 as id,
          'store_1' as store_id,
          toDateTime('2025-01-01') as ts,
          100 as units
        UNION ALL
        SELECT
          2,
          'store_1',
          toDateTime('2024-01-01'),
          400
      ) AS `test_sales`
      LEFT JOIN (
        SELECT
          'store_1' as store_id,
          'Main Street Store' as name
      ) AS `test_stores` ON `test_sales`.store_id = `test_stores`.store_id
    WHERE
      (
        `test_sales`.ts >= parseDateTimeBestEffort(?)
        AND `test_sales`.ts <= parseDateTimeBestEffort(?)
      )
    GROUP BY
      1
  ) AS `q_0` ON (
    (
      `fk_aggregate_keys`.`test_stores__name` = `q_0`.`test_stores__name`
      OR (
        (`fk_aggregate_keys`.`test_stores__name` IS NULL)
        AND (`q_0`.`test_stores__name` IS NULL)
      )
    )
  )
  LEFT JOIN (
    SELECT
      *
    FROM
      cte_1 AS `cte_1`
  ) AS `q_1` ON (
    (
      `fk_aggregate_keys`.`test_stores__name` = `q_1`.`test_stores__name`
      OR (
        (`fk_aggregate_keys`.`test_stores__name` IS NULL)
        AND (`q_1`.`test_stores__name` IS NULL)
      )
    )
  )
ORDER BY
  2 DESC
LIMIT
  10000

This surely needs to be fixed.

[magno32]

Yes, we have Tesseract enabled, as its grouping strategies will be vital to our use-case. We are currently testing with it.

Apologies, should have mentioned that.

[BlueMagma2]

We also use tesseract, we've had a second syntax problem that was fixed when deactivating tesseract:

• With tesseract: CAST(field as STRING)
• Without tesseract: CAST(field as String) <= the correct syntax for clickhouse

It seems to me that tesseract doesn't properly take into account the specificity of the configured database

[ksnikiforov]

+1 having the same issue

[igorlukanin]

Reproduced the null-safe join-key issue on v1.6.7 with Tesseract: the multi-fact join condition is emitted as (a = b OR (a IS NULL AND b IS NULL)), which ClickHouse rejects in JOIN ON.

Fixed as of v1.6.24 — the ClickHouse dialect now emits isNotDistinctFrom(a, b) instead (commit 43429eb, #10494). Confirmed gone on latest v1.6.57.

Note: the separate CAST(field as STRING) vs String symptom @BlueMagma2 raised is not addressed by that fix and looks like a distinct casing bug — probably worth tracking separately.

[igorlukanin]

The separate CAST(field as STRING) vs String casing @BlueMagma2 raised is a distinct, smaller bug (Tesseract doesn't override the ClickHouse String type template). Fix is up in #11053 and will resolve it once merged.

Closing this issue as the originally reported problem is resolved; the casing follow-up is tracked in #11053.