{"record":{"id":"193900bd83a60ef0","repo":"cocoindex-io/cocoindex","slug":"zvec-collections-require-at-least-one-vector-field","errorCode":null,"errorMessage":"zvec collections require at least one vector field (dense or sparse).","messagePattern":"zvec collections require at least one vector field \\(dense or sparse\\)\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/cocoindex/connectors/zvec/_target.py","lineNumber":966,"sourceCode":"    Args:\n        db: A ContextKey for the ManagedConnection (provided via lifespan).\n        collection_name: Name of the collection (a subdirectory under the\n            connection's base path).\n        schema: Schema definition built via ``CollectionSchema.from_class``.\n        managed_by: Whether CocoIndex manages the collection lifecycle\n            (\"system\") or it must already exist (\"user\", documents only).\n    \"\"\"\n    _validate_collection_name(collection_name)\n    for name in schema.columns:\n        if name != schema.primary_key:\n            _validate_identifier(name, \"field name\")\n\n    if not any(\n        col.kind in (\"dense\", \"sparse\")\n        for name, col in schema.columns.items()\n        if name != schema.primary_key\n    ):\n        raise ValueError(\n            \"zvec collections require at least one vector field (dense or sparse).\"\n        )\n\n    key = _CollectionKey(db_key=db.key, collection_name=collection_name)\n    spec = _CollectionSpec(schema=schema, managed_by=managed_by)\n    return _collection_provider.target_state(key, spec)\n\n\ndef declare_collection_target(\n    db: ContextKey[ManagedConnection],\n    collection_name: str,\n    schema: CollectionSchema[RowT],\n    *,\n    managed_by: target.ManagedBy = target.ManagedBy.SYSTEM,\n) -> \"CollectionTarget[RowT, coco.PendingS]\":\n    \"\"\"Declare a zvec collection target and return a CollectionTarget for rows.\"\"\"\n    provider = coco.declare_target_state_with_child(\n        collection_target(db, collection_name, schema, managed_by=managed_by)","sourceCodeStart":948,"sourceCodeEnd":984,"githubUrl":"https://github.com/cocoindex-io/cocoindex/blob/e84aa99b3292c5270a4b313b2a7137ad9ce8ab3b/python/cocoindex/connectors/zvec/_target.py#L948-L984","documentation":"collection_target() validates that the declared schema has at least one vector field (dense or sparse) besides the primary key, since zvec is a vector collection store. A schema of only scalar columns raises ValueError.","triggerScenarios":"Calling collection_target()/declare_collection_target()/mount_collection_target() with a record type whose columns are all scalar (no embedding/vector field).","commonSituations":"Forgetting to add the embedding column; a schema-refactoring step that removed the vector field; using a text-only table schema with a zvec backend.","solutions":["Add a dense (or sparse) vector column to your record type and populate it with embeddings.","Use a different (non-vector) target connector if you only need scalar storage.","Check schema.columns for at least one kind in ('dense','sparse') before calling collection_target."],"exampleFix":"// before\n@dataclass\nclass Doc:\n    id: str\n    title: str\n// after\n@dataclass\nclass Doc:\n    id: str\n    title: str\n    embedding: list[float]  # declared as dense vector column","handlingStrategy":"validation","validationCode":"if not any(c.kind in (\"dense\", \"sparse\") for n, c in schema.columns.items() if n != schema.primary_key):\n    raise ValueError(\"schema needs at least one vector column\")","typeGuard":"def has_vector_column(schema) -> bool:\n    return any(c.kind in (\"dense\", \"sparse\") for n, c in schema.columns.items() if n != schema.primary_key)","tryCatchPattern":"try:\n    target = collection_target(db, collection_name, schema)\nexcept ValueError as e:\n    logging.error(\"invalid zvec schema: %s\", e)","preventionTips":["Always include an embedding (dense or sparse) column in zvec record types.","Use a non-vector connector for scalar-only tables.","Validate the schema before declaring the target."],"tags":["python","vector-database","schema-validation","missing-field"],"backgroundTag":"schema-validation-failed","analyzedSha":"e84aa99b3292c5270a4b313b2a7137ad9ce8ab3b","analyzedAt":"2026-09-08T15:59:19.997Z","contentChangedAt":"2026-09-08T15:59:19.997Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}