Core: deprecate delete-by-query

This API is trappy: it secretly does a refresh, which can quickly
cause too many segments / OOME if you are also concurrently indexing,
and it might delete different documents between primary and replica.

It will be removed in 2.0.

It's better to do a scan/scroll request with the query, gather the
matching ids, and issue a bulk request to delete them.

Closes #10083

docs/java-api/delete-by-query.asciidoc

@@ -1,6 +1,8 @@
 [[delete-by-query]]
 == Delete By Query API
 
+deprecated[1.5.0, "Delete by Query will be removed in 2.0: it is problematic since it silently forces a refresh which can quickly cause OutOfMemoryError during concurrent indexing, and can also cause primary and replica to become inconsistent.  Instead, use the <<search-request-scroll,scroll/scan API>> to find all matching ids and then issue a bulk request to delete them.]
+
 The delete by query API allows one to delete documents from one or more
 indices and one or more types based on a <<query-dsl-queries,query>>. Here
 is an example:

docs/reference/docs/delete-by-query.asciidoc

@@ -1,6 +1,8 @@
 [[docs-delete-by-query]]
 == Delete By Query API
 
+deprecated[1.5.0, "Delete by Query will be removed in 2.0: it is problematic since it silently forces a refresh which can quickly cause OutOfMemoryError during concurrent indexing, and can also cause primary and replica to become inconsistent.  Instead, use the <<search-request-scroll,scroll/scan API>> to find all matching ids and then issue a bulk request to delete them.]
+
 The delete by query API allows to delete documents from one or more
 indices and one or more types based on a query. The query can either be
 provided using a simple query string as a parameter, or using the