{"record":{"id":"12528f234e644fb2","repo":"cocoindex-io/cocoindex","slug":"vectorspecprovider-is-required-for-numpy-ndarray-t","errorCode":null,"errorMessage":"VectorSpecProvider is required for NumPy ndarray type.","messagePattern":"VectorSpecProvider is required for NumPy ndarray type\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/cocoindex/connectors/postgres/_target.py","lineNumber":287,"sourceCode":"    Use `PgType` annotation with `typing.Annotated` to override the default.\n    \"\"\"\n    type_info = analyze_type_info(python_type)\n\n    # Check for PgType annotation override\n    for annotation in type_info.annotations:\n        if isinstance(annotation, PgType):\n            return _TypeMapping(annotation.pg_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 pgvector type bases; dimension is handled at the schema layer.\n    if base_type is np.ndarray:\n        if vector_schema is None:\n            raise ValueError(\"VectorSpecProvider is required for NumPy ndarray type.\")\n        if vector_schema.size <= 0:\n            raise ValueError(f\"Invalid pgvector dimension: {vector_schema.size}\")\n\n        # Default to `vector` (float32/float64/int64/etc.). Use `halfvec` for float16.\n        base = \"halfvec\" if vector_schema.dtype in (np.half, np.float16) else \"vector\"\n        return _TypeMapping(\n            pg_type=f\"{base}({vector_schema.size})\", encoder=_vector_encoder\n        )\n\n    elif vector_schema is not None:\n        raise ValueError(\n            f\"VectorSpecProvider 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    ):","sourceCodeStart":269,"sourceCodeEnd":305,"githubUrl":"https://github.com/cocoindex-io/cocoindex/blob/e84aa99b3292c5270a4b313b2a7137ad9ce8ab3b/python/cocoindex/connectors/postgres/_target.py#L269-L305","documentation":"A NumPy ndarray column maps to a pgvector type, and the required vector dimension and dtype come from a VectorSpecProvider. If no vector schema is supplied for an ndarray-typed field, the type mapping cannot be built and ValueError is raised.","triggerScenarios":"Defining a record type with an np.ndarray field for TableTarget.from_class without providing column_overrides containing a VectorSchemaProvider for that column.","commonSituations":"Embedding columns in rows: developers add an ndarray field but forget the vector schema override, especially when the dimension is not statically known.","solutions":["Provide a VectorSchemaProvider for the ndarray column via column_overrides in from_class.","Ensure the provider's size is a positive integer.","Alternatively use a type with an explicit leaf mapping if a vector column is not intended."],"exampleFix":"// before\ntarget = await PgTableTarget.from_class(EmbedRow, primary_key=[\"id\"])\n// after\ntarget = await PgTableTarget.from_class(\n    EmbedRow, primary_key=[\"id\"],\n    column_overrides={\"embedding\": VectorSchemaProvider(size=768)})","handlingStrategy":"validation","validationCode":"import numpy as np\nfor name, tp in get_type_hints(EmbedRow).items():\n    if tp is np.ndarray:\n        assert name in column_overrides, f\"Provide VectorSchemaProvider for '{name}'\"","typeGuard":"import numpy as np\ndef ndarray_columns_have_overrides(row_type: type, overrides: dict) -> bool:\n    import typing\n    hints = typing.get_type_hints(row_type)\n    return all(\n        name in overrides\n        for name, tp in hints.items()\n        if tp is np.ndarray\n    )","tryCatchPattern":"try:\n    target = await PgTableTarget.from_class(Row, primary_key=[\"id\"], column_overrides=overrides)\nexcept ValueError as e:\n    if \"VectorSpecProvider is required\" in str(e):\n        overrides = {**overrides, \"embedding\": VectorSchemaProvider(size=DIM)}","preventionTips":["Always supply a VectorSchemaProvider for every ndarray field.","Define the embedding dimension as a module constant and reuse it in the provider.","Wrap from_class in a helper that injects vector overrides automatically."],"tags":["python","pgvector","numpy","configuration"],"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"}