|
| 1 | +--- |
| 2 | +mapped_pages: |
| 3 | + - https://www.elastic.co/guide/en/kibana/current/search-sessions.html |
| 4 | +applies_to: |
| 5 | + stack: preview 9.2 |
| 6 | + serverless: unavailable |
| 7 | +products: |
| 8 | + - id: kibana |
| 9 | +description: Send your long-running queries to run in the background with background searches and search sessions, and focus on your other tasks while they complete. |
| 10 | +--- |
| 11 | + |
| 12 | +# Run a search in the background |
| 13 | + |
| 14 | +::::{important} - Background search replaces Search sessions |
| 15 | + |
| 16 | +Background search is a feature introduced in version 9.2. It replaces the deprecated **Search sessions** feature. |
| 17 | +If you have been using search sessions and upgrade to 9.2, your search sessions aren't lost and become background searches. |
| 18 | +:::: |
| 19 | + |
| 20 | +Sometimes you might need to search through large amounts of data, no matter how long the search takes. Consider a threat hunting scenario, where you need to search through years of data. |
| 21 | + |
| 22 | +You can send your long-running searches to the background from **Discover** or **Dashboards** and let them run while you continue your work. |
| 23 | + |
| 24 | +A notification appears when a background search has completed, and lets you open the list of background searches. You can also access that list at any time to check the status of your searches and interact with them from the {icon}`background_task` **Background searches** button in the toolbar. |
| 25 | + |
| 26 | + |
| 27 | + |
| 28 | + |
| 29 | +## Enable background searches |
| 30 | + |
| 31 | +This feature is disabled by default. You can enable background searches in versions 9.2 and higher, or search sessions in versions 9.1 and lower, by setting [`data.search.sessions.enabled`](kibana://reference/configuration-reference/search-sessions-settings.md) to `true` in the [`kibana.yml`](/deploy-manage/stack-settings.md) configuration file. |
| 32 | + |
| 33 | +:::{note} - Exception for search sessions users |
| 34 | +If you are upgrading to version 9.2 or higher and search sessions were already enabled before, background searches are already enabled. |
| 35 | +::: |
| 36 | + |
| 37 | +## Usage requirements [_requirements] |
| 38 | + |
| 39 | +The background searches that you run are personal and only visible by you. To be able to use this feature, you must have the following minimum permissions: |
| 40 | + |
| 41 | +:::::{tab-set} |
| 42 | +:group: background search |
| 43 | + |
| 44 | +::::{tab-item} 9.2 and later |
| 45 | +:sync: 92 |
| 46 | +To send searches to the background, and to view and interact with the list of background searches from **Discover** and **Dashboards** apps, you must have permissions for **Discover** and **Dashboard**, and for the [Background search subfeature](../../deploy-manage/users-roles/cluster-or-deployment-auth/kibana-privileges.md#kibana-feature-privileges). |
| 47 | +:::: |
| 48 | + |
| 49 | +::::{tab-item} 9.1 and earlier |
| 50 | +:sync: 91 |
| 51 | +In versions 9.1 and earlier, this feature is named **Search sessions**. |
| 52 | +* To save a session, you must have permissions for **Discover** and **Dashboard**, and the [Search sessions subfeature](../../deploy-manage/users-roles/cluster-or-deployment-auth/kibana-privileges.md#kibana-feature-privileges). |
| 53 | +* To view and restore a saved session, you must have access to **Stack Management**. |
| 54 | +:::: |
| 55 | + |
| 56 | +::::: |
| 57 | + |
| 58 | +## Send a search to the background |
| 59 | + |
| 60 | +You can send a search to the background only after it starts running. Until then, the **Send to background** button is disabled. |
| 61 | + |
| 62 | +1. Write or edit the query. |
| 63 | + |
| 64 | +1. Select {icon}`play` **Run** (or {icon}`refresh` **Refresh** if you already ran the query at least once) to start executing the query. At this point, the {icon}`background_task` **Send to background** button becomes available. |
| 65 | + |
| 66 | +1. Select this button. The search is sent to the background and added to the queue of background searches. |
| 67 | + |
| 68 | +You can resume your other tasks, for example start a new search, navigate to a different application, or close the browser. Once the search has completed, a notification informs you and lets you access the search to view its results. |
| 69 | + |
| 70 | +Background searches expire after 7 days. Beyond that period, you must run the search again. |
| 71 | + |
| 72 | +## Reopen or manage background searches |
| 73 | + |
| 74 | +From the list of background searches, you can reopen and edit any searches, but also extend their validity period or delete to keep only searches that you care about. |
| 75 | + |
| 76 | +1. Open your list of background searches using one of the following methods: |
| 77 | + - Once a background search has completed, a notification appears to inform you, with a link to open the list of background searches. |
| 78 | + - If you miss the notification or need to access this list at any time, go to **Discover** or **Dashboards** and select the {icon}`background_task` **Background searches** button in the toolbar. This option is only available from version 9.2. |
| 79 | + |
| 80 | + :::{tip} |
| 81 | + From **Discover**, you can only view Discover background searches. And from **Dashboards**, you can only see Dashboards background searches. |
| 82 | + ::: |
| 83 | + - Open the **Background Search** management page in {{kib}}. |
| 84 | + |
| 85 | +1. Find the background search that you want to interact with using the search or status filter options. |
| 86 | + - To open it to view its results and continue your explorations, select its name. Relative dates are converted to absolute dates. |
| 87 | + - To rename it, select the {icon}`boxes_horizontal` More actions button, then select {icon}`pencil` **Edit name**. By default, background searches get default names that indicate their execution date and time. |
| 88 | + - To extend its current expiration date by another 7 days, select the {icon}`boxes_horizontal` More actions button, then select **Extend**. |
| 89 | + - To delete it, select the {icon}`boxes_horizontal` More actions button, then select {icon}`trash` **Delete**. |
| 90 | + |
| 91 | + |
| 92 | +## Background search limitations in dashboards [_limitations] |
| 93 | + |
| 94 | +Some visualization features do not fully support background searches. When you restore a dashboard, panels with unsupported features won’t load immediately, but instead send out additional data requests, which can take a while to complete. The **Your background search is still running** warning appears. You can either wait for these additional requests to complete or come back to the dashboard later when all data requests have finished. |
| 95 | + |
| 96 | +A panel on a dashboard can behave like this if one of the following features is used: |
| 97 | + |
| 98 | +**Lens** |
| 99 | + |
| 100 | +* A **top values** dimension with an enabled **Group other values as "Other"** setting. This is configurable in the **Advanced** section of the dimension. |
| 101 | +* An **intervals** dimension. |
| 102 | + |
| 103 | +**Aggregation-based** visualizations |
| 104 | + |
| 105 | +* A **terms** aggregation with an enabled **Group other values in separate bucket** setting. |
| 106 | +* A **histogram** aggregation. |
| 107 | + |
| 108 | +**Maps** |
| 109 | + |
| 110 | +* Layers using joins, blended layers, or tracks layers. |
0 commit comments