|
| 1 | +--- |
| 2 | +navigation_title: "Run queries in the background" |
| 3 | +mapped_pages: |
| 4 | + - https://www.elastic.co/guide/en/kibana/current/search-sessions.html |
| 5 | +applies_to: |
| 6 | + stack: preview 9.2 |
| 7 | + serverless: unavailable |
| 8 | +products: |
| 9 | + - id: kibana |
| 10 | +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. |
| 11 | +--- |
| 12 | + |
| 13 | +# Run Discover and Dashboards queries in the background |
| 14 | + |
| 15 | +::::{important} - Background search replaces Search sessions |
| 16 | + |
| 17 | +Background search is a feature introduced in version 9.2. It replaces the deprecated **Search sessions** feature. |
| 18 | +If you have been using search sessions and upgrade to 9.2, your search sessions aren't lost and become background searches. |
| 19 | +:::: |
| 20 | + |
| 21 | +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. |
| 22 | + |
| 23 | +You can send your long-running searches to the background from **Discover** or **Dashboards** and let them run while you continue your work. |
| 24 | + |
| 25 | +You can access your list of background searches at any time to check their status and manage them from the {icon}`background_task` **Background searches** button in the toolbar. |
| 26 | + |
| 27 | + |
| 28 | + |
| 29 | + |
| 30 | +## Enable background searches |
| 31 | + |
| 32 | +This feature is disabled by default. You can enable background searches in versions 9.2 and later, or search sessions in versions 9.1 and earlier, 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. |
| 33 | + |
| 34 | +:::{note} - Exception for search sessions users |
| 35 | +If you upgrade to version 9.2 or later with search sessions enabled in the version you upgrade from, background searches are automatically enabled. |
| 36 | +::: |
| 37 | + |
| 38 | +## Usage requirements [_requirements] |
| 39 | + |
| 40 | +The background searches that you run are personal and only visible by you. To use this feature, you must have the following minimum permissions: |
| 41 | + |
| 42 | +:::::{tab-set} |
| 43 | +:group: background search |
| 44 | + |
| 45 | +::::{tab-item} 9.2 and later |
| 46 | +:sync: 92 |
| 47 | +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). |
| 48 | +:::: |
| 49 | + |
| 50 | +::::{tab-item} 9.1 and earlier |
| 51 | +:sync: 91 |
| 52 | +In versions 9.1 and earlier, this feature is named **Search sessions**. |
| 53 | +* 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). |
| 54 | +* To view and restore a saved session, you must have access to **Stack Management**. |
| 55 | +:::: |
| 56 | + |
| 57 | +::::: |
| 58 | + |
| 59 | +## Send a search to the background |
| 60 | + |
| 61 | +You can send a search to the background only after it starts running. Until then, the **Send to background** button is disabled. |
| 62 | + |
| 63 | +1. Write or edit the query. |
| 64 | + |
| 65 | +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. |
| 66 | + |
| 67 | +1. Select {icon}`background_task` **Send to background**. The search is sent to the background and added to the queue of background searches. |
| 68 | + |
| 69 | +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. |
| 70 | + |
| 71 | +Background searches expire after 7 days. Beyond that period, you must run the search again. You can change this default value by editing the [`data.search.sessions.defaultExpiration`](kibana://reference/configuration-reference/search-sessions-settings.md) setting. |
| 72 | + |
| 73 | +## Reopen or manage background searches |
| 74 | + |
| 75 | +From the list of background searches, you can reopen and edit any searches, but also extend their validity period or delete them to keep only searches that you care about. |
| 76 | + |
| 77 | +1. Open your list of background searches using one of the following methods: |
| 78 | + - Once a background search is sent to the background, a notification appears to inform you, with a link to open the list of background searches. |
| 79 | + - 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. |
| 80 | + |
| 81 | + :::{tip} |
| 82 | + From **Discover**, you can only view Discover background searches. And from **Dashboards**, you can only see Dashboards background searches. |
| 83 | + ::: |
| 84 | + - Open the **Background Search** management page in {{kib}}. |
| 85 | + |
| 86 | +1. Find the background search that you want to interact with using the search or status filter options. |
| 87 | + - To open it to view its results and continue your explorations, select its name. Relative dates are converted to absolute dates. |
| 88 | + - 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. |
| 89 | + - To extend its current expiration date by another 7 days, select the {icon}`boxes_horizontal` More actions button, then select **Extend**. |
| 90 | + - To delete it, select the {icon}`boxes_horizontal` More actions button, then select {icon}`trash` **Delete**. |
| 91 | + |
| 92 | + |
| 93 | +## Background search limitations in dashboards [_limitations] |
| 94 | + |
| 95 | +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. |
| 96 | + |
| 97 | +A panel on a dashboard can behave like this if one of the following features is used: |
| 98 | + |
| 99 | +**Lens** |
| 100 | + |
| 101 | +* A **top values** dimension with an enabled **Group other values as "Other"** setting. This is configurable in the **Advanced** section of the dimension. |
| 102 | +* An **intervals** dimension. |
| 103 | + |
| 104 | +**Aggregation-based** visualizations |
| 105 | + |
| 106 | +* A **terms** aggregation with an enabled **Group other values in separate bucket** setting. |
| 107 | +* A **histogram** aggregation. |
| 108 | + |
| 109 | +**Maps** |
| 110 | + |
| 111 | +* Layers using joins, blended layers, or tracks layers. |
0 commit comments