|
1 | 1 | # data |
2 | 2 |
|
3 | | -`data` plugin provides common data access services. |
| 3 | +The data plugin provides common data access services, such as `search` and `query`, for solutions and application developers. |
4 | 4 |
|
5 | | -- `expressions` — run pipeline functions and render results. |
6 | | -- `filter` |
7 | | -- `index_patterns` |
8 | | -- `query` |
9 | | -- `search`: Elasticsearch API service and strategies |
| 5 | +## Autocomplete |
| 6 | + |
| 7 | +The autocomplete service provides suggestions for field names and values. |
| 8 | + |
| 9 | +It is wired into the `TopNavMenu` component, but can be used independently. |
| 10 | + |
| 11 | +### Fetch Query Suggestions |
| 12 | + |
| 13 | +The `getQuerySuggestions` function helps to construct a query. |
| 14 | +KQL suggestion functions are registered in X-Pack, so this API does not return results in OSS. |
| 15 | + |
| 16 | +```.ts |
| 17 | + |
| 18 | + // `inputValue` is the user input |
| 19 | + const querySuggestions = await autocomplete.getQuerySuggestions({ |
| 20 | + language: 'kuery', |
| 21 | + indexPatterns: [indexPattern], |
| 22 | + query: inputValue, |
| 23 | + }); |
| 24 | + |
| 25 | +``` |
| 26 | + |
| 27 | +### Fetch Value Suggestions |
| 28 | + |
| 29 | +The `getValueSuggestions` function returns suggestions for field values. |
| 30 | +This is helpful when you want to provide a user with options, for example when constructing a filter. |
| 31 | + |
| 32 | +```.ts |
| 33 | + |
| 34 | + // `inputValue` is the user input |
| 35 | + const valueSuggestions = await autocomplete.getValueSuggestions({ |
| 36 | + indexPattern, |
| 37 | + field, |
| 38 | + query: inputValue, |
| 39 | + }); |
| 40 | + |
| 41 | +``` |
| 42 | + |
| 43 | +## Field Formats |
| 44 | + |
| 45 | +Coming soon. |
| 46 | + |
| 47 | +## Index Patterns |
| 48 | + |
| 49 | +Coming soon. |
| 50 | + |
| 51 | +## Query |
| 52 | + |
| 53 | +The query service is responsible for managing the configuration of a search query (`QueryState`): filters, time range, query string, and settings such as the auto refresh behavior and saved queries. |
| 54 | + |
| 55 | +It contains sub-services for each of those configurations: |
| 56 | + - `data.query.filterManager` - Manages the `filters` component of a `QueryState`. The global filter state (filters that are persisted between applications) are owned by this service. |
| 57 | + - `data.query.timefilter` - Responsible for the time range filter and the auto refresh behavior settings. |
| 58 | + - `data.query.queryString` - Responsible for the query string and query language settings. |
| 59 | + - `data.query.savedQueries` - Responsible for persisting a `QueryState` into a `SavedObject`, so it can be restored and used by other applications. |
| 60 | + |
| 61 | + Any changes to the `QueryState` are published on the `data.query.state$`, which is useful when wanting to persist global state or run a search upon data changes. |
| 62 | + |
| 63 | + A simple use case is: |
| 64 | + |
| 65 | + ```.ts |
| 66 | + function searchOnChange(indexPattern: IndexPattern, aggConfigs: AggConfigs) { |
| 67 | + data.query.state$.subscribe(() => { |
| 68 | + |
| 69 | + // Constuct the query portion of the search request |
| 70 | + const query = data.query.getEsQuery(indexPattern); |
| 71 | + |
| 72 | + // Construct a request |
| 73 | + const request = { |
| 74 | + params: { |
| 75 | + index: indexPattern.title, |
| 76 | + body: { |
| 77 | + aggs: aggConfigs.toDsl(), |
| 78 | + query, |
| 79 | + }, |
| 80 | + }, |
| 81 | + }; |
| 82 | + |
| 83 | + // Search with the `data.query` config |
| 84 | + const search$ = data.search.search(request); |
| 85 | + |
| 86 | + ... |
| 87 | + }); |
| 88 | + } |
| 89 | + |
| 90 | + ``` |
| 91 | + |
| 92 | +## Search |
| 93 | + |
| 94 | +Provides access to Elasticsearch using the high-level `SearchSource` API or low-level `Search Strategies`. |
| 95 | + |
| 96 | +### SearchSource |
| 97 | + |
| 98 | +The `SearchSource` API is a convenient way to construct and run an Elasticsearch search query. |
| 99 | + |
| 100 | +```.tsx |
| 101 | + |
| 102 | + const searchSource = await data.search.searchSource.create(); |
| 103 | + const searchResponse = await searchSource |
| 104 | + .setParent(undefined) |
| 105 | + .setField('index', indexPattern) |
| 106 | + .setField('filter', filters) |
| 107 | + .fetch(); |
| 108 | + |
| 109 | +``` |
| 110 | + |
| 111 | +### Low-level search |
| 112 | + |
| 113 | +#### Default Search Strategy |
| 114 | + |
| 115 | +One benefit of using the low-level search API, is partial response support in X-Pack, allowing for a better and more responsive user experience. |
| 116 | +In OSS only the final result is returned. |
| 117 | + |
| 118 | +```.ts |
| 119 | + import { isCompleteResponse } from '../plugins/data/public'; |
| 120 | + |
| 121 | + const search$ = data.search.search(request) |
| 122 | + .subscribe({ |
| 123 | + next: (response) => { |
| 124 | + if (isCompleteResponse(response)) { |
| 125 | + // Final result |
| 126 | + search$.unsubscribe(); |
| 127 | + } else { |
| 128 | + // Partial result - you can update the UI, but data is still loading |
| 129 | + } |
| 130 | + }, |
| 131 | + error: (e: Error) => { |
| 132 | + // Show customized toast notifications. |
| 133 | + // You may choose to handle errors differently if you prefer. |
| 134 | + data.search.showError(e); |
| 135 | + }, |
| 136 | + }); |
| 137 | +``` |
0 commit comments