cube-js/cube · error · UserError

Distributed approximate distinct count is not supported by t

Error message

Distributed approximate distinct count is not supported by this DB

What it means

hllInit() is the base dialect hook used to initialize HyperLogLog state for distributed approximate distinct counts (needed when distinct counts are computed across multiple nodes/pre-aggregations). The default BaseQuery implementation is a stub that always throws, since not every database has HLL primitives.

Source

Thrown at packages/cubejs-schema-compiler/src/adapter/BaseQuery.js:3989

    if (symbol.type === 'count' || symbol.type === 'sum') {
      return `sum(${evaluateSql})`;
    } else if (symbol.type === 'countDistinctApprox') {
      return topLevelMerge ? this.hllCardinalityMerge(evaluateSql) : this.hllMergeOnly(evaluateSql);
    } else if (symbol.type === 'min' || symbol.type === 'max') {
      return `${symbol.type}(${evaluateSql})`;
    }
    return undefined;
  }

  topAggregateWrap(symbol, evaluateSql) {
    if (symbol.type === 'countDistinctApprox') {
      return this.hllCardinality(evaluateSql);
    }
    return evaluateSql;
  }

  hllInit(_sql) {
    throw new UserError('Distributed approximate distinct count is not supported by this DB');
  }

  hllMerge(_sql) {
    throw new UserError('Distributed approximate distinct count is not supported by this DB');
  }

  hllCardinality(_sql) {
    throw new UserError('Distributed approximate distinct count is not supported by this DB');
  }

  hllMergeOnly(sql) {
    return this.hllMerge(sql);
  }

  hllCardinalityMerge(sql) {
    return this.hllMerge(sql);
  }

View on GitHub (pinned to 7d981676b3)

Solutions

Switch to a database/adapter with HLL support (e.g. Postgres with postgresql-hll, BigQuery, Snowflake)
Override hllInit/hllMerge/hllCardinality in a custom adapter for your DB
Replace the approximate measure with an exact regular countDistinct measure

Example fix

// before
measures: { visitors: { type: 'countDistinctApprox', sql: 'user_id' } }
// after
measures: { visitors: { type: 'countDistinct', sql: 'user_id' } } // or move to an HLL-capable DB

Defensive patterns

Strategy: fallback

Validate before calling

const approxSupported = ['postgres', 'bigquery', 'snowflake', 'clickhouse', 'duckdb'];
if (measureType === 'countDistinctApprox' && !approxSupported.includes(dbType)) {
  console.warn('Distributed HLL not supported; falling back to exact countDistinct');
}

Type guard

function supportsHllInit(adapter) {
  return typeof adapter.hllInit === 'function' &&
    adapter.hllInit !== Object.getPrototypeOf(Object.getPrototypeOf(adapter)).hllInit;
}

Try / catch

try { return await cube.load(measures, query); } catch (e) {
  if (/Distributed approximate distinct count/.test(e.message)) {
    return await cube.load(withExactCountDistinct(measures), query);
  }
  throw e;
}

Prevention

Use countDistinctApprox only on dialects with HLL support
Keep an exact countDistinct variant of key measures as a fallback
Pin database versions that ship HLL extensions

When it happens

Trigger: A query or pre-aggregation plan requests approximate distinct count in a mode that requires distributed HLL (hllInit) while running against an adapter that did not override hllInit.

Common situations: Using countDistinctApprox (approximate distinct count measure type) on a database driver that lacks HLL support; mixing in rolled-up approx counts across cubes on an unsupported DB.

Related errors

AI-assisted analysis of cube-js/cube@7d981676b3 (2026-09-02). Data as JSON: /api/errors/086a7214e4eb0951. Report an issue: GitHub.