{"record":{"id":"03b004753f49bc86","repo":"cocoindex-io/cocoindex","slug":"vectorschemaprovider-is-required-for-numpy-ndarray-03b004","errorCode":null,"errorMessage":"VectorSchemaProvider is required for NumPy ndarray type.","messagePattern":"VectorSchemaProvider is required for NumPy ndarray type\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/cocoindex/connectors/neo4j/_target.py","lineNumber":313,"sourceCode":"\n\nasync def _get_type_mapping(\n    python_type: Any, *, vector_schema: res_schema.VectorSchema | None = None\n) -> _TypeMapping:\n    type_info = analyze_type_info(python_type)\n\n    for annotation in type_info.annotations:\n        if isinstance(annotation, Neo4jType):\n            return _TypeMapping(annotation.neo4j_type, annotation.encoder)\n\n    base_type = type_info.base_type\n\n    if base_type in _LEAF_TYPE_MAPPINGS:\n        return _LEAF_TYPE_MAPPINGS[base_type]\n\n    if base_type is np.ndarray:\n        if vector_schema is None:\n            raise ValueError(\"VectorSchemaProvider is required for NumPy ndarray type.\")\n        if vector_schema.size <= 0:\n            raise ValueError(f\"Invalid vector dimension: {vector_schema.size}\")\n        return _TypeMapping(\n            neo4j_type=\"LIST<FLOAT>\",\n            encoder=_ndarray_to_list,\n        )\n    elif vector_schema is not None:\n        raise ValueError(\n            \"VectorSchemaProvider is only supported for NumPy ndarray type. \"\n            f\"Got type: {python_type}\"\n        )\n\n    if isinstance(type_info.variant, (SequenceType,)):\n        return _ARRAY_MAPPING\n    if isinstance(type_info.variant, (MappingType, RecordType, UnionType, AnyType)):\n        return _OBJECT_MAPPING\n\n    return _OBJECT_MAPPING","sourceCodeStart":295,"sourceCodeEnd":331,"githubUrl":"https://github.com/cocoindex-io/cocoindex/blob/e84aa99b3292c5270a4b313b2a7137ad9ce8ab3b/python/cocoindex/connectors/neo4j/_target.py#L295-L331","documentation":"This ValueError is raised by _get_type_mapping when a column's Python type is numpy.ndarray but no VectorSchemaProvider (vector schema) was supplied in column_overrides. The connector needs the vector size (and metadata) to map the ndarray to Neo4j's LIST<FLOAT> type. It cannot infer the dimension from the type annotation alone, so it fails fast.","triggerScenarios":"Building a TableSchema from a record type with an np.ndarray field (embedding column) without passing a VectorSchemaProvider for that column in column_overrides.","commonSituations":"Defining a dataclass with an `embedding: np.ndarray` field and forgetting the override; refactoring from list[float] to ndarray without adding the vector schema; auto-generated schemas where column_overrides was not populated.","solutions":["Pass column_overrides={\"<field>\": res_schema.VectorSchemaProvider(size=<dim>)} when building the TableSchema.","Annotate the field appropriately or provide the vector schema via the schema-building API.","If the column should not be a vector, change the type or drop the column."],"exampleFix":"// before\nTableSchema.from_class(DocRecord)  # DocRecord.embedding: np.ndarray\n// after\nTableSchema.from_class(DocRecord, column_overrides={\"embedding\": VectorSchemaProvider(size=768)})","handlingStrategy":"validation","validationCode":"import dataclasses, numpy as np\nfrom cocoindex.resources import schema as res_schema\noverrides = {\n    f.name: res_schema.VectorSchemaProvider(size=EMBED_DIM)\n    for f in dataclasses.fields(Record)\n    if f.type is np.ndarray\n}","typeGuard":null,"tryCatchPattern":"try:\n    schema = await TableSchema.from_class(Record, column_overrides=overrides)\nexcept ValueError as e:\n    raise RuntimeError(\"every ndarray column needs a VectorSchemaProvider override\") from e","preventionTips":["Build column_overrides programmatically from the record's ndarray fields","Document that every np.ndarray column requires a vector schema override","Add a startup check that overrides cover all ndarray columns"],"tags":["neo4j","numpy","vector","schema"],"backgroundTag":"missing-required-config-field","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"}