{"record":{"id":"7f3a51fb2d95b565","repo":"cocoindex-io/cocoindex","slug":"vectorschemaprovider-is-required-for-numpy-ndarray-7f3a51","errorCode":null,"errorMessage":"VectorSchemaProvider is required for NumPy ndarray type.","messagePattern":"VectorSchemaProvider is required for NumPy ndarray type\\.","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"python/cocoindex/connectors/falkordb/_target.py","lineNumber":274,"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, FalkorType):\n            return _TypeMapping(annotation.falkor_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            falkor_type=f\"vector<float32, {vector_schema.size}>\",\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":256,"sourceCodeEnd":292,"githubUrl":"https://github.com/cocoindex-io/cocoindex/blob/e84aa99b3292c5270a4b313b2a7137ad9ce8ab3b/python/cocoindex/connectors/falkordb/_target.py#L256-L292","documentation":"In `_get_type_mapping`, a `numpy.ndarray` column requires an explicit vector schema to know the FalkorDB vector type (`vector<float32, N>`) and dimension. If no `VectorSchemaProvider` override was supplied (via `column_overrides`), the library raises ValueError because the dimension cannot be inferred from the ndarray annotation alone.","triggerScenarios":"Calling `TableSchema.from_class` (which calls `_columns_from_record_type` -> `_get_type_mapping`) on a record type whose field is annotated `np.ndarray` without passing a `VectorSchemaProvider` for that column in `column_overrides`.","commonSituations":"Defining a dataclass row with an `np.ndarray` embedding field and forgetting the column override; assuming the library infers dimension from a default value; copying a schema example that had vector metadata removed.","solutions":["Add a `VectorSchemaProvider` for the ndarray column in `column_overrides`, e.g. `column_overrides={\"embedding\": res_schema.VectorSchemaProvider(dimension=768)}`.","Alternatively annotate the field with a fixed-size typed form if supported instead of bare `np.ndarray`.","Check which column triggered it by comparing record fields against your overrides dict."],"exampleFix":"// before\nawait falkordb.TableSchema.from_class(Record, primary_key=\"id\")\n// after\nawait falkordb.TableSchema.from_class(Record, primary_key=\"id\", column_overrides={\"embedding\": res_schema.VectorSchemaProvider(dimension=384)})","handlingStrategy":"validation","validationCode":"from cocoindex.resources import schema as res_schema\noverrides = {\"embedding\": res_schema.VectorSchemaProvider(dimension=384)}\n# ensure every np.ndarray field has an override before from_class\nfor f in dataclasses.fields(Row):\n    if f.type is \"np.ndarray\" or f.type.endswith(\"ndarray\"):\n        assert f.name in overrides","typeGuard":"def is_ndarray_field(ann: object) -> bool:\n    return ann is np.ndarray or getattr(ann, \"__origin__\", None) is np.ndarray","tryCatchPattern":"try:\n    schema = await falkordb.TableSchema.from_class(Row, column_overrides=overrides)\nexcept ValueError as e:\n    if \"VectorSchemaProvider is required\" in str(e):\n        logging.error(\"Add VectorSchemaProvider for ndarray fields: %s\", e)\n    raise","preventionTips":["Keep a single overrides dict co-located with the record definition.","Never annotate vector fields as bare np.ndarray without a matching override.","Add a unit test that builds all schemas at import time to fail fast."],"tags":["python","falkordb","vector","schema"],"backgroundTag":"missing-required-argument","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"}