{"record":{"id":"9669a52b479f448b","repo":"cocoindex-io/cocoindex","slug":"dimension-is-required-for-declare-vector-index","errorCode":null,"errorMessage":"dimension is required for declare_vector_index()","messagePattern":"dimension is required for declare_vector_index\\(\\)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/cocoindex/connectors/surrealdb/_target.py","lineNumber":1139,"sourceCode":"            return {f.name: getattr(row, f.name) for f in record_info.fields}\n\n    def declare_vector_index(\n        self: TableTarget[RowT],\n        *,\n        name: str | None = None,\n        field: str,\n        metric: Literal[\"cosine\", \"euclidean\", \"manhattan\"] = \"cosine\",\n        method: Literal[\"mtree\", \"hnsw\"] = \"mtree\",\n        dimension: int | None = None,\n        vector_type: Literal[\"f32\", \"f64\", \"i16\", \"i32\", \"i64\"] = \"f32\",\n    ) -> None:\n        \"\"\"Declare a vector index on this table.\"\"\"\n        _validate_identifier(field, \"vector index field\")\n        if name is None:\n            name = f\"idx_{self._table_name}__{field}\"\n        _validate_identifier(name, \"vector index name\")\n        if dimension is None:\n            raise ValueError(\"dimension is required for declare_vector_index()\")\n        spec = _VectorIndexSpec(\n            field=field,\n            metric=metric,\n            method=method,\n            dimension=dimension,\n            vector_type=vector_type,\n        )\n        att_provider = self._provider.attachment(\"vector_index\")\n        coco.declare_target_state(att_provider.target_state(name, spec))\n\n    def __coco_memo_key__(self) -> str:\n        return self._provider.memo_key\n\n\n# ---------------------------------------------------------------------------\n# RelationTarget\n# ---------------------------------------------------------------------------\n","sourceCodeStart":1121,"sourceCodeEnd":1157,"githubUrl":"https://github.com/cocoindex-io/cocoindex/blob/e84aa99b3292c5270a4b313b2a7137ad9ce8ab3b/python/cocoindex/connectors/surrealdb/_target.py#L1121-L1157","documentation":"A vector index in SurrealDB needs an explicit dimension (vector length) to be created. `declare_vector_index()` raises ValueError when `dimension=None` because there is no default the library could safely infer for arbitrary vector fields.","triggerScenarios":"Calling `table.declare_vector_index(field=..., ...)` without the `dimension` keyword argument, or explicitly passing `dimension=None`.","commonSituations":"Following older documentation or examples where dimension was optional; copying a call for a scalar index and adding a `field` only; assuming the embedding model's dimension is auto-detected.","solutions":["Pass `dimension=<int>` matching your embedding model's output size (e.g. 384 for all-MiniLM-L6-v2, 1536 for text-embedding-3-small).","If the vector comes from a cocoindex Vector schema, read the dimension from the embedding function/model config and pass it through.","Check the method signature: `dimension` is required, not defaulted."],"exampleFix":"// before\nawait table.declare_vector_index(field=\"embedding\", metric=\"cosine\")\n// after\nawait table.declare_vector_index(field=\"embedding\", metric=\"cosine\", dimension=384)","handlingStrategy":"validation","validationCode":"if dimension is None:\n    raise ValueError(\"dimension must be set before declare_vector_index()\")\nassert isinstance(dimension, int) and dimension > 0","typeGuard":"def has_dimension(kwargs: dict) -> bool:\n    d = kwargs.get(\"dimension\")\n    return isinstance(d, int) and d > 0","tryCatchPattern":"try:\n    await table.declare_vector_index(field=\"embedding\", metric=\"cosine\", dimension=dim)\nexcept ValueError as e:\n    if \"dimension is required\" in str(e):\n        raise RuntimeError(\"Embedding dimension not configured\") from e\n    raise","preventionTips":["Derive dimension from your embedding model config and pass it explicitly.","Centralize index creation in one helper that takes dimension as a required parameter.","Validate embedding output length once at startup and reuse it."],"tags":["python","vector-index","surrealdb","config"],"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-17T15:17:12.973Z"}