[Data] Cleanup filter docs

docs/development/plugins/data/public/kibana-plugin-plugins-data-public.esfilters.md

@@ -28,7 +28,7 @@ esFilters: {
     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;
+    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: 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;

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,

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(

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');

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) {

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,

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[] = [],

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>,

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;
 

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() === '') {

packages/kbn-es-query/src/es_query/migrate_filter.ts

@@ -11,7 +11,7 @@ import { getConvertedValueForField } from '../filters';
 import { Filter } from '../filters';
 import { IndexPatternBase } from './types';
 
-export interface DeprecatedMatchPhraseFilter extends Filter {
+interface DeprecatedMatchPhraseFilter extends Filter {
   query: {
     match: {
       [field: string]: {
@@ -28,6 +28,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];

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;

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,
   };
 

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,

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;
+}

packages/kbn-es-query/src/filters/build_filters/exists_filter.ts

@@ -6,26 +6,42 @@
  * Side Public License, v 1.
  */
 
+import { get } from 'lodash';
 import type { IndexPatternFieldBase, IndexPatternBase } from '../../es_query';
-import type { Filter, FilterMeta } from './types';
-
-export type ExistsFilterMeta = FilterMeta;
-
-export interface FilterExistsProperty {
-  field: any;
-}
+import type { FieldFilter, Filter, FilterMeta } from './types';
 
+/** @public */
 export type ExistsFilter = Filter & {
-  meta: ExistsFilterMeta;
-  exists?: FilterExistsProperty;
+  meta: FilterMeta;
+  exists?: {
+    field: string;
+  };
 };
 
-export const isExistsFilter = (filter: any): filter is ExistsFilter => filter && filter.exists;
+/**
+ * @param filter
+ * @returns `true` if a filter is an `ExistsFilter`
+ *
+ * @public
+ */
+export const isExistsFilter = (filter: FieldFilter): filter is ExistsFilter =>
+  get(filter, 'exists');
 
+/**
+ * @internal
+ */
 export const getExistsFilterField = (filter: ExistsFilter) => {
   return filter.exists && filter.exists.field;
 };
 
+/**
+ * Builds an `ExistsFilter`
+ * @param field field to validate the existence of
+ * @param indexPattern index pattern to look for the field in
+ * @returns An `ExistsFilter`
+ *
+ * @public
+ */
 export const buildExistsFilter = (field: IndexPatternFieldBase, indexPattern: IndexPatternBase) => {
   return {
     meta: {

packages/kbn-es-query/src/filters/build_filters/geo_bounding_box_filter.ts

@@ -6,7 +6,8 @@
  * Side Public License, v 1.
  */
 
-import type { Filter, FilterMeta, LatLon } from './types';
+import { get } from 'lodash';
+import type { FieldFilter, Filter, FilterMeta, LatLon } from './types';
 
 export type GeoBoundingBoxFilterMeta = FilterMeta & {
   params: {
@@ -20,9 +21,18 @@ export type GeoBoundingBoxFilter = Filter & {
   geo_bounding_box: any;
 };
 
-export const isGeoBoundingBoxFilter = (filter: any): filter is GeoBoundingBoxFilter =>
-  filter && filter.geo_bounding_box;
+/**
+ * @param filter
+ * @returns `true` if a filter is an `GeoBoundingBoxFilter`
+ *
+ * @public
+ */
+export const isGeoBoundingBoxFilter = (filter: FieldFilter): filter is GeoBoundingBoxFilter =>
+  get(filter, 'geo_bounding_box');
 
+/**
+ * @internal
+ */
 export const getGeoBoundingBoxFilterField = (filter: GeoBoundingBoxFilter) => {
   return (
     filter.geo_bounding_box &&