From 09226db99c8823a0fec5fe5fa87e33909f95621a Mon Sep 17 00:00:00 2001 From: Liza Katz Date: Thu, 1 Oct 2020 10:56:17 +0300 Subject: [PATCH] Data plugin README (#78750) * data readme * Delete old readme (other folders don't have a README of their own. * generate asciidoc * Update src/plugins/data/README.md Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * Update src/plugins/data/README.md Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * Update src/plugins/data/README.md Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * Update src/plugins/data/README.md Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * Update src/plugins/data/README.md Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * Update src/plugins/data/README.md Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * Update src/plugins/data/README.md Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * Update src/plugins/data/README.md Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * Update src/plugins/data/README.md Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * Update src/plugins/data/README.md Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * Update src/plugins/data/README.md Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * Update src/plugins/data/README.md Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * Update README.md * Update plugin-list.asciidoc * gen plugin list * Update src/plugins/data/README.md Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * Update src/plugins/data/README.md Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * Update src/plugins/data/README.md Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> Co-authored-by: Elastic Machine Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> --- docs/developer/plugin-list.asciidoc | 2 +- src/plugins/data/README.md | 140 ++++++++++++++++++++++- src/plugins/data/public/search/README.md | 23 ---- 3 files changed, 135 insertions(+), 30 deletions(-) delete mode 100644 src/plugins/data/public/search/README.md diff --git a/docs/developer/plugin-list.asciidoc b/docs/developer/plugin-list.asciidoc index e314e55c34085..ed58e77427d47 100644 --- a/docs/developer/plugin-list.asciidoc +++ b/docs/developer/plugin-list.asciidoc @@ -48,7 +48,7 @@ NOTE: |{kib-repo}blob/{branch}/src/plugins/data/README.md[data] -|data plugin provides common data access services. +|The data plugin provides common data access services, such as search and query, for solutions and application developers. |{kib-repo}blob/{branch}/src/plugins/dev_tools/README.md[devTools] diff --git a/src/plugins/data/README.md b/src/plugins/data/README.md index da0b71122fd9e..33c07078c5348 100644 --- a/src/plugins/data/README.md +++ b/src/plugins/data/README.md @@ -1,9 +1,137 @@ # data -`data` plugin provides common data access services. +The data plugin provides common data access services, such as `search` and `query`, for solutions and application developers. -- `expressions` — run pipeline functions and render results. -- `filter` -- `index_patterns` -- `query` -- `search`: Elasticsearch API service and strategies \ No newline at end of file +## Autocomplete + +The autocomplete service provides suggestions for field names and values. + +It is wired into the `TopNavMenu` component, but can be used independently. + +### Fetch Query Suggestions + +The `getQuerySuggestions` function helps to construct a query. +KQL suggestion functions are registered in X-Pack, so this API does not return results in OSS. + +```.ts + + // `inputValue` is the user input + const querySuggestions = await autocomplete.getQuerySuggestions({ + language: 'kuery', + indexPatterns: [indexPattern], + query: inputValue, + }); + +``` + +### Fetch Value Suggestions + +The `getValueSuggestions` function returns suggestions for field values. +This is helpful when you want to provide a user with options, for example when constructing a filter. + +```.ts + + // `inputValue` is the user input + const valueSuggestions = await autocomplete.getValueSuggestions({ + indexPattern, + field, + query: inputValue, + }); + +``` + +## Field Formats + +Coming soon. + +## Index Patterns + +Coming soon. + +## Query + +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. + +It contains sub-services for each of those configurations: + - `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. + - `data.query.timefilter` - Responsible for the time range filter and the auto refresh behavior settings. + - `data.query.queryString` - Responsible for the query string and query language settings. + - `data.query.savedQueries` - Responsible for persisting a `QueryState` into a `SavedObject`, so it can be restored and used by other applications. + + 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. + + A simple use case is: + + ```.ts + function searchOnChange(indexPattern: IndexPattern, aggConfigs: AggConfigs) { + data.query.state$.subscribe(() => { + + // Constuct the query portion of the search request + const query = data.query.getEsQuery(indexPattern); + + // Construct a request + const request = { + params: { + index: indexPattern.title, + body: { + aggs: aggConfigs.toDsl(), + query, + }, + }, + }; + + // Search with the `data.query` config + const search$ = data.search.search(request); + + ... + }); + } + + ``` + +## Search + +Provides access to Elasticsearch using the high-level `SearchSource` API or low-level `Search Strategies`. + +### SearchSource + +The `SearchSource` API is a convenient way to construct and run an Elasticsearch search query. + +```.tsx + + const searchSource = await data.search.searchSource.create(); + const searchResponse = await searchSource + .setParent(undefined) + .setField('index', indexPattern) + .setField('filter', filters) + .fetch(); + +``` + +### Low-level search + +#### Default Search Strategy + +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. +In OSS only the final result is returned. + +```.ts + import { isCompleteResponse } from '../plugins/data/public'; + + const search$ = data.search.search(request) + .subscribe({ + next: (response) => { + if (isCompleteResponse(response)) { + // Final result + search$.unsubscribe(); + } else { + // Partial result - you can update the UI, but data is still loading + } + }, + error: (e: Error) => { + // Show customized toast notifications. + // You may choose to handle errors differently if you prefer. + data.search.showError(e); + }, + }); +``` diff --git a/src/plugins/data/public/search/README.md b/src/plugins/data/public/search/README.md deleted file mode 100644 index 0a123ffa3f1e9..0000000000000 --- a/src/plugins/data/public/search/README.md +++ /dev/null @@ -1,23 +0,0 @@ -# search - -The `search` service provides you with APIs to query Elasticsearch. - -The services are split into two parts: (1) low-level API; and (2) high-level API. - -## Low-level API - -With low level API you work directly with elasticsearch DSL - -```typescript -const results = await data.search.search(request, params); -``` - -## High-level API - -Using high-level API you work with Kibana abstractions around Elasticsearch DSL: filters, queries, and aggregations. Provided by the *Search Source* service. - -```typescript -const search = data.search.searchSource.createEmpty(); -search.setField('query', data.query.queryString); -const results = await search.fetch(); -```