From 7d699ce08745943f29c315bf89b5387839d67989 Mon Sep 17 00:00:00 2001 From: Luna Lucadou Date: Thu, 27 Mar 2025 15:07:34 -0500 Subject: [PATCH 1/2] Add param notes to DSL search.delete documentation, fix broken links The preferred way of passing parameters to the DSL `Search.delete` appears to be calling `Search.params` first, but this is only ever discussed in GitHub issues like elastic/elasticsearch-dsl-py#1115 and elastic/elasticsearch-dsl-py#1395. To help anyone else who has stumbled across this, I added a note about this to the documentation. I also went ahead and updated the links for the `Search.scan` and `FacetedSearch.params` methods to the most recent versions since they were 404ing. --- docs/reference/dsl_how_to_guides.md | 9 +++++++++ elasticsearch/dsl/_async/search.py | 10 +++++++--- elasticsearch/dsl/_sync/search.py | 10 +++++++--- elasticsearch/dsl/faceted_search_base.py | 2 +- 4 files changed, 24 insertions(+), 7 deletions(-) diff --git a/docs/reference/dsl_how_to_guides.md b/docs/reference/dsl_how_to_guides.md index 08e16b28c..bc3328fd5 100644 --- a/docs/reference/dsl_how_to_guides.md +++ b/docs/reference/dsl_how_to_guides.md @@ -84,6 +84,15 @@ s = Search(index='i').query("match", title="python") response = s.delete() ``` +To pass [deletion parameters](https://elasticsearch-py.readthedocs.io/en/latest/api/elasticsearch.html#elasticsearch.Elasticsearch.delete_by_query) +in your query, you can add them by calling ``params`` on the ``Search`` object before ``delete`` like this: + +```python +s = Search(index='i').query("match", title="python") +s = s.params(ignore_unavailable=False, wait_for_completion=True) +response = s.delete() +``` + #### Queries [_queries] diff --git a/elasticsearch/dsl/_async/search.py b/elasticsearch/dsl/_async/search.py index 42eb142fd..bafbfcb39 100644 --- a/elasticsearch/dsl/_async/search.py +++ b/elasticsearch/dsl/_async/search.py @@ -107,9 +107,9 @@ async def scan(self) -> AsyncIterator[_R]: Turn the search into a scan search and return a generator that will iterate over all the documents matching the query. - Use ``params`` method to specify any additional arguments you with to + Use the ``params`` method to specify any additional arguments you wish to pass to the underlying ``scan`` helper from ``elasticsearch-py`` - - https://elasticsearch-py.readthedocs.io/en/master/helpers.html#elasticsearch.helpers.scan + https://elasticsearch-py.readthedocs.io/en/latest/helpers.html#scan The ``iterate()`` method should be preferred, as it provides similar functionality using an Elasticsearch point in time. @@ -123,7 +123,11 @@ async def scan(self) -> AsyncIterator[_R]: async def delete(self) -> AttrDict[Any]: """ - delete() executes the query by delegating to delete_by_query() + ``delete()`` executes the query by delegating to ``delete_by_query()``. + + Use the ``params`` method to specify any additional arguments you wish to + pass to the underlying ``delete_by_query`` helper from ``elasticsearch-py`` - + https://elasticsearch-py.readthedocs.io/en/latest/async.html#elasticsearch.AsyncElasticsearch.delete_by_query """ es = get_connection(self._using) diff --git a/elasticsearch/dsl/_sync/search.py b/elasticsearch/dsl/_sync/search.py index ae826a12f..4dfbdb92b 100644 --- a/elasticsearch/dsl/_sync/search.py +++ b/elasticsearch/dsl/_sync/search.py @@ -104,9 +104,9 @@ def scan(self) -> Iterator[_R]: Turn the search into a scan search and return a generator that will iterate over all the documents matching the query. - Use ``params`` method to specify any additional arguments you with to + Use the ``params`` method to specify any additional arguments you wish to pass to the underlying ``scan`` helper from ``elasticsearch-py`` - - https://elasticsearch-py.readthedocs.io/en/master/helpers.html#elasticsearch.helpers.scan + https://elasticsearch-py.readthedocs.io/en/latest/helpers.html#scan The ``iterate()`` method should be preferred, as it provides similar functionality using an Elasticsearch point in time. @@ -118,7 +118,11 @@ def scan(self) -> Iterator[_R]: def delete(self) -> AttrDict[Any]: """ - delete() executes the query by delegating to delete_by_query() + ``delete()`` executes the query by delegating to ``delete_by_query()``. + + Use the ``params`` method to specify any additional arguments you wish to + pass to the underlying ``delete_by_query`` helper from ``elasticsearch-py`` - + https://elasticsearch-py.readthedocs.io/en/latest/api/elasticsearch.html#elasticsearch.Elasticsearch.delete_by_query """ es = get_connection(self._using) diff --git a/elasticsearch/dsl/faceted_search_base.py b/elasticsearch/dsl/faceted_search_base.py index 5caa041bf..b58f23dca 100644 --- a/elasticsearch/dsl/faceted_search_base.py +++ b/elasticsearch/dsl/faceted_search_base.py @@ -469,7 +469,7 @@ def params(self, **kwargs: Any) -> None: """ Specify query params to be used when executing the search. All the keyword arguments will override the current values. See - https://elasticsearch-py.readthedocs.io/en/master/api.html#elasticsearch.Elasticsearch.search + https://elasticsearch-py.readthedocs.io/en/latest/api/elasticsearch.html#elasticsearch.Elasticsearch.search for all available parameters. """ self._s = self._s.params(**kwargs) From 550a44fc83450bbec8cf1545ef7dd7582933f56e Mon Sep 17 00:00:00 2001 From: Miguel Grinberg Date: Mon, 31 Mar 2025 10:16:31 +0100 Subject: [PATCH 2/2] make sync and async changes the same --- elasticsearch/dsl/_async/search.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/elasticsearch/dsl/_async/search.py b/elasticsearch/dsl/_async/search.py index bafbfcb39..2ea277a07 100644 --- a/elasticsearch/dsl/_async/search.py +++ b/elasticsearch/dsl/_async/search.py @@ -127,7 +127,7 @@ async def delete(self) -> AttrDict[Any]: Use the ``params`` method to specify any additional arguments you wish to pass to the underlying ``delete_by_query`` helper from ``elasticsearch-py`` - - https://elasticsearch-py.readthedocs.io/en/latest/async.html#elasticsearch.AsyncElasticsearch.delete_by_query + https://elasticsearch-py.readthedocs.io/en/latest/api/elasticsearch.html#elasticsearch.Elasticsearch.delete_by_query """ es = get_connection(self._using)