perspective-dev/perspective · error · Error

Unknown type

Error message

Unknown type '${name}'

What it means

`duckdbTypeToPsp()` in the ClickHouse virtual-server adapter maps ClickHouse/duckdb type names to Perspective type strings (`string`, `date`, etc.). When it encounters a type `name` it has no mapping for, it throws "Unknown type '<name>'". Callers `tableSchema`, `tableValidateExpression`, and `dtype` hit this whenever a remote table's schema contains a type the adapter does not recognize.

Solutions

1. Upgrade perspective / the ClickHouse adapter to a version whose `duckdbTypeToPsp` mapping includes the offending type.
2. Change the column type on the ClickHouse side (e.g. cast `Nullable(X)` to `X`, or cast exotic types to String) before registering the table.
3. Cast unmapped columns to a supported type in your query (e.g. `CAST(col AS String)`) when defining the table.
4. If the type is broadly a known one, patch the mapping function to add the `name` → psp-type case (check exact casing).

Example fix

// before
SELECT id, tags FROM events -- tags is Array(String): Unknown type 'Array(String)'
// after
SELECT id, CAST(tags AS String) AS tags FROM events

const SUPPORTED = new Set(["String", "Int8", "Int16", "Int32", "Int64", "UInt8", "UInt16", "UInt32", "UInt64", "Float32", "Float64", "Bool", "Date", "DateTime"]);
for (const col of schema) {
  if (!SUPPORTED.has(col.type)) console.warn(`Unmapped ClickHouse type '${col.type}' for column ${col.name}; cast or upgrade adapter.`);
}

function isSupportedClickHouseType(t: string): boolean {
  return /^(String|Bool|Date|DateTime|Float\d\d?|U?Int\d+)$/.test(t);
}

try {
  const schema = await tableSchema(table);
} catch (e) {
  const m = String(e.message).match(/Unknown type '(.+)'/);
  if (m) {
    console.error(`ClickHouse type ${m[1]} not supported; cast the column to a base type.`);
  }
  throw e;
}

When it happens

Trigger: A ClickHouse table includes a column type not in the adapter's mapping — e.g. `UUID`, `Array(...)`, `Tuple(...)`, `Map(...)`, `Enum8/Enum16`, `Nullable(...)` wrapping an unmapped base, `IPv4/IPv6`, `FixedString`, or an unusually cased name like `date` vs `Date` (mapping is case-sensitive: `Date` matches, `DATE` does not).

Common situations: Schemas created with newer ClickHouse types than the adapter version supports; columns using composite/parameterized types (Array, Tuple, Nullable) that the flat mapping can't express; case-mismatched type names from a driver or middleware normalizing types differently.

Related errors

• Unknown type
• Missing perspective-client.wasm

AI-assisted analysis of perspective-dev/perspective@11c8238c0c (2026-09-09). Data as JSON: /api/errors/11146ea2a8d4c09b. Report an issue: GitHub.

Appendix: source

Thrown at rust/perspective-js/src/ts/virtual_servers/clickhouse.ts:159

    }

    if (name === "Int64" || name === "UInt64" || name === "Float64") {
        return "float";
    }

    if (name === "String") {
        return "string";
    }

    if (name === "DateTime") {
        return "datetime";
    }

    if (name === "Date") {
        return "date";
    }

    throw new Error(`Unknown type '${name}'`);
}

function convertDecimalToNumber(value: any, dtypeString: string) {
    if (!(value instanceof Uint32Array || value instanceof Int32Array)) {
        return value;
    }

    let bigIntValue = BigInt(0);
    for (let i = 0; i < value.length; i++) {
        bigIntValue |= BigInt(value[i]) << BigInt(i * 32);
    }

    const scaleMatch = dtypeString.match(/Decimal\[\d+e(\d+)\]/);
    if (scaleMatch) {
        const scale = parseInt(scaleMatch[1]);
        return Number(bigIntValue) / Math.pow(10, scale);
    } else {
        return Number(bigIntValue);

View on GitHub (pinned to 11c8238c0c)