{"record":{"id":"96391841d577ba95","repo":"cocoindex-io/cocoindex","slug":"vectorschemaprovider-is-required-for-numpy-ndarray-963918","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/sqlite/_target.py","lineNumber":258,"sourceCode":"    Use `SqliteType` annotation with `typing.Annotated` to override the default.\n    \"\"\"\n    type_info = analyze_type_info(python_type)\n\n    # Check for SqliteType annotation override\n    for annotation in type_info.annotations:\n        if isinstance(annotation, SqliteType):\n            return _TypeMapping(annotation.sqlite_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: serialize to sqlite-vec compatible format\n    if base_type is np.ndarray:\n        if vector_schema is None:\n            raise ValueError(\"VectorSchemaProvider is required for NumPy ndarray type.\")\n\n        if vector_schema.size <= 0:\n            raise ValueError(f\"Invalid vector dimension: {vector_schema.size}\")\n\n        # sqlite-vec uses float[N] type (e.g., float[384])\n        import sqlite_vec  # type: ignore\n\n        return _TypeMapping(\n            f\"float[{vector_schema.size}]\", sqlite_vec.serialize_float32\n        )\n\n    elif vector_schema is not None:\n        raise ValueError(\n            f\"VectorSchemaProvider is only supported for NumPy ndarray type. Got type: {python_type}\"\n        )\n\n    # Complex types that need JSON encoding\n    if isinstance(","sourceCodeStart":240,"sourceCodeEnd":276,"githubUrl":"https://github.com/cocoindex-io/cocoindex/blob/e84aa99b3292c5270a4b313b2a7137ad9ce8ab3b/python/cocoindex/connectors/sqlite/_target.py#L240-L276","documentation":"NumPy ndarray columns are stored as sqlite-vec vectors, whose fixed dimension can only be known from an attached VectorSchemaProvider. Without one, `_get_type_mapping` cannot determine the SQL type `float[N]` or the serializer, so it raises. This keeps column schema derivation deterministic from the record type.","triggerScenarios":"Defining a dataclass/NamedTuple record type with an `np.ndarray` field and calling `table_target`/`from_class` without providing a vector schema (no VectorSchemaProvider annotation/metadata for that field).","commonSituations":"Embedding pipelines where the record field is typed `np.ndarray` but the developer forgot to attach the VectorSchemaProvider with the embedding dimension.","solutions":["Attach a VectorSchemaProvider to the ndarray field specifying the vector dimension (e.g. via typing.Annotated).","Alternatively change the field type to a fixed-size type the connector maps without a schema.","Ensure the provider's size matches your embedding model's output dimension."],"exampleFix":"// before\nembedding: np.ndarray\n// after\nembedding: Annotated[np.ndarray, VectorSchemaProvider(size=384)]","handlingStrategy":"validation","validationCode":"import typing\nfrom cocoindex.connectors.sqlite import VectorSchemaProvider\n\nfor name, f in Row.__dataclass_fields__.items():\n    if f.type is np.ndarray or \"ndarray\" in str(f.type):\n        has_schema = any(isinstance(m, VectorSchemaProvider) for m in typing.get_args(f.type)[1:])\n        assert has_schema, f\"Field {name} needs VectorSchemaProvider\"","typeGuard":null,"tryCatchPattern":"try:\n    target = sqlite.table_target(record_type=Row, ...)\nexcept ValueError as e:\n    if \"VectorSchemaProvider is required\" in str(e):\n        raise ConfigError(\"Add Annotated[np.ndarray, VectorSchemaProvider(size=N)] to the embedding field\") from e\n    raise","preventionTips":["Always annotate ndarray fields with Annotated[np.ndarray, VectorSchemaProvider(size=dim)].","Derive the dimension from your embedding model's config, not by hand.","Construct targets in an import-time/test-time smoke check."],"tags":["sqlite","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"}