Add docs for managing stored queries in searchpromotions

and update docs about the search -> searchpromotions migration.

CHANGELOG.txt

@@ -78,6 +78,7 @@ Changelog
  * Docs: Switch the Getting started tutorial’s snippets example to be more understandable (Damilola Oladele)
  * Docs: Update the deployment documentation page and remove outdated information (Jake Howard)
  * Docs: Add more items to performance page regarding pre-fetching images and frontend caching (Jake Howard)
+ * Docs: Add docs for managing stored queries in `searchpromotions` (Scott Foster)
  * Maintenance: Removed support for Python 3.7 (Dan Braghis)
  * Maintenance: Switch to ruff for flake8 / isort code checking (Oliver Parker)
  * Maintenance: Deprecate `insert_editor_css` in favour of `insert_global_admin_css` (Ester Beltrami)

CONTRIBUTORS.md

@@ -721,6 +721,7 @@
 * Sahil Jangra
 * Henry Harutyunyan
 * Alex Morega
+* Scott Foster
 
 ## Translators
 

docs/reference/contrib/searchpromotions.md

@@ -50,3 +50,69 @@ To retrieve a list of promoted search results for a particular search query, you
     {% endfor %}
 </ul>
 ```
+
+### Managing stored search queries
+
+The `searchpromotions` module keeps a log of search queries as well as the number of daily hits through the `Query` and `QueryDailyHits` models.
+
+```{eval-rst}
+.. class:: wagtail.contrib.search_promotions.models.Query
+
+    .. method:: get(query_string)
+        :classmethod:
+
+        Retrieves a stored search query or creates a new one if it doesn't exist.
+
+    .. method:: add_hit(date=None)
+
+        Records another daily hit for a search query by creating a new record or incrementing the number of hits for an existing record. Defaults to using the current date but an optional `date` parameter can be passed in.
+```
+
+#### Example search view
+
+Here's an example Django view for a search page that records a hit for the search query:
+
+```python
+from django.template.response import TemplateResponse
+
+from wagtail.models import Page
+from wagtail.contrib.search_promotions.models import Query
+
+
+def search(request):
+    search_query = request.GET.get("query", None)
+
+    if search_query:
+        search_results = Page.objects.live().search(search_query)
+        query = Query.get(search_query)
+
+        # Record hit
+        query.add_hit()
+    else:
+        search_results = Page.objects.none()
+
+    return TemplateResponse(
+        request,
+        "search/search.html",
+        {
+            "search_query": search_query,
+            "search_results": search_results,
+        },
+    )
+```
+
+## Management Commands
+
+(searchpromotions_garbage_collect)=
+
+### `searchpromotions_garbage_collect`
+
+```sh
+./manage.py searchpromotions_garbage_collect
+```
+
+On high traffic websites, the stored queries and daily hits logs may get large and you may want to clean out old records. This command cleans out all search query logs that are more than one week old (or a number of days configurable through the [`WAGTAILSEARCH_HITS_MAX_AGE`](wagtailsearch_hits_max_age) setting).
+
+```{versionadded} 5.0
+This management command was renamed from `search_garbage_collect`.
+```

docs/reference/management_commands.md

@@ -124,8 +124,6 @@ If this is omitted or provided with any number above 0 it will produce the same
 
 An alias for the `update_index` command that can be used when another installed package (such as [Haystack](https://haystacksearch.org/)) provides a command named `update_index`. In this case, the other package's entry in `INSTALLED_APPS` should appear above `wagtail.search` so that its `update_index` command takes precedence over Wagtail's.
 
-(search_garbage_collect)=
-
 ## rebuild_references_index
 
 ```sh
@@ -156,7 +154,9 @@ Displays a summary of the contents of the references index. This shows the numbe
 ./manage.py search_garbage_collect
 ```
 
-Wagtail keeps a log of search queries that are popular on your website. On high traffic websites, this log may get big and you may want to clean out old search queries. This command cleans out all search query logs that are more than one week old (or a number of days configurable through the [`WAGTAILSEARCH_HITS_MAX_AGE`](wagtailsearch_hits_max_age) setting).
+```{versionchanged} 5.0
+This management command has been renamed to [`searchpromotions_garbage_collect`](searchpromotions_garbage_collect). See the [upgrade consideration](wagtailsearch_query_migration) for more details.
+```
 
 (wagtail_update_image_renditions)=
 

docs/reference/settings.md

@@ -68,7 +68,7 @@ Define a search backend. For a full explanation, see [](wagtailsearch_backends).
 WAGTAILSEARCH_HITS_MAX_AGE = 14
 ```
 
-Set the number of days (default 7) that search query logs are kept for; these are used to identify popular search terms for [promoted search results](editors_picks). Queries older than this will be removed by the [](search_garbage_collect) command.
+Set the number of days (default 7) that search query logs are kept for; these are used to identify popular search terms for [promoted search results](editors_picks). Queries older than this will be removed by the [](searchpromotions_garbage_collect) command.
 
 ## Internationalisation
 

docs/releases/5.0.md

@@ -272,10 +272,12 @@ It is recommended that the `rebuild_references_index` management command is run
 
 The undocumented `Page.get_static_site_paths` method (which returns a generator of URL paths for use by static site generator packages) has been removed. Packages relying on this functionality should provide their own fallback implementation.
 
+(wagtailsearch_query_migration)=
+
 ### `wagtailsearch.Query` has moved to `wagtail.contrib.search_promotions`
 
 The `wagtailsearch.Query` model has been moved from the `search` application to the contrib application `wagtail.contrib.search_promotions`.
-All imports will need to be updated and migrations will need to be run via a custom command, some imports will still work with a warning until a future version.
+All imports will need to be updated and migrations will need to be run via a management command, some imports will still work with a warning until a future version.
 
 #### Migration command
 
@@ -285,6 +287,10 @@ If you have daily hits records in the `wagtailsearch.Query` you can run the mana
 ./manage.py copy_daily_hits_from_wagtailsearch
 ```
 
+#### Managing stored search queries
+
+The `search_garbage_collect` command used to remove old stored search queries and daily hits has been moved to [`searchpromotions_garbage_collect`](searchpromotions_garbage_collect).
+
 #### Import updates
 
 | **Import**    | **Old import**                               | **New import**                                                  |

docs/releases/5.1.md

@@ -134,6 +134,7 @@ This feature was developed by Aman Pandey as part of the Google Summer of Code p
  * Revise main Getting started tutorial for clarity (Kevin Chung (kev-odin))
  * Update the [deployment documentation](deployment_guide) page and remove outdated information (Jake Howard)
  * Add more items to performance page regarding pre-fetching images and frontend caching (Jake Howard)
+ * Add docs for managing stored queries in `searchpromotions` (Scott Foster)
 
 ### Maintenance
 

docs/topics/search/searching.md

@@ -378,7 +378,7 @@ Here's an example Django view that could be used to add a "search" page to your
 from django.shortcuts import render
 
 from wagtail.models import Page
-from wagtail.search.models import Query
+from wagtail.contrib.search_promotions.models import Query
 
 
 def search(request):