diff --git a/docs/topics/search/searching.rst b/docs/topics/search/searching.rst index 4fd763e52..e606d40ab 100644 --- a/docs/topics/search/searching.rst +++ b/docs/topics/search/searching.rst @@ -85,6 +85,49 @@ This can be limited to a certian set of fields using the ``fields`` keyword argu [, ] +Changing search behaviour +------------------------- + +Search operator +^^^^^^^^^^^^^^^ + +.. versionadded:: 1.2 + +The search operator specifies how search should behave when the user has typed in multiple search terms. There are two possible values: + + - "or" - The results must match at least one term (default for Elasticsearch) + - "and" - The results must match all terms (default for database search) + +Both operators have benefits and drawbacks. The "or" operator will return many more results but will likely contain a lot of results that aren't relevent. The "and" operator only returns results that contain all search terms, but require the user to be more precise with their query. + +We recommend using the "or" operator when ordering by relevance and the "and" operator when ordering by anything else (note: the database backend doesn't currently support ordering by relevance). + +Here's an example of using the "operator" keyword argument: + +.. code-block:: python + + # The database contains a "Thing" model with the following items: + # - Hello world + # - Hello + # - World + + + # Search with the "or" operator + >>> s = get_search_backend() + >>> s.search("Hello world", Things, operator="or") + + # All records returned as they all contain either "hello" or "world" + [, , ] + + + # Search with the "and" operator + >>> s = get_search_backend() + >>> s.search("Hello world", Things, operator="and") + + # Only "hello world" returned as that's the only item that contains both terms + [] + + .. _wagtailsearch_frontend_views: