{"record":{"id":"e5dcb1c3dd941b57","repo":"cocoindex-io/cocoindex","slug":"vectorschemaprovider-is-only-supported-for-numpy-n-e5dcb1","errorCode":null,"errorMessage":"VectorSchemaProvider is only supported for NumPy ndarray type. Got type: {python_type}","messagePattern":"VectorSchemaProvider is only supported for NumPy ndarray type\\. Got type: (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/cocoindex/connectors/sqlite/_target.py","lineNumber":271,"sourceCode":"        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(\n        type_info.variant, (SequenceType, MappingType, RecordType, UnionType, AnyType)\n    ):\n        return _JSON_MAPPING\n\n    # Default fallback\n    return _JSON_MAPPING\n\n\nclass ColumnDef(NamedTuple):\n    \"\"\"Definition of a table column.\"\"\"\n\n    type: str  # SQLite type (e.g., \"TEXT\", \"INTEGER\", \"REAL\", \"BLOB\")\n    nullable: bool = True","sourceCodeStart":253,"sourceCodeEnd":289,"githubUrl":"https://github.com/cocoindex-io/cocoindex/blob/e84aa99b3292c5270a4b313b2a7137ad9ce8ab3b/python/cocoindex/connectors/sqlite/_target.py#L253-L289","documentation":"VectorSchemaProvider metadata is only meaningful on NumPy ndarray fields, where it defines the sqlite-vec vector dimension. Attaching it to a field of any other type is contradictory — there is no vector to size — so `_get_type_mapping` rejects it with this ValueError.","triggerScenarios":"Declaring e.g. `Annotated[list[float], VectorSchemaProvider(size=768)]` or annotating a str/int field with VectorSchemaProvider, then building the target via `table_target`/`from_class`.","commonSituations":"Migrating from a list-of-floats embedding representation to ndarray (or vice versa) and leaving the old annotation in place; copying an annotated field template without changing the type.","solutions":["Change the field type to np.ndarray to match the VectorSchemaProvider annotation.","Or remove the VectorSchemaProvider annotation if the field genuinely isn't a vector.","If lists must be stored as vectors, convert to np.ndarray in the function before declaring the row."],"exampleFix":"// before\nembedding: Annotated[list[float], VectorSchemaProvider(size=768)]\n// after\nembedding: Annotated[np.ndarray, VectorSchemaProvider(size=768)]","handlingStrategy":"type-guard","validationCode":"import typing, numpy as np\nfrom cocoindex.connectors.sqlite import VectorSchemaProvider\n\nfor name, f in Row.__dataclass_fields__.items():\n    ann = typing.get_args(f.type)\n    has_provider = any(isinstance(m, VectorSchemaProvider) for m in ann[1:])\n    if has_provider and ann[0] is not np.ndarray:\n        raise TypeError(f\"VectorSchemaProvider on non-ndarray field {name}: {ann[0]}\")","typeGuard":"def provider_matches_type(annotation: object) -> bool:\n    import typing, numpy as np\n    args = typing.get_args(annotation)\n    base = args[0] if args else annotation\n    has_provider = any(isinstance(m, VectorSchemaProvider) for m in args[1:])\n    return not has_provider or base is np.ndarray","tryCatchPattern":"try:\n    target = sqlite.table_target(record_type=Row, ...)\nexcept ValueError as e:\n    if \"only supported for NumPy ndarray\" in str(e):\n        raise ConfigError(\"Use np.ndarray as the field type together with VectorSchemaProvider\") from e\n    raise","preventionTips":["Pair VectorSchemaProvider only with np.ndarray fields.","When switching representations (list[float] <-> ndarray), update annotations together.","Validate the record type once in tests before production syncs."],"tags":["sqlite","vector","type-mismatch","annotation"],"backgroundTag":"type-mismatch","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"}