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