{"record":{"id":"5b4c819ece46a453","repo":"spring-projects/spring-ai","slug":"failed-to-delete-documents-by-filter-5b4c81","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-elasticsearch-store/src/main/java/org/springframework/ai/vectorstore/elasticsearch/ElasticsearchVectorStore.java","lineNumber":234,"sourceCode":"\t@Override\n\tpublic void doDelete(List<String> idList) {\n\t\tBulkRequest.Builder bulkRequestBuilder = new BulkRequest.Builder();\n\t\tfor (String id : idList) {\n\t\t\tbulkRequestBuilder.operations(op -> op.delete(idx -> idx.index(this.options.getIndexName()).id(id)));\n\t\t}\n\t\tif (bulkRequest(bulkRequestBuilder.build()).errors()) {\n\t\t\tthrow new IllegalStateException(\"Delete operation failed\");\n\t\t}\n\t}\n\n\t@Override\n\tpublic void doDelete(Filter.Expression filterExpression) {\n\t\ttry {\n\t\t\tthis.elasticsearchClient.deleteByQuery(d -> d.index(this.options.getIndexName())\n\t\t\t\t.query(q -> q.queryString(qs -> qs.query(getElasticsearchQueryString(filterExpression)))));\n\t\t}\n\t\tcatch (Exception e) {\n\t\t\tthrow new IllegalStateException(\"Failed to delete documents by filter\", e);\n\t\t}\n\t}\n\n\tprivate BulkResponse bulkRequest(BulkRequest bulkRequest) {\n\t\ttry {\n\t\t\treturn this.elasticsearchClient.bulk(bulkRequest);\n\t\t}\n\t\tcatch (IOException e) {\n\t\t\tthrow new RuntimeException(e);\n\t\t}\n\t}\n\n\t@Override\n\tpublic List<Document> doSimilaritySearch(SearchRequest searchRequest) {\n\t\tAssert.notNull(searchRequest, \"The search request must not be null.\");\n\t\ttry {\n\t\t\tfloat threshold = (float) searchRequest.getSimilarityThreshold();\n\t\t\t// reverting l2_norm distance to its original value","sourceCodeStart":216,"sourceCodeEnd":252,"githubUrl":"https://github.com/spring-projects/spring-ai/blob/98a7beda4f29d80a71c5837eb4053b03a93a46f7/vector-stores/spring-ai-elasticsearch-store/src/main/java/org/springframework/ai/vectorstore/elasticsearch/ElasticsearchVectorStore.java#L216-L252","documentation":"ElasticsearchVectorStore.doDelete(Filter.Expression) runs a delete_by_query with a query_string built from the filter; any Exception from the Elasticsearch client is wrapped in IllegalStateException(\"Failed to delete documents by filter\", e). It means the delete-by-query request could not be executed (bad query syntax, connectivity, index problems).","triggerScenarios":"Calling vectorStore.delete(Filter.Expression) when the generated query_string is invalid for the index mapping, the index does not exist, or the Elasticsearch client call throws (IO/timeout/auth errors).","commonSituations":"Filtering on metadata fields not present in the mapping, special characters in filter values breaking query_string syntax, index name misconfigured, cluster unreachable or secured.","solutions":["Inspect the chained cause for the concrete Elasticsearch error","Test the converter output (getElasticsearchQueryString) manually against the index in Kibana","Verify the index exists (initializeSchema=true or pre-create it) and metadata fields are mapped","Escape/validate filter values that contain Lucene query_string special characters"],"exampleFix":"// before: unescaped value breaks query_string\nnew MetadataValue(\"status:active AND level\");\n// after: avoid reserved Lucene chars in metadata values\nnew MetadataValue(\"status_active_and_level\");","handlingStrategy":"try-catch","validationCode":"String qs = store.getElasticsearchQueryString(filterExpression); // test-print before executing\nassert !qs.contains(\":\") || qs.chars().filter(c -> c == ':').count() <= 1;","typeGuard":null,"tryCatchPattern":"try {\n    vectorStore.delete(filterExpression);\n} catch (IllegalStateException e) {\n    logger.error(\"delete_by_query failed for query [{}]\", e.getCause() != null ? e.getCause().getMessage() : \"\", e);\n    throw e;\n}","preventionTips":["Escape Lucene query_string special characters in metadata values","Ensure metadata fields are mapped in the index","Verify delete_by_query manually in Kibana Dev Tools first"],"tags":["elasticsearch","vector-store","delete-by-query","filter"],"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-14T11:17:12.474Z"}