{"record":{"id":"309302761c267283","repo":"cocoindex-io/cocoindex","slug":"vec0-virtual-tables-require-exactly-one-primary-ke","errorCode":null,"errorMessage":"vec0 virtual tables require exactly one primary key column, got {len(table_schema.primary_key)}: {table_schema.primary_key}","messagePattern":"vec0 virtual tables require exactly one primary key column, got (.+?): (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/cocoindex/connectors/sqlite/_target.py","lineNumber":1147,"sourceCode":"            \"sqlite-vec extension must be loaded for vec0 virtual tables. \"\n            \"Use connect(..., load_vec=True)\"\n        )\n    has_vector_col = any(\n        col_def.type.startswith(\"float[\") for col_def in table_schema.columns.values()\n    )\n    if not has_vector_col:\n        raise ValueError(\n            \"vec0 virtual tables require at least one float[N] vector column\"\n        )\n    all_cols = set(table_schema.columns.keys())\n    invalid_partition = set(virtual_table_def.partition_key_columns) - all_cols\n    if invalid_partition:\n        raise ValueError(f\"Partition key columns not in schema: {invalid_partition}\")\n    invalid_aux = set(virtual_table_def.auxiliary_columns) - all_cols\n    if invalid_aux:\n        raise ValueError(f\"Auxiliary columns not in schema: {invalid_aux}\")\n    if len(table_schema.primary_key) != 1:\n        raise ValueError(\n            f\"vec0 virtual tables require exactly one primary key column, \"\n            f\"got {len(table_schema.primary_key)}: {table_schema.primary_key}\"\n        )\n    pk_col_name = table_schema.primary_key[0]\n    pk_col_type = table_schema.columns[pk_col_name].type\n    if pk_col_type != \"INTEGER\":\n        raise ValueError(\n            f\"vec0 virtual tables require INTEGER primary key, \"\n            f\"got {pk_col_type} for column '{pk_col_name}'\"\n        )\n\n\ndef table_target(\n    db: ContextKey[ManagedConnection],\n    table_name: str,\n    table_schema: TableSchema[RowT],\n    *,\n    managed_by: target.ManagedBy = target.ManagedBy.SYSTEM,","sourceCodeStart":1129,"sourceCodeEnd":1165,"githubUrl":"https://github.com/cocoindex-io/cocoindex/blob/e84aa99b3292c5270a4b313b2a7137ad9ce8ab3b/python/cocoindex/connectors/sqlite/_target.py#L1129-L1165","documentation":"sqlite-vec vec0 virtual tables require exactly one primary key column. The provided table schema declares zero or multiple primary key columns, so CocoIndex rejects the configuration before creating the table.","triggerScenarios":"Calling table_target() for a vec0 table where table_schema.primary_key has length != 1 (composite PK like [\"id\", \"ts\"], or no PK at all).","commonSituations":"Defining a composite primary key as in normal SQLite/Postgres tables, then reusing the schema for a vec0 table; forgetting to mark any column as primary key when building the schema manually.","solutions":["Change the schema so exactly one column is the primary key.","Move extra key columns to regular columns or partition key columns instead.","If no PK was intended, explicitly mark one existing column (e.g. an INTEGER id) as primary key."],"exampleFix":"// before\nschema = table_schema(primary_key=[\"id\", \"doc_id\"])\n// after\nschema = table_schema(primary_key=[\"id\"], columns=[\"id\", \"doc_id\", \"embedding\"])","handlingStrategy":"validation","validationCode":"if len(schema.primary_key) != 1:\n    raise ValueError(\"vec0 tables need exactly one primary key column\")","typeGuard":"def has_single_pk(schema) -> bool:\n    return len(schema.primary_key) == 1","tryCatchPattern":"try:\n    target = table_target(schema, virtual_table_def)\nexcept ValueError as e:\n    if \"exactly one primary key\" in str(e):\n        schema = replace_primary_key(schema, [\"id\"])\n        ...","preventionTips":["Never use composite primary keys with vec0 tables; use one INTEGER PK plus indexed regular columns.","Check primary_key length when reusing shared schema builders.","Document the single-PK constraint in table definition helpers."],"tags":["sqlite","vec0","primary-key","schema-validation"],"backgroundTag":"schema-validation-failed","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"}