diff --git a/CHANGELOG.txt b/CHANGELOG.txt index 97b79a6692..9b343be169 100644 --- a/CHANGELOG.txt +++ b/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) diff --git a/CONTRIBUTORS.md b/CONTRIBUTORS.md index 6e2ef0f08d..4cadd6a752 100644 --- a/CONTRIBUTORS.md +++ b/CONTRIBUTORS.md @@ -721,6 +721,7 @@ * Sahil Jangra * Henry Harutyunyan * Alex Morega +* Scott Foster ## Translators diff --git a/docs/reference/contrib/searchpromotions.md b/docs/reference/contrib/searchpromotions.md index 7116a70b6b..ca8313e74b 100644 --- a/docs/reference/contrib/searchpromotions.md +++ b/docs/reference/contrib/searchpromotions.md @@ -50,3 +50,69 @@ To retrieve a list of promoted search results for a particular search query, you {% endfor %} ``` + +### 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`. +``` diff --git a/docs/reference/management_commands.md b/docs/reference/management_commands.md index cd419760d5..5ddfd9709c 100644 --- a/docs/reference/management_commands.md +++ b/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)= diff --git a/docs/reference/settings.md b/docs/reference/settings.md index 3f0b25c1c9..03f18f8ecb 100644 --- a/docs/reference/settings.md +++ b/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 diff --git a/docs/releases/5.0.md b/docs/releases/5.0.md index 9896454fbe..2ef4f01bc2 100644 --- a/docs/releases/5.0.md +++ b/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** | diff --git a/docs/releases/5.1.md b/docs/releases/5.1.md index ae86a0b4a6..352e390153 100644 --- a/docs/releases/5.1.md +++ b/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 diff --git a/docs/topics/search/searching.md b/docs/topics/search/searching.md index a3b7d57f78..13aeb75daf 100644 --- a/docs/topics/search/searching.md +++ b/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):