{"record":{"id":"19912b139640b88b","repo":"cocoindex-io/cocoindex","slug":"vectorschemaprovider-is-required-for-numpy-ndarray-19912b","errorCode":null,"errorMessage":"VectorSchemaProvider is required for NumPy ndarray type.","messagePattern":"VectorSchemaProvider is required for NumPy ndarray type\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/cocoindex/connectors/surrealdb/_target.py","lineNumber":284,"sourceCode":"    Use ``SurrealType`` annotation with ``typing.Annotated`` to override.\n    \"\"\"\n    type_info = analyze_type_info(python_type)\n\n    # Check for SurrealType annotation override\n    for annotation in type_info.annotations:\n        if isinstance(annotation, SurrealType):\n            return _TypeMapping(annotation.surreal_type, annotation.encoder)\n\n    base_type = type_info.base_type\n\n    # Check direct leaf type mappings\n    if base_type in _LEAF_TYPE_MAPPINGS:\n        return _LEAF_TYPE_MAPPINGS[base_type]\n\n    # NumPy ndarray: map to array<float, 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\n        return _TypeMapping(\n            surreal_type=f\"array<float, {vector_schema.size}>\",\n            encoder=_ndarray_encoder,\n        )\n\n    elif vector_schema is not None:\n        raise ValueError(\n            f\"VectorSchemaProvider is only supported for NumPy ndarray type. \"\n            f\"Got type: {python_type}\"\n        )\n\n    # Complex types that need JSON encoding\n    if isinstance(\n        type_info.variant, (SequenceType, MappingType, RecordType, UnionType, AnyType)\n    ):","sourceCodeStart":266,"sourceCodeEnd":302,"githubUrl":"https://github.com/cocoindex-io/cocoindex/blob/e84aa99b3292c5270a4b313b2a7137ad9ce8ab3b/python/cocoindex/connectors/surrealdb/_target.py#L266-L302","documentation":"When mapping a record's Python types to SurrealDB column types, a field of type numpy.ndarray requires a VectorSchemaProvider so CocoIndex knows the vector dimension N for the array<float, N> SurrealDB type. Without it the dimension is unknown and the mapping fails.","triggerScenarios":"Declaring a SurrealDB table_target/relation_target whose record type includes an np.ndarray field but passing no vector_schema for that column in _columns_from_record_type.","commonSituations":"Embedding vectors stored as numpy arrays without attaching a VectorSchemaProvider (with size and dimension) to the column definition; migrating a schema from another connector where vectors were typed differently.","solutions":["Attach a VectorSchemaProvider specifying the vector size/dimension to the ndarray field's column definition.","Alternatively change the field type to a typed sequence (e.g. list[float]) with a fixed length if vector semantics are not needed.","Verify the record type annotation is actually np.ndarray for that field and that the schema builder maps it to the provider."],"exampleFix":"// before\ncolumns = {\"embedding\": np.ndarray}\n// after\ncolumns = {\"embedding\": VectorSchemaProvider(size=768, dtype=np.float32)}","handlingStrategy":"type-guard","validationCode":"if any(isinstance(t, np.ndarray) for t in record_type_fields.values()) and not vector_schemas:\n    raise ValueError(\"ndarray fields require a VectorSchemaProvider\")","typeGuard":"def ndarray_fields_have_vector_schema(fields, schemas) -> bool:\n    import numpy as np\n    return all(\n        t is not np.ndarray or name in schemas\n        for name, t in fields.items()\n    )","tryCatchPattern":"try:\n    target = table_target(record_type, ...)\nexcept ValueError as e:\n    if \"VectorSchemaProvider is required\" in str(e):\n        # add vector_schema to the ndarray column and rebuild the target\n        ...","preventionTips":["Attach a VectorSchemaProvider whenever a record field is annotated np.ndarray.","Centralize vector column definitions (dimension + dtype) in one module.","Add a schema-building test that covers ndarray fields."],"tags":["surrealdb","vector","numpy","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"}