perspective-dev/perspective · error · ValueError

Unknown type

Error message

Unknown type '{name}'

What it means

clickhouse_type_to_psp maps ClickHouse column type names to Perspective type strings ('date', 'datetime', string, float, etc.). It raises ValueError when it encounters a ClickHouse type name it does not recognize, so schema construction, expression validation, or data fetch for a table with that column type fails.

Solutions

1. Identify the offending column from the error's type name and cast it in the query to a supported type (e.g. toString(col), toDate(col)) before it reaches Perspective
2. Update/patch clickhouse_type_to_psp in perspective/virtual_servers/clickhouse.py to map the new type to the appropriate Perspective type
3. Pin/align the ClickHouse server version with one whose type names the connector recognizes

Example fix

# before
SELECT * FROM my_table
// after
SELECT toString(enum_col) AS enum_col, arrayJoin(arr_col) AS arr_col FROM my_table

# Before creating a table/view, check the ClickHouse schema types:
allowed = {"String","Float64","Int64","UInt64","Date","DateTime"}
schema = run_clickhouse("DESCRIBE TABLE my_table")
unsupported = [row.type for row in schema if row.type not in allowed]
if unsupported:
    print("Cast these columns in the query:", unsupported)

try:
    table = client.table(query, db)
except ValueError as e:
    if str(e).startswith("Unknown type '"):
        bad = str(e).split("'")[1]
        query = query.replace(bad, f"toString({bad})")
        table = client.table(query, db)
    else:
        raise

When it happens

Trigger: Creating a Perspective table/view over ClickHouse data whose schema contains an unmapped ClickHouse type (e.g. Enum8, Array, Nullable variants, UUID, or a version-specific type name) — reached via table_schema, table_validate_expression, or view_get_data.

Common situations: Querying ClickHouse tables with advanced/region-specific column types; ClickHouse server version differences introducing new type names; using the ClickHouse virtual server against tables with Array/Enum columns.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Unknown type
• Missing perspective-client.wasm

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

Appendix: source

Thrown at rust/perspective-python/perspective/virtual_servers/clickhouse.py:260

        name = name[9:-1]

    if name.startswith("Array"):
        return "string"

    if name in ("Int64", "UInt64", "Float64"):
        return "float"

    if name == "String":
        return "string"

    if name == "DateTime":
        return "datetime"

    if name == "Date":
        return "date"

    msg = f"Unknown type '{name}'"
    raise ValueError(msg)


def run_query(db, query, execute=False, columns=False):
    query = " ".join(query.split())
    start = datetime.now()
    result = None
    try:
        if execute:
            db.command(query)
        else:
            req = db.query(query)
            result = req.result_rows
    except Exception as e:
        logger.error(e)
        logger.error(f"{query}")
        raise e
    else:
        logger.debug(f"{datetime.now() - start} {query}")

View on GitHub (pinned to 11c8238c0c)