{"record":{"id":"6bd36c4734111034","repo":"apache/cassandra","slug":"cosine-similarity-is-not-supported-for-single-dime","errorCode":null,"errorMessage":"Cosine similarity is not supported for single-dimension vectors","messagePattern":"Cosine similarity is not supported for single-dimension vectors","errorType":"validation","errorClass":"InvalidRequestException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/index/sai/StorageAttachedIndex.java","lineNumber":307,"sourceCode":"        {\n            for (IndexTermType subType : indexTermType.subTypes())\n            {\n                if (!SUPPORTED_TYPES.contains(subType.asCQL3Type()) && !subType.isFrozen())\n                    throw new InvalidRequestException(\"Unsupported type: \" + subType.asCQL3Type());\n            }\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","sourceCodeStart":289,"sourceCodeEnd":325,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/index/sai/StorageAttachedIndex.java#L289-L325","documentation":"Cosine similarity is mathematically undefined for a 1-dimensional vector (norm-based angles do not apply). SAI's validateOptions rejects ANN indexes on vector<float,1> columns when the configured similarity function is COSINE, throwing VECTOR_1_DIMENSION_COSINE_ERROR.","triggerScenarios":"CREATE CUSTOM INDEX on a vector<float, 1> column with OPTIONS {'similarity_function': 'COSINE'} (COSINE is also the default similarity in some paths, so even omitting the option can trigger it).","commonSituations":"Single-dimensional vector columns used as scalar embeddings; schema generated with dimension 1 by mistake; default similarity function left at COSINE.","solutions":["Change the similarity function to EUCLIDEAN or DOT_PRODUCT in the index options.","If the data is truly multi-dimensional, fix the column's declared dimension to match the real embeddings.","Use a non-ANN index/query strategy if 1-dimensional similarity search is required."],"exampleFix":"// before\nWITH OPTIONS = {'similarity_function': 'COSINE'}  -- on vector<float, 1>\n// after\nWITH OPTIONS = {'similarity_function': 'EUCLIDEAN'}","handlingStrategy":"validation","validationCode":"if (vectorDimension === 1 && (options.similarity_function || 'COSINE') === 'COSINE') throw new Error('cosine is not valid for 1-d vectors; use EUCLIDEAN or DOT_PRODUCT');","typeGuard":null,"tryCatchPattern":"catch (InvalidRequestException e) { if (e.getMessage().includes('single-dimension vectors')) { // retry with EUCLIDEAN similarity } }","preventionTips":["Set similarity_function explicitly instead of relying on defaults","Do not create 1-dimensional vector columns for ANN search","Validate dimension >= 2 when using cosine similarity"],"tags":["cassandra","sai","vector","similarity-function"],"backgroundTag":"invalid-argument-value","analyzedSha":"88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1","analyzedAt":"2026-09-10T07:29:22.284Z","contentChangedAt":"2026-09-10T07:29:22.284Z","schemaVersion":2},"datasetVersion":"2026-09-14T21:17:11.552Z"}