cocoindex-io/cocoindex · error

Invalid metric name: {metric}

Error message

Invalid metric name: {metric}

What it means

The metric argument must be 'l2_distance' or 'inner_product', or a custom Doris distance function name that is a valid Python identifier (used as distance_fn in the ORDER BY). Anything else — spaces, dashes, empty string — raises ValueError.

Source

Thrown at python/cocoindex/connectors/doris/_target.py:1416

        _validate_identifier(table_parts[1])
        quoted_table = f"`{table_parts[0]}`.`{table_parts[1]}`"
    elif len(table_parts) == 1:
        _validate_identifier(table)
        quoted_table = f"`{table}`"
    else:
        raise ValueError(f"Invalid table name format: {table}")

    _validate_identifier(vector_field)

    if metric == "l2_distance":
        distance_fn = "l2_distance_approximate"
        order = "ASC"
    elif metric == "inner_product":
        distance_fn = "inner_product_approximate"
        order = "DESC"
    else:
        if not metric.isidentifier():
            raise ValueError(f"Invalid metric name: {metric}")
        distance_fn = metric
        order = "ASC" if "distance" in metric else "DESC"

    vector_literal = "[" + ", ".join(str(float(v)) for v in query_vector) + "]"

    if select_columns:
        quoted_columns = []
        for col in select_columns:
            _validate_identifier(col)
            quoted_columns.append(f"`{col}`")
        select = ", ".join(quoted_columns)
    else:
        select = "*"

    query = f"""SELECT {select}, {distance_fn}(`{vector_field}`, {vector_literal}) as _distance
FROM {quoted_table}"""

    if where_clause:

View on GitHub (pinned to e84aa99b32)

Solutions

1. Use one of the supported values: 'l2_distance' or 'inner_product'
2. For custom functions, pass a bare function identifier, e.g. metric='cosine_distance'
3. Sanitize/normalize the metric string before calling

Example fix

// before
build_vector_search_query(..., metric="l2-distance")
// after
build_vector_search_query(..., metric="l2_distance")

assert metric in ("l2_distance", "inner_product") or metric.isidentifier(), f"bad metric: {metric}"

try:
    sql = build_vector_search_query(..., metric=metric)
except ValueError as e:
    logger.error("Unsupported metric %r", metric); raise

When it happens

Trigger: Calling build_vector_search_query(metric='cosine') is fine only if 'cosine' is a valid identifier; errors occur for metric names like 'l2-distance', 'cosine similarity', '' or None passed by mistake.

Common situations: Copying metric names from other vector DBs (e.g. 'cosine_sim' with dashes, pgvector's '<->' operator); passing an enum's string repr like 'Metric.L2'; UI-supplied metric strings with spaces.

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

• record_type must be a record type, got {type(record_type)}
• Invalid table name format: {table}
• aiohttp is required for Doris connector. Install it with: pi
• pymysql is required for Doris connector DDL operations. Inst
• {operation_name} failed after {config.max_retries + 1} attem

AI-assisted analysis of cocoindex-io/cocoindex@e84aa99b32 (2026-09-08). Data as JSON: /api/errors/d52cde69844b53ed. Report an issue: GitHub.