cocoindex-io/cocoindex · error · ValueError

build_relationship_index_create requires at least one field

Error message

build_relationship_index_create requires at least one field

What it means

This ValueError is raised by build_relationship_index_create when the fields sequence used to build a Neo4j relationship index is empty. A Cypher relationship index must index at least one property, so generating the CREATE INDEX statement with no fields would produce invalid Cypher. The library throws early to fail at statement-construction time rather than at database execution time.

Source

Thrown at python/cocoindex/connectors/neo4j/_cypher.py:197


def build_node_index_drop(name: str) -> str:
    """``DROP INDEX <name> IF EXISTS``.

    Unlike FalkorDB's by-(label, field) drop, Neo4j drops indexes by name
    regardless of kind (node or relationship).
    """
    return f"DROP INDEX {_quote(name)} IF EXISTS"


def build_relationship_index_create(
    name: str,
    rel_type: str,
    fields: Sequence[str],
) -> str:
    """``CREATE INDEX <name> IF NOT EXISTS FOR ()-[r:`RelType`]-() ON (r.`f1`, ...)``."""
    if not fields:
        raise ValueError("build_relationship_index_create requires at least one field")
    field_list = ", ".join(f"r.{_quote(f)}" for f in fields)
    return (
        f"CREATE INDEX {_quote(name)} IF NOT EXISTS "
        f"FOR ()-[r:{_quote(rel_type)}]-() ON ({field_list})"
    )


def build_relationship_index_drop(name: str) -> str:
    """``DROP INDEX <name> IF EXISTS``.

    Same DROP statement as for node indexes — Neo4j unifies the namespace.
    """
    return f"DROP INDEX {_quote(name)} IF EXISTS"


def build_constraint_create(
    name: str,
    label: str,

View on GitHub (pinned to e84aa99b32)

Solutions

Pass at least one relationship property name in fields, e.g. ['weight'].
If fields are computed, check the list before calling and skip index creation when empty.
Verify the upstream schema/config actually populates the fields collection.

Example fix

// before
build_relationship_index_create("rel_weight_idx", "KNOWS", [])
// after
build_relationship_index_create("rel_weight_idx", "KNOWS", ["weight"])

Defensive patterns

Strategy: validation

Validate before calling

if not fields:
    raise ValueError("fields must contain at least one property name")  # or skip index creation
build_relationship_index_create(name, rel_type, fields)

Try / catch

try:
    stmt = build_relationship_index_create(name, rel_type, fields)
except ValueError as e:
    logging.warning("skipping relationship index %s: %s", name, e)

Prevention

Assert len(fields) > 0 in the config loader before index setup
Log a warning and skip instead of building an index when a rel type has no indexed fields
Keep index field lists derived from the same schema source as the data

When it happens

Trigger: Calling build_relationship_index_create(name, rel_type, fields=[]) with an empty list/tuple of field names — e.g. deriving fields from a schema that produced no indexed columns, or passing a literal empty list.

Common situations: Schema introspection returning no indexed fields for a relationship type; a config file where the 'index_fields' key is present but empty; filtering fields by type and accidentally excluding all of them.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

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