{"record":{"id":"85143fd402345cb7","repo":"apache/cassandra","slug":"clientwarn-instance-warn-vector-usage-warning","errorCode":null,"errorMessage":"ClientWarn.instance.warn(VECTOR_USAGE_WARNING)","messagePattern":"ClientWarn\\.instance\\.warn\\(VECTOR_USAGE_WARNING\\)","errorType":"validation","errorClass":"ClientWarn","httpStatus":null,"severity":"info","filePath":"src/java/org/apache/cassandra/index/sai/StorageAttachedIndex.java","lineNumber":312,"sourceCode":"            }\n        }\n        else if (!SUPPORTED_TYPES.contains(indexTermType.asCQL3Type()) && !indexTermType.isFrozen())\n        {\n            throw new InvalidRequestException(\"Unsupported type: \" + indexTermType.asCQL3Type());\n        }\n        // If this is a vector type we need to validate it for the current vector index constraints\n        else if (indexTermType.isVector())\n        {\n            if (!(indexTermType.vectorElementType() instanceof FloatType))\n                throw new InvalidRequestException(VECTOR_NON_FLOAT_ERROR);\n\n            if (indexTermType.vectorDimension() == 1 && config.getSimilarityFunction() == VectorSimilarityFunction.COSINE)\n                throw new InvalidRequestException(VECTOR_1_DIMENSION_COSINE_ERROR);\n\n            if (DatabaseDescriptor.getRawConfig().data_file_directories.length > 1)\n                throw new InvalidRequestException(VECTOR_MULTIPLE_DATA_DIRECTORY_ERROR);\n\n            ClientWarn.instance.warn(VECTOR_USAGE_WARNING);\n        }\n\n        return Collections.emptyMap();\n    }\n\n    @Override\n    public void register(IndexRegistry registry)\n    {\n        // index will be available for writes\n        registry.registerIndex(this, StorageAttachedIndexGroup.GROUP_KEY, () -> new StorageAttachedIndexGroup(baseCfs));\n    }\n\n    @Override\n    public void unregister(IndexRegistry registry)\n    {\n        registry.unregisterIndex(this, StorageAttachedIndexGroup.GROUP_KEY);\n    }\n","sourceCodeStart":294,"sourceCodeEnd":330,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/index/sai/StorageAttachedIndex.java#L294-L330","documentation":"This is a ClientWarn warning issued during CREATE INDEX option validation for a vector index: after validating the similarity function and dimensions, SAI warns the client that vector index support has constraints (e.g. limited when multiple data directories are configured — a hard error above — and other caveats surfaced in VECTOR_USAGE_WARNING). It is informational feedback returned to CQL clients, not an exception.","triggerScenarios":"Executing CREATE CUSTOM INDEX ... USING 'StorageAttachedIndex' with a vector column and options that pass validation but merit a caution (dimension > 1, allowed similarity function), while the config passes the multiple-data-directory check.","commonSituations":"Creating vector search indexes in clusters spanning multiple data directories or on versions where SAI vector support is still restricted; developers evaluating ANN search on early Cassandra releases.","solutions":["Read the VECTOR_USAGE_WARNING text returned to the cqlsh/driver client and follow its guidance.","If planning multi-data-directory deployments, reconsider — multiple data_file_directories with vector indexes raises InvalidRequestException (VECTOR_MULTIPLE_DATA_DIRECTORY_ERROR).","Avoid COSINE similarity with 1-dimension vectors (rejected outright); pick dot_product or euclidean instead.","Pin to a Cassandra version where SAI vector indexes meet your production requirements."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// validate options before CREATE INDEX\n// conf: data_file_directories must be a single directory for vector indexes\n// dimension must be > 1 when using COSINE similarity","typeGuard":null,"tryCatchPattern":"try { session.execute(createVectorIndexCql); } catch (InvalidRequestException e) { // handle VECTOR_MULTIPLE_DATA_DIRECTORY_ERROR / VECTOR_1_DIMENSION_COSINE_ERROR\n logger.warn(e.getMessage()); }","preventionTips":["Configure exactly one data_file_directories entry when using SAI vector indexes.","Never use COSINE similarity with 1-dimension vectors.","Review vector support caveats of your Cassandra version before production use.","Surface client warnings in your driver instead of discarding them."],"tags":["sai","vector-index","client-warning","cql"],"backgroundTag":"deprecated-api-usage","analyzedSha":"88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1","analyzedAt":"2026-09-10T07:29:22.284Z","contentChangedAt":"2026-09-10T07:29:22.284Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}