{"record":{"id":"92b7df1bb9fe4096","repo":"apache/cassandra","slug":"sai-ann-indexes-are-only-allowed-on-vector-columns","errorCode":null,"errorMessage":"SAI ANN indexes are only allowed on vector columns with float elements","messagePattern":"SAI ANN indexes are only allowed on vector columns with float elements","errorType":"validation","errorClass":"InvalidRequestException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/index/sai/StorageAttachedIndex.java","lineNumber":304,"sourceCode":"\n        // If we are indexing map entries we need to validate the subtypes\n        if (indexTermType.isComposite())\n        {\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));","sourceCodeStart":286,"sourceCodeEnd":322,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/index/sai/StorageAttachedIndex.java#L286-L322","documentation":"SAI vector (ANN) indexes require the vector's element type to be float. When validateOptions sees a vector target whose vectorElementType() is not FloatType, it throws VECTOR_NON_FLOAT_ERROR ('SAI ANN indexes are only allowed on vector columns with float elements').","triggerScenarios":"CREATE CUSTOM INDEX ... USING 'StorageAttachedIndex' with function ANN/option on a vector column declared with a non-float element type (e.g., vector<int, N> or vector<double, N>).","commonSituations":"Creating vector columns with integer embeddings; copying vector schema from other systems using double precision; typo in the vector type declaration.","solutions":["Declare the column as vector<float, N> (float elements) and re-create the index.","Migrate existing data: add a float-typed vector column, copy/convert values, then index it.","Drop and re-create the table with the correct vector type if data volume is small."],"exampleFix":"// before\nembedding vector<int, 128>\n// after\nALTER TABLE ks.tbl ADD embedding_f vector<float, 128>;\nCREATE CUSTOM INDEX ON ks.tbl (embedding_f) USING 'StorageAttachedIndex';","handlingStrategy":"validation","validationCode":"const m = /^vector<\\s*([a-z]+)\\s*,\\s*(\\d+)\\s*>$/.exec(columnType); if (!m || m[1] !== 'float') throw new Error('vector columns must use float elements for SAI ANN');","typeGuard":"function isFloatVector(cqlType) { const m = /^vector<\\s*float\\s*,\\s*\\d+\\s*>$/.exec(cqlType); return m !== null; }","tryCatchPattern":"catch (InvalidRequestException e) { if (e.getMessage().includes('only allowed on vector columns with float elements')) { // migrate column to vector<float,N> and recreate index } }","preventionTips":["Always declare embedding columns as vector<float, N>","Add schema linting to reject non-float vectors for ANN","Standardize embedding pipeline output to float32"],"tags":["cassandra","sai","vector","unsupported-dtype"],"backgroundTag":"unsupported-dtype","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"}