[Data] Cleanup filter docs (#107169)

* Move more utils to package and cleanup API * docs and imports * better imports * change comment * Better docs * typos * typo * fixes * casting * Code review * Update meta_filter.ts * fix Co-authored-by: Kibana Machine <42973632+kibanamachine@users.noreply.github.com> # Conflicts: # docs/development/plugins/data/public/kibana-plugin-plugins-data-public.castestokbnfieldtypename.md # docs/development/plugins/data/public/kibana-plugin-plugins-data-public.getkbntypenames.md # docs/development/plugins/data/public/kibana-plugin-plugins-data-public.md # docs/development/plugins/data/server/kibana-plugin-plugins-data-server.buildqueryfromfilters.md # docs/development/plugins/data/server/kibana-plugin-plugins-data-server.castestokbnfieldtypename.md # docs/development/plugins/data/server/kibana-plugin-plugins-data-server.esqueryconfig.md # docs/development/plugins/data/server/kibana-plugin-plugins-data-server.filter.md # docs/development/plugins/data/server/kibana-plugin-plugins-data-server.ifieldsubtype.md # docs/development/plugins/data/server/kibana-plugin-plugins-data-server.kuerynode.md # src/plugins/data/public/public.api.md
elastic · Aug 6, 2021 · 3c645c1 · 3c645c1
1 parent 209b062
commit 3c645c1
Show file tree

Hide file tree

Showing 46 changed files with 464 additions and 134 deletions.
diff --git a/.../development/plugins/data/public/kibana-plugin-plugins-data-public.esfilters.md b/.../development/plugins/data/public/kibana-plugin-plugins-data-public.esfilters.md
@@ -20,18 +20,18 @@ esFilters: {
     FILTERS: typeof import("@kbn/es-query").FILTERS;
     FilterStateStore: typeof FilterStateStore;
     buildEmptyFilter: (isPinned: boolean, index?: string | undefined) => import("@kbn/es-query").Filter;
-    buildPhrasesFilter: (field: import("@kbn/es-query").IndexPatternFieldBase, params: any[], indexPattern: import("@kbn/es-query").IndexPatternBase) => import("@kbn/es-query").PhrasesFilter;
+    buildPhrasesFilter: (field: import("@kbn/es-query").IndexPatternFieldBase, params: string[], indexPattern: import("@kbn/es-query").IndexPatternBase) => import("@kbn/es-query").PhrasesFilter;
     buildExistsFilter: (field: import("@kbn/es-query").IndexPatternFieldBase, indexPattern: import("@kbn/es-query").IndexPatternBase) => import("@kbn/es-query").ExistsFilter;
-    buildPhraseFilter: (field: import("@kbn/es-query").IndexPatternFieldBase, value: any, indexPattern: import("@kbn/es-query").IndexPatternBase) => import("@kbn/es-query").PhraseFilter;
+    buildPhraseFilter: (field: import("@kbn/es-query").IndexPatternFieldBase, value: string | number | boolean, indexPattern: import("@kbn/es-query").IndexPatternBase) => import("@kbn/es-query").PhraseFilter;
     buildQueryFilter: (query: any, index: string, alias: string) => import("@kbn/es-query/target_types/filters/build_filters").QueryStringFilter;
     buildRangeFilter: (field: import("@kbn/es-query").IndexPatternFieldBase, params: import("@kbn/es-query").RangeFilterParams, indexPattern: import("@kbn/es-query").IndexPatternBase, formattedValue?: string | undefined) => import("@kbn/es-query").RangeFilter;
-    isPhraseFilter: (filter: any) => filter is import("@kbn/es-query").PhraseFilter;
-    isExistsFilter: (filter: any) => filter is import("@kbn/es-query").ExistsFilter;
-    isPhrasesFilter: (filter: any) => filter is import("@kbn/es-query").PhrasesFilter;
-    isRangeFilter: (filter: any) => filter is import("@kbn/es-query").RangeFilter;
-    isMatchAllFilter: (filter: any) => filter is import("@kbn/es-query").MatchAllFilter;
-    isMissingFilter: (filter: any) => filter is import("@kbn/es-query").MissingFilter;
-    isQueryStringFilter: (filter: any) => filter is import("@kbn/es-query/target_types/filters/build_filters").QueryStringFilter;
+    isPhraseFilter: (filter: import("@kbn/es-query").FieldFilter) => filter is import("@kbn/es-query").PhraseFilter;
+    isExistsFilter: (filter: import("@kbn/es-query").FieldFilter) => filter is import("@kbn/es-query").ExistsFilter;
+    isPhrasesFilter: (filter: import("@kbn/es-query").FieldFilter) => filter is import("@kbn/es-query").PhrasesFilter;
+    isRangeFilter: (filter?: import("@kbn/es-query").ExistsFilter | import("@kbn/es-query").GeoPolygonFilter | import("@kbn/es-query").PhrasesFilter | import("@kbn/es-query").PhraseFilter | import("@kbn/es-query").MatchAllFilter | import("@kbn/es-query").MissingFilter | import("@kbn/es-query").RangeFilter | import("@kbn/es-query").GeoBoundingBoxFilter | undefined) => filter is import("@kbn/es-query").RangeFilter;
+    isMatchAllFilter: (filter: import("@kbn/es-query").FieldFilter) => filter is import("@kbn/es-query").MatchAllFilter;
+    isMissingFilter: (filter: import("@kbn/es-query").FieldFilter) => filter is import("@kbn/es-query").MissingFilter;
+    isQueryStringFilter: (filter: import("@kbn/es-query").FieldFilter) => filter is import("@kbn/es-query/target_types/filters/build_filters").QueryStringFilter;
     isFilterPinned: (filter: import("@kbn/es-query").Filter) => boolean | undefined;
     toggleFilterNegated: (filter: import("@kbn/es-query").Filter) => {
         meta: {
@@ -46,7 +46,9 @@ esFilters: {
             params?: any;
             value?: string | undefined;
         };
-        $state?: import("@kbn/es-query").FilterState | undefined;
+        $state?: {
+            store: FilterStateStore;
+        } | undefined;
         query?: any;
     };
     disableFilter: (filter: import("@kbn/es-query").Filter) => import("@kbn/es-query").Filter;

diff --git a/...ugins/data/server/kibana-plugin-plugins-data-server.castestokbnfieldtypename.md b/...ugins/data/server/kibana-plugin-plugins-data-server.castestokbnfieldtypename.md
@@ -6,11 +6,7 @@
 
 > Warning: This API is now obsolete.
 > 
-<<<<<<< HEAD
-> import from "<!-- -->@<!-- -->kbn/field-types" instead
-=======
 > Import from the "<!-- -->@<!-- -->kbn/field-types" package directly instead.  8.1
->>>>>>> af3a976e177... [FieldFormats] Break from `data` plugin (#107173)
 > 
 
 <b>Signature:</b>

diff --git a/.../development/plugins/data/server/kibana-plugin-plugins-data-server.esfilters.md b/.../development/plugins/data/server/kibana-plugin-plugins-data-server.esfilters.md
@@ -13,8 +13,8 @@ esFilters: {
     buildEmptyFilter: (isPinned: boolean, index?: string | undefined) => import("@kbn/es-query").Filter;
     buildExistsFilter: (field: import("@kbn/es-query").IndexPatternFieldBase, indexPattern: import("@kbn/es-query").IndexPatternBase) => import("@kbn/es-query").ExistsFilter;
     buildFilter: typeof import("@kbn/es-query").buildFilter;
-    buildPhraseFilter: (field: import("@kbn/es-query").IndexPatternFieldBase, value: any, indexPattern: import("@kbn/es-query").IndexPatternBase) => import("@kbn/es-query").PhraseFilter;
-    buildPhrasesFilter: (field: import("@kbn/es-query").IndexPatternFieldBase, params: any[], indexPattern: import("@kbn/es-query").IndexPatternBase) => import("@kbn/es-query").PhrasesFilter;
+    buildPhraseFilter: (field: import("@kbn/es-query").IndexPatternFieldBase, value: string | number | boolean, indexPattern: import("@kbn/es-query").IndexPatternBase) => import("@kbn/es-query").PhraseFilter;
+    buildPhrasesFilter: (field: import("@kbn/es-query").IndexPatternFieldBase, params: string[], indexPattern: import("@kbn/es-query").IndexPatternBase) => import("@kbn/es-query").PhrasesFilter;
     buildRangeFilter: (field: import("@kbn/es-query").IndexPatternFieldBase, params: import("@kbn/es-query").RangeFilterParams, indexPattern: import("@kbn/es-query").IndexPatternBase, formattedValue?: string | undefined) => import("@kbn/es-query").RangeFilter;
     isFilterDisabled: (filter: import("@kbn/es-query").Filter) => boolean;
 }

diff --git a/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.md b/docs/development/plugins/data/server/kibana-plugin-plugins-data-server.md
@@ -23,8 +23,6 @@
 |  Enumeration | Description |
 |  --- | --- |
 |  [BUCKET\_TYPES](./kibana-plugin-plugins-data-server.bucket_types.md) |  |
-|  [ES\_FIELD\_TYPES](./kibana-plugin-plugins-data-server.es_field_types.md) | \* |
-|  [KBN\_FIELD\_TYPES](./kibana-plugin-plugins-data-server.kbn_field_types.md) | \* |
 |  [METRIC\_TYPES](./kibana-plugin-plugins-data-server.metric_types.md) |  |
 
 ## Functions
@@ -74,7 +72,7 @@
 |  [AggGroupLabels](./kibana-plugin-plugins-data-server.agggrouplabels.md) |  |
 |  [AggGroupNames](./kibana-plugin-plugins-data-server.agggroupnames.md) |  |
 |  [buildQueryFromFilters](./kibana-plugin-plugins-data-server.buildqueryfromfilters.md) |  |
-|  [castEsToKbnFieldTypeName](./kibana-plugin-plugins-data-server.castestokbnfieldtypename.md) | Get the KbnFieldType name for an esType string |
+|  [castEsToKbnFieldTypeName](./kibana-plugin-plugins-data-server.castestokbnfieldtypename.md) |  |
 |  [config](./kibana-plugin-plugins-data-server.config.md) |  |
 |  [ES\_SEARCH\_STRATEGY](./kibana-plugin-plugins-data-server.es_search_strategy.md) |  |
 |  [esFilters](./kibana-plugin-plugins-data-server.esfilters.md) |  |

diff --git a/packages/kbn-es-query/src/es_query/build_es_query.ts b/packages/kbn-es-query/src/es_query/build_es_query.ts
@@ -13,6 +13,10 @@ import { buildQueryFromLucene } from './from_lucene';
 import { Filter, Query } from '../filters';
 import { IndexPatternBase } from './types';
 
+/**
+ * Configurations to be used while constructing an ES query.
+ * @public
+ */
 export interface EsQueryConfig {
   allowLeadingWildcards: boolean;
   queryStringOptions: Record<string, any>;
@@ -33,6 +37,8 @@ function removeMatchAll<T>(filters: T[]) {
  * @param config - an objects with query:allowLeadingWildcards and query:queryString:options UI
  * settings in form of { allowLeadingWildcards, queryStringOptions }
  * config contains dateformat:tz
+ *
+ * @public
  */
 export function buildEsQuery(
   indexPattern: IndexPatternBase | undefined,
@@ -47,7 +53,7 @@ export function buildEsQuery(
   queries = Array.isArray(queries) ? queries : [queries];
   filters = Array.isArray(filters) ? filters : [filters];
 
-  const validQueries = queries.filter((query) => has(query, 'query'));
+  const validQueries = queries.filter((query: any) => has(query, 'query'));
   const queriesByLanguage = groupBy(validQueries, 'language');
   const kueryQuery = buildQueryFromKuery(
     indexPattern,

diff --git a/packages/kbn-es-query/src/es_query/decorate_query.ts b/packages/kbn-es-query/src/es_query/decorate_query.ts
@@ -16,6 +16,8 @@ import { DslQuery, isEsQueryString } from './es_query_dsl';
  * @param queryStringOptions query:queryString:options from UI settings
  * @param dateFormatTZ dateFormat:tz from UI settings
  * @returns {object}
+ *
+ * @public
  */
 
 export function decorateQuery(

diff --git a/packages/kbn-es-query/src/es_query/es_query_dsl.ts b/packages/kbn-es-query/src/es_query/es_query_dsl.ts
@@ -43,12 +43,16 @@ export interface DslTermQuery {
   term: Record<string, string>;
 }
 
+/**
+ * @public
+ */
 export type DslQuery =
   | DslRangeQuery
   | DslMatchQuery
   | DslQueryStringQuery
   | DslMatchAllQuery
   | DslTermQuery;
 
+/** @internal */
 export const isEsQueryString = (query: any): query is DslQueryStringQuery =>
   has(query, 'query_string.query');
diff --git a/packages/kbn-es-query/src/es_query/filter_matches_index.ts b/packages/kbn-es-query/src/es_query/filter_matches_index.ts
@@ -13,6 +13,8 @@ import { IndexPatternBase } from '..';
  * TODO: We should base this on something better than `filter.meta.key`. We should probably modify
  * this to check if `filter.meta.index` matches `indexPattern.id` instead, but that's a breaking
  * change.
+ *
+ * @internal
  */
 export function filterMatchesIndex(filter: Filter, indexPattern?: IndexPatternBase | null) {
   if (!filter.meta?.key || !indexPattern) {

diff --git a/packages/kbn-es-query/src/es_query/from_filters.ts b/packages/kbn-es-query/src/es_query/from_filters.ts
@@ -43,6 +43,14 @@ const translateToQuery = (filter: Filter) => {
   return filter;
 };
 
+/**
+ * @param filters
+ * @param indexPattern
+ * @param ignoreFilterIfFieldNotInIndex by default filters that use fields that can't be found in the specified index pattern are not applied. Set this to true if you want to apply them any way.
+ * @returns An EQL query
+ *
+ * @public
+ */
 export const buildQueryFromFilters = (
   filters: Filter[] = [],
   indexPattern: IndexPatternBase | undefined,

diff --git a/packages/kbn-es-query/src/es_query/from_kuery.ts b/packages/kbn-es-query/src/es_query/from_kuery.ts
@@ -10,6 +10,7 @@ import { Query } from '../filters';
 import { fromKueryExpression, toElasticsearchQuery, nodeTypes, KueryNode } from '../kuery';
 import { IndexPatternBase } from './types';
 
+/** @internal */
 export function buildQueryFromKuery(
   indexPattern: IndexPatternBase | undefined,
   queries: Query[] = [],

diff --git a/packages/kbn-es-query/src/es_query/from_lucene.ts b/packages/kbn-es-query/src/es_query/from_lucene.ts
@@ -10,6 +10,7 @@ import { Query } from '..';
 import { decorateQuery } from './decorate_query';
 import { luceneStringToDsl } from './lucene_string_to_dsl';
 
+/** @internal */
 export function buildQueryFromLucene(
   queries: Query[],
   queryStringOptions: Record<string, any>,

diff --git a/packages/kbn-es-query/src/es_query/handle_nested_filter.ts b/packages/kbn-es-query/src/es_query/handle_nested_filter.ts
@@ -9,6 +9,7 @@
 import { getFilterField, cleanFilter, Filter } from '../filters';
 import { IndexPatternBase } from './types';
 
+/** @internal */
 export const handleNestedFilter = (filter: Filter, indexPattern?: IndexPatternBase) => {
   if (!indexPattern) return filter;
 

diff --git a/packages/kbn-es-query/src/es_query/lucene_string_to_dsl.ts b/packages/kbn-es-query/src/es_query/lucene_string_to_dsl.ts
@@ -9,6 +9,13 @@
 import { isString } from 'lodash';
 import { DslQuery } from './es_query_dsl';
 
+/**
+ *
+ * @param query
+ * @returns
+ *
+ * @public
+ */
 export function luceneStringToDsl(query: string | any): DslQuery {
   if (isString(query)) {
     if (query.trim() === '') {

diff --git a/packages/kbn-es-query/src/es_query/migrate_filter.ts b/packages/kbn-es-query/src/es_query/migrate_filter.ts
@@ -11,6 +11,7 @@ import { getConvertedValueForField } from '../filters';
 import { Filter } from '../filters';
 import { IndexPatternBase } from './types';
 
+/** @internal */
 export interface DeprecatedMatchPhraseFilter extends Filter {
   query: {
     match: {
@@ -28,6 +29,7 @@ function isDeprecatedMatchPhraseFilter(filter: any): filter is DeprecatedMatchPh
   return Boolean(fieldName && get(filter, ['query', 'match', fieldName, 'type']) === 'phrase');
 }
 
+/** @internal */
 export function migrateFilter(filter: Filter, indexPattern?: IndexPatternBase) {
   if (isDeprecatedMatchPhraseFilter(filter)) {
     const fieldName = Object.keys(filter.query.match)[0];

diff --git a/packages/kbn-es-query/src/es_query/types.ts b/packages/kbn-es-query/src/es_query/types.ts
@@ -8,10 +8,19 @@
 
 import type { estypes } from '@elastic/elasticsearch';
 
+/**
+ * A field's sub type
+ * @public
+ */
 export interface IFieldSubType {
   multi?: { parent: string };
   nested?: { path: string };
 }
+
+/**
+ * A base interface for an index pattern field
+ * @public
+ */
 export interface IndexPatternFieldBase {
   name: string;
   /**
@@ -31,6 +40,10 @@ export interface IndexPatternFieldBase {
   scripted?: boolean;
 }
 
+/**
+ * A base interface for an index pattern
+ * @public
+ */
 export interface IndexPatternBase {
   fields: IndexPatternFieldBase[];
   id?: string;

diff --git a/packages/kbn-es-query/src/filters/build_filters/build_empty_filter.ts b/packages/kbn-es-query/src/filters/build_filters/build_empty_filter.ts
@@ -6,7 +6,7 @@
  * Side Public License, v 1.
  */
 
-import { Filter, FilterMeta, FilterState, FilterStateStore } from './types';
+import { Filter, FilterMeta, FilterStateStore } from './types';
 
 export const buildEmptyFilter = (isPinned: boolean, index?: string): Filter => {
   const meta: FilterMeta = {
@@ -15,7 +15,7 @@ export const buildEmptyFilter = (isPinned: boolean, index?: string): Filter => {
     alias: null,
     index,
   };
-  const $state: FilterState = {
+  const $state: Filter['$state'] = {
     store: isPinned ? FilterStateStore.GLOBAL_STATE : FilterStateStore.APP_STATE,
   };
 

diff --git a/packages/kbn-es-query/src/filters/build_filters/build_filters.ts b/packages/kbn-es-query/src/filters/build_filters/build_filters.ts
@@ -14,8 +14,22 @@ import { buildRangeFilter } from './range_filter';
 import { buildExistsFilter } from './exists_filter';
 
 import type { IndexPatternFieldBase, IndexPatternBase } from '../../es_query';
-import { FilterMeta, FilterStateStore } from './types';
+import { FilterStateStore } from './types';
 
+/**
+ *
+ * @param indexPattern
+ * @param field
+ * @param type
+ * @param negate whether the filter is negated (NOT filter)
+ * @param disabled  whether the filter is disabled andwon't be applied to searches
+ * @param params
+ * @param alias a display name for the filter
+ * @param store whether the filter applies to the current application or should be applied to global context
+ * @returns
+ *
+ * @public
+ */
 export function buildFilter(
   indexPattern: IndexPatternBase,
   field: IndexPatternFieldBase,
@@ -36,26 +50,6 @@ export function buildFilter(
   return filter;
 }
 
-export function buildCustomFilter(
-  indexPatternString: string,
-  queryDsl: any,
-  disabled: boolean,
-  negate: boolean,
-  alias: string | null,
-  store: FilterStateStore
-): Filter {
-  const meta: FilterMeta = {
-    index: indexPatternString,
-    type: FILTERS.CUSTOM,
-    disabled,
-    negate,
-    alias,
-  };
-  const filter: Filter = { ...queryDsl, meta };
-  filter.$state = { store };
-  return filter;
-}
-
 function buildBaseFilter(
   indexPattern: IndexPatternBase,
   field: IndexPatternFieldBase,

diff --git a/packages/kbn-es-query/src/filters/build_filters/custom_filter.ts b/packages/kbn-es-query/src/filters/build_filters/custom_filter.ts
@@ -6,8 +6,41 @@
  * Side Public License, v 1.
  */
 
-import type { Filter } from './types';
+import { Filter, FilterMeta, FILTERS, FilterStateStore } from './types';
 
+/** @public */
 export type CustomFilter = Filter & {
   query: any;
 };
+
+/**
+ *
+ * @param indexPatternString
+ * @param queryDsl
+ * @param disabled
+ * @param negate
+ * @param alias
+ * @param store
+ * @returns
+ *
+ * @public
+ */
+export function buildCustomFilter(
+  indexPatternString: string,
+  queryDsl: any,
+  disabled: boolean,
+  negate: boolean,
+  alias: string | null,
+  store: FilterStateStore
+): Filter {
+  const meta: FilterMeta = {
+    index: indexPatternString,
+    type: FILTERS.CUSTOM,
+    disabled,
+    negate,
+    alias,
+  };
+  const filter: Filter = { ...queryDsl, meta };
+  filter.$state = { store };
+  return filter;
+}