{"record":{"id":"f304d189ccfea093","repo":"spring-projects/spring-ai","slug":"failed-to-delete-documents-by-filter-f304d1","errorCode":null,"errorMessage":"Failed to delete documents by filter","messagePattern":"Failed to delete documents by filter","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"vector-stores/spring-ai-couchbase-store/src/main/java/org/springframework/ai/vectorstore/couchbase/CouchbaseSearchVectorStore.java","lineNumber":170,"sourceCode":"\tpublic void doDelete(List<String> idList) {\n\t\tfor (String id : idList) {\n\t\t\tthis.collection.remove(id);\n\t\t}\n\t}\n\n\t@Override\n\tpublic void doDelete(Filter.Expression filterExpression) {\n\t\tAssert.notNull(filterExpression, \"Filter expression must not be null\");\n\t\ttry {\n\t\t\tString nativeFilter = this.filterExpressionConverter.convertExpression(filterExpression);\n\t\t\tString sql = String.format(\"DELETE FROM %s WHERE %s\", this.collection.name(), nativeFilter);\n\t\t\tthis.scope.query(sql, QueryOptions.queryOptions().metrics(true));\n\t\t}\n\t\tcatch (Exception e) {\n\t\t\tif (logger.isErrorEnabled()) {\n\t\t\t\tlogger.error(\"Failed to delete documents by filter: \" + e.getMessage(), e);\n\t\t\t}\n\t\t\tthrow new IllegalStateException(\"Failed to delete documents by filter\", e);\n\t\t}\n\t}\n\n\t@Override\n\tpublic List<Document> doSimilaritySearch(org.springframework.ai.vectorstore.SearchRequest springAiRequest) {\n\t\tfloat[] embeddings = this.embeddingModel.embed(springAiRequest.getQuery());\n\t\tint topK = springAiRequest.getTopK();\n\n\t\tdouble similarityThreshold = springAiRequest.getSimilarityThreshold();\n\t\tFilter.Expression fe = springAiRequest.getFilterExpression();\n\n\t\tString nativeFilterExpression = (fe != null) ? \" AND \" + this.filterExpressionConverter.convertExpression(fe)\n\t\t\t\t: \"\";\n\t\tString statement = String.format(\n\t\t\t\t\"\"\"\n\t\t\t\t\t\tSELECT c.* FROM `%s` AS c\n\t\t\t\t\t\tWHERE SEARCH_SCORE() > %s AND SEARCH(`c`, {\"query\": {\"match_none\": {}}, \"knn\": [{\"field\": \"embedding\", \"k\": %s, \"vector\": %s }   ]    }, {\"index\": \"%s.%s.%s\"}   )\n\t\t\t\t\t\t%s","sourceCodeStart":152,"sourceCodeEnd":188,"githubUrl":"https://github.com/spring-projects/spring-ai/blob/98a7beda4f29d80a71c5837eb4053b03a93a46f7/vector-stores/spring-ai-couchbase-store/src/main/java/org/springframework/ai/vectorstore/couchbase/CouchbaseSearchVectorStore.java#L152-L188","documentation":"CouchbaseSearchVectorStore.doDelete(Filter.Expression) runs a N1QL DELETE query on the scope and wraps any exception (query syntax error, connectivity failure, index missing, timeouts) in IllegalStateException. It means the filter-based delete did not execute successfully against Couchbase. The original cause is logged and chained.","triggerScenarios":"Calling vectorStore.delete(Filter.Expression) when the Couchbase cluster/scope is unreachable, the search index does not exist, the N1QL statement is invalid, or the query fails with metrics() enabled.","commonSituations":"Wrong connection string/bucket/scope config, Couchbase Query service unavailable, missing primary index for the collection, network/credentials problems, or malformed filter expressions producing invalid N1QL.","solutions":["Check the chained cause and logged error to see the underlying Couchbase failure","Verify bucket/scope/collection names and that the Query service and required indexes exist","Validate cluster connectivity and credentials with a simple query first","Print the generated N1QL filter (ElasticsearchAiSearch-style converter) and test it in the Couchbase query workbench"],"exampleFix":"// before: delete with an unindexed metadata field\ndelete(new Filter.Expression(ExpressionType.EQ, new MetadataKey(\"year\"), new MetadataValue(\"2024\")));\n// after: ensure index exists first\ncluster.query(\"CREATE PRIMARY INDEX IF NOT EXISTS ON `bucket`.`scope`.`collection`\");\ndelete(new Filter.Expression(ExpressionType.EQ, new MetadataKey(\"year\"), new MetadataValue(\"2024\")));","handlingStrategy":"try-catch","validationCode":"boolean queryServiceUp = cluster.query(\"SELECT 1\").rows().all().block() != null;","typeGuard":null,"tryCatchPattern":"try {\n    vectorStore.delete(filterExpression);\n} catch (IllegalStateException e) {\n    logger.error(\"Couchbase filter delete failed: {}\", e.getCause() != null ? e.getCause().getMessage() : e.getMessage(), e);\n    throw e;\n}","preventionTips":["Create primary/secondary indexes before deleting by metadata filters","Validate bucket/scope/collection configuration at startup","Test generated N1QL in the Couchbase query workbench"],"tags":["couchbase","vector-store","delete","n1ql","database"],"backgroundTag":"database-query-failed","analyzedSha":"98a7beda4f29d80a71c5837eb4053b03a93a46f7","analyzedAt":"2026-09-11T14:15:49.441Z","contentChangedAt":"2026-09-11T14:15:49.441Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}