{"record":{"id":"a5d7304478a7d3bf","repo":"cocoindex-io/cocoindex","slug":"zvec-collections-require-exactly-one-primary-key-c","errorCode":null,"errorMessage":"zvec collections require exactly one primary key column (mapped to the document id), got {primary_key}.","messagePattern":"zvec collections require exactly one primary key column \\(mapped to the document id\\), got (.+?)\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/cocoindex/connectors/zvec/_target.py","lineNumber":501,"sourceCode":"            ZvecType | ZvecVectorDef | ZvecFtsType | res_schema.VectorSchemaProvider,\n        ]\n        | None = None,\n    ) -> \"CollectionSchema[RowT]\":\n        \"\"\"Build a CollectionSchema from a record type.\n\n        Args:\n            record_type: A dataclass, NamedTuple, or Pydantic model.\n            primary_key: Exactly one column name. Its value becomes the document\n                id (converted to ``str``).\n            column_overrides: Optional per-column type/vector overrides.\n        \"\"\"\n        if not is_record_type(record_type):\n            raise TypeError(\n                \"record_type must be a record type (dataclass, NamedTuple, \"\n                f\"Pydantic model), got {type(record_type)}\"\n            )\n        if len(primary_key) != 1:\n            raise ValueError(\n                \"zvec collections require exactly one primary key column \"\n                f\"(mapped to the document id), got {primary_key}.\"\n            )\n\n        record_info = RecordType(record_type)\n        columns: dict[str, _Column] = {}\n        for fld in record_info.fields:\n            override = column_overrides.get(fld.name) if column_overrides else None\n            columns[fld.name] = await _resolve_column(fld.name, fld.type_hint, override)\n        return cls(columns, primary_key[0], row_type=record_type)\n\n\ndef _metric_type(metric: str) -> Any:\n    key = metric.lower()\n    if key == \"cosine\":\n        return _zvec.MetricType.COSINE\n    if key == \"ip\":\n        return _zvec.MetricType.IP","sourceCodeStart":483,"sourceCodeEnd":519,"githubUrl":"https://github.com/cocoindex-io/cocoindex/blob/e84aa99b3292c5270a4b313b2a7137ad9ce8ab3b/python/cocoindex/connectors/zvec/_target.py#L483-L519","documentation":"zvec collections map the primary-key column value to the document id, and zvec requires exactly one such column. from_class() raises ValueError when primary_key is not a sequence of exactly one column name.","triggerScenarios":"Calling from_class(record_type, primary_key=()) with zero names, or primary_key=(\"id\", \"other\") with multiple names.","commonSituations":"Copying config from a connector that supports composite keys (e.g. postgres multi-column keys); passing a string with a comma or a list of candidate key columns.","solutions":["Pass exactly one column name: primary_key=(\"id\",) or primary_key=[\"id\"].","Pick a single unique scalar field as the document id.","If you need a composite id, combine values into one scalar field (e.g. a formatted string) and use that."],"exampleFix":"// before\nRecordTarget.from_class(Doc, primary_key=(\"tenant_id\", \"doc_id\"))\n// after\nRecordTarget.from_class(Doc, primary_key=(\"doc_id\",))","handlingStrategy":"validation","validationCode":"if len(primary_key) != 1:\n    raise ValueError(\"zvec requires exactly one primary key column\")","typeGuard":null,"tryCatchPattern":"try:\n    target = RecordTarget.from_class(Doc, primary_key=primary_key)\nexcept ValueError as e:\n    logging.error(\"bad primary_key: %s\", e)","preventionTips":["Use a single-element tuple like (\"id\",) for primary_key.","Combine composite keys into one scalar string field.","Remember zvec document ids are single-valued."],"tags":["python","primary-key","schema-validation","vector-database"],"backgroundTag":"invalid-argument-value","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"}