[7.x] expression service docs (#78774) (#80184)

docs/developer/plugin-list.asciidoc

@@ -70,8 +70,20 @@ This API doesn't support angular, for registering angular dev tools, bootstrap a
 |WARNING: Missing README.
 
 
-|{kib-repo}blob/{branch}/src/plugins/expressions/README.md[expressions]
-|This plugin provides methods which will parse & execute an expression pipeline
+|<<kibana-expressions-plugin>>
+|Expression pipeline is a chain of functions that *pipe* its output to the
+input of the next function. Functions can be configured using arguments provided
+by the user. The final output of the expression pipeline can be rendered using
+one of the *renderers* registered in `expressions` plugin.
+
+All the arguments to expression functions need to be serializable, as well as input and output.
+Expression functions should try to stay 'pure'. This makes functions easy to reuse and also 
+make it possible to serialize the whole chain as well as output at every step of execution.
+
+Expressions power visualizations in Dashboard and Lens, as well as, every
+*element* in Canvas is backed by an expression.
+
+This plugin provides methods which will parse & execute an *expression pipeline*
 string for you, as well as a series of registries for advanced users who might
 want to incorporate their own functions, types, and renderers into the service
 for use in their own application.
@@ -520,5 +532,6 @@ in their infrastructure.
 |===
 
 include::{kibana-root}/src/plugins/dashboard/README.asciidoc[leveloffset=+1]
+include::{kibana-root}/src/plugins/expressions/README.asciidoc[leveloffset=+1]
 include::{kibana-root}/x-pack/plugins/dashboard_enhanced/README.asciidoc[leveloffset=+1]
 include::{kibana-root}/x-pack/plugins/embeddable_enhanced/README.asciidoc[leveloffset=+1]

docs/development/plugins/expressions/public/index.md

@@ -0,0 +1,12 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md)
+
+## API Reference
+
+## Packages
+
+|  Package | Description |
+|  --- | --- |
+|  [kibana-plugin-plugins-expressions-public](./kibana-plugin-plugins-expressions-public.md) |  |
+

docs/development/plugins/expressions/public/kibana-plugin-plugins-expressions-public.anyexpressionfunctiondefinition.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-plugins-expressions-public](./kibana-plugin-plugins-expressions-public.md) &gt; [AnyExpressionFunctionDefinition](./kibana-plugin-plugins-expressions-public.anyexpressionfunctiondefinition.md)
+
+## AnyExpressionFunctionDefinition type
+
+Type to capture every possible expression function definition.
+
+<b>Signature:</b>
+
+```typescript
+export declare type AnyExpressionFunctionDefinition = ExpressionFunctionDefinition<string, any, Record<string, any>, any>;
+```

docs/development/plugins/expressions/public/kibana-plugin-plugins-expressions-public.anyexpressiontypedefinition.md

@@ -0,0 +1,11 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-plugins-expressions-public](./kibana-plugin-plugins-expressions-public.md) &gt; [AnyExpressionTypeDefinition](./kibana-plugin-plugins-expressions-public.anyexpressiontypedefinition.md)
+
+## AnyExpressionTypeDefinition type
+
+<b>Signature:</b>
+
+```typescript
+export declare type AnyExpressionTypeDefinition = ExpressionTypeDefinition<any, any, any>;
+```

docs/development/plugins/expressions/public/kibana-plugin-plugins-expressions-public.argumenttype.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-plugins-expressions-public](./kibana-plugin-plugins-expressions-public.md) &gt; [ArgumentType](./kibana-plugin-plugins-expressions-public.argumenttype.md)
+
+## ArgumentType type
+
+This type represents all of the possible combinations of properties of an Argument in an Expression Function. The presence or absence of certain fields influence the shape and presence of others within each `arg` in the specification.
+
+<b>Signature:</b>
+
+```typescript
+export declare type ArgumentType<T> = SingleArgumentType<T> | MultipleArgumentType<T> | UnresolvedSingleArgumentType<T> | UnresolvedMultipleArgumentType<T>;
+```

docs/development/plugins/expressions/public/kibana-plugin-plugins-expressions-public.buildexpression.md

@@ -0,0 +1,24 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-plugins-expressions-public](./kibana-plugin-plugins-expressions-public.md) &gt; [buildExpression](./kibana-plugin-plugins-expressions-public.buildexpression.md)
+
+## buildExpression() function
+
+Makes it easy to progressively build, update, and traverse an expression AST. You can either start with an empty AST, or provide an expression string, AST, or array of expression function builders to use as initial state.
+
+<b>Signature:</b>
+
+```typescript
+export declare function buildExpression(initialState?: ExpressionAstFunctionBuilder[] | ExpressionAstExpression | string): ExpressionAstExpressionBuilder;
+```
+
+## Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  initialState | <code>ExpressionAstFunctionBuilder[] &#124; ExpressionAstExpression &#124; string</code> |  |
+
+<b>Returns:</b>
+
+`ExpressionAstExpressionBuilder`
+

docs/development/plugins/expressions/public/kibana-plugin-plugins-expressions-public.buildexpressionfunction.md

@@ -0,0 +1,30 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-plugins-expressions-public](./kibana-plugin-plugins-expressions-public.md) &gt; [buildExpressionFunction](./kibana-plugin-plugins-expressions-public.buildexpressionfunction.md)
+
+## buildExpressionFunction() function
+
+Manages an AST for a single expression function. The return value can be provided to `buildExpression` to add this function to an expression.
+
+Note that to preserve type safety and ensure no args are missing, all required arguments for the specified function must be provided up front. If desired, they can be changed or removed later.
+
+<b>Signature:</b>
+
+```typescript
+export declare function buildExpressionFunction<FnDef extends AnyExpressionFunctionDefinition = AnyExpressionFunctionDefinition>(fnName: InferFunctionDefinition<FnDef>['name'], 
+initialArgs: {
+    [K in keyof FunctionArgs<FnDef>]: FunctionArgs<FnDef>[K] | ExpressionAstExpressionBuilder | ExpressionAstExpressionBuilder[];
+}): ExpressionAstFunctionBuilder<FnDef>;
+```
+
+## Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  fnName | <code>InferFunctionDefinition&lt;FnDef&gt;['name']</code> |  |
+|  initialArgs | <code>{</code><br/><code>    [K in keyof FunctionArgs&lt;FnDef&gt;]: FunctionArgs&lt;FnDef&gt;[K] &#124; ExpressionAstExpressionBuilder &#124; ExpressionAstExpressionBuilder[];</code><br/><code>}</code> |  |
+
+<b>Returns:</b>
+
+`ExpressionAstFunctionBuilder<FnDef>`
+

docs/development/plugins/expressions/public/kibana-plugin-plugins-expressions-public.datatable.columns.md

@@ -0,0 +1,11 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-plugins-expressions-public](./kibana-plugin-plugins-expressions-public.md) &gt; [Datatable](./kibana-plugin-plugins-expressions-public.datatable.md) &gt; [columns](./kibana-plugin-plugins-expressions-public.datatable.columns.md)
+
+## Datatable.columns property
+
+<b>Signature:</b>
+
+```typescript
+columns: DatatableColumn[];
+```

docs/development/plugins/expressions/public/kibana-plugin-plugins-expressions-public.datatable.md

@@ -0,0 +1,22 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-plugins-expressions-public](./kibana-plugin-plugins-expressions-public.md) &gt; [Datatable](./kibana-plugin-plugins-expressions-public.datatable.md)
+
+## Datatable interface
+
+A `Datatable` in Canvas is a unique structure that represents tabulated data.
+
+<b>Signature:</b>
+
+```typescript
+export interface Datatable 
+```
+
+## Properties
+
+|  Property | Type | Description |
+|  --- | --- | --- |
+|  [columns](./kibana-plugin-plugins-expressions-public.datatable.columns.md) | <code>DatatableColumn[]</code> |  |
+|  [rows](./kibana-plugin-plugins-expressions-public.datatable.rows.md) | <code>DatatableRow[]</code> |  |
+|  [type](./kibana-plugin-plugins-expressions-public.datatable.type.md) | <code>typeof name</code> |  |
+

docs/development/plugins/expressions/public/kibana-plugin-plugins-expressions-public.datatable.rows.md

@@ -0,0 +1,11 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-plugins-expressions-public](./kibana-plugin-plugins-expressions-public.md) &gt; [Datatable](./kibana-plugin-plugins-expressions-public.datatable.md) &gt; [rows](./kibana-plugin-plugins-expressions-public.datatable.rows.md)
+
+## Datatable.rows property
+
+<b>Signature:</b>
+
+```typescript
+rows: DatatableRow[];
+```

docs/development/plugins/expressions/public/kibana-plugin-plugins-expressions-public.datatable.type.md

@@ -0,0 +1,11 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-plugins-expressions-public](./kibana-plugin-plugins-expressions-public.md) &gt; [Datatable](./kibana-plugin-plugins-expressions-public.datatable.md) &gt; [type](./kibana-plugin-plugins-expressions-public.datatable.type.md)
+
+## Datatable.type property
+
+<b>Signature:</b>
+
+```typescript
+type: typeof name;
+```

docs/development/plugins/expressions/public/kibana-plugin-plugins-expressions-public.datatablecolumn.id.md

@@ -0,0 +1,11 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-plugins-expressions-public](./kibana-plugin-plugins-expressions-public.md) &gt; [DatatableColumn](./kibana-plugin-plugins-expressions-public.datatablecolumn.md) &gt; [id](./kibana-plugin-plugins-expressions-public.datatablecolumn.id.md)
+
+## DatatableColumn.id property
+
+<b>Signature:</b>
+
+```typescript
+id: string;
+```

docs/development/plugins/expressions/public/kibana-plugin-plugins-expressions-public.datatablecolumn.md

@@ -0,0 +1,22 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-plugins-expressions-public](./kibana-plugin-plugins-expressions-public.md) &gt; [DatatableColumn](./kibana-plugin-plugins-expressions-public.datatablecolumn.md)
+
+## DatatableColumn interface
+
+This type represents the shape of a column in a `Datatable`<!-- -->.
+
+<b>Signature:</b>
+
+```typescript
+export interface DatatableColumn 
+```
+
+## Properties
+
+|  Property | Type | Description |
+|  --- | --- | --- |
+|  [id](./kibana-plugin-plugins-expressions-public.datatablecolumn.id.md) | <code>string</code> |  |
+|  [meta](./kibana-plugin-plugins-expressions-public.datatablecolumn.meta.md) | <code>DatatableColumnMeta</code> |  |
+|  [name](./kibana-plugin-plugins-expressions-public.datatablecolumn.name.md) | <code>string</code> |  |
+

docs/development/plugins/expressions/public/kibana-plugin-plugins-expressions-public.datatablecolumn.meta.md

@@ -0,0 +1,11 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-plugins-expressions-public](./kibana-plugin-plugins-expressions-public.md) &gt; [DatatableColumn](./kibana-plugin-plugins-expressions-public.datatablecolumn.md) &gt; [meta](./kibana-plugin-plugins-expressions-public.datatablecolumn.meta.md)
+
+## DatatableColumn.meta property
+
+<b>Signature:</b>
+
+```typescript
+meta: DatatableColumnMeta;
+```

docs/development/plugins/expressions/public/kibana-plugin-plugins-expressions-public.datatablecolumn.name.md

@@ -0,0 +1,11 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-plugins-expressions-public](./kibana-plugin-plugins-expressions-public.md) &gt; [DatatableColumn](./kibana-plugin-plugins-expressions-public.datatablecolumn.md) &gt; [name](./kibana-plugin-plugins-expressions-public.datatablecolumn.name.md)
+
+## DatatableColumn.name property
+
+<b>Signature:</b>
+
+```typescript
+name: string;
+```

docs/development/plugins/expressions/public/kibana-plugin-plugins-expressions-public.datatablecolumntype.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-plugins-expressions-public](./kibana-plugin-plugins-expressions-public.md) &gt; [DatatableColumnType](./kibana-plugin-plugins-expressions-public.datatablecolumntype.md)
+
+## DatatableColumnType type
+
+This type represents the `type` of any `DatatableColumn` in a `Datatable`<!-- -->.
+
+<b>Signature:</b>
+
+```typescript
+export declare type DatatableColumnType = 'string' | 'number' | 'boolean' | 'date' | 'null';
+```

docs/development/plugins/expressions/public/kibana-plugin-plugins-expressions-public.datatablerow.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-plugins-expressions-public](./kibana-plugin-plugins-expressions-public.md) &gt; [DatatableRow](./kibana-plugin-plugins-expressions-public.datatablerow.md)
+
+## DatatableRow type
+
+This type represents a row in a `Datatable`<!-- -->.
+
+<b>Signature:</b>
+
+```typescript
+export declare type DatatableRow = Record<string, any>;
+```

docs/development/plugins/expressions/public/kibana-plugin-plugins-expressions-public.execution._constructor_.md

@@ -0,0 +1,20 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-plugins-expressions-public](./kibana-plugin-plugins-expressions-public.md) &gt; [Execution](./kibana-plugin-plugins-expressions-public.execution.md) &gt; [(constructor)](./kibana-plugin-plugins-expressions-public.execution._constructor_.md)
+
+## Execution.(constructor)
+
+Constructs a new instance of the `Execution` class
+
+<b>Signature:</b>
+
+```typescript
+constructor(params: ExecutionParams<ExtraContext>);
+```
+
+## Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  params | <code>ExecutionParams&lt;ExtraContext&gt;</code> |  |
+

docs/development/plugins/expressions/public/kibana-plugin-plugins-expressions-public.execution.cancel.md

@@ -0,0 +1,17 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-plugins-expressions-public](./kibana-plugin-plugins-expressions-public.md) &gt; [Execution](./kibana-plugin-plugins-expressions-public.execution.md) &gt; [cancel](./kibana-plugin-plugins-expressions-public.execution.cancel.md)
+
+## Execution.cancel() method
+
+Stop execution of expression.
+
+<b>Signature:</b>
+
+```typescript
+cancel(): void;
+```
+<b>Returns:</b>
+
+`void`
+

docs/development/plugins/expressions/public/kibana-plugin-plugins-expressions-public.execution.cast.md

@@ -0,0 +1,23 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-plugins-expressions-public](./kibana-plugin-plugins-expressions-public.md) &gt; [Execution](./kibana-plugin-plugins-expressions-public.execution.md) &gt; [cast](./kibana-plugin-plugins-expressions-public.execution.cast.md)
+
+## Execution.cast() method
+
+<b>Signature:</b>
+
+```typescript
+cast(value: any, toTypeNames?: string[]): any;
+```
+
+## Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  value | <code>any</code> |  |
+|  toTypeNames | <code>string[]</code> |  |
+
+<b>Returns:</b>
+
+`any`
+

docs/development/plugins/expressions/public/kibana-plugin-plugins-expressions-public.execution.context.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-plugins-expressions-public](./kibana-plugin-plugins-expressions-public.md) &gt; [Execution](./kibana-plugin-plugins-expressions-public.execution.md) &gt; [context](./kibana-plugin-plugins-expressions-public.execution.context.md)
+
+## Execution.context property
+
+Execution context - object that allows to do side-effects. Context is passed to every function.
+
+<b>Signature:</b>
+
+```typescript
+readonly context: ExecutionContext<Input, InspectorAdapters> & ExtraContext;
+```

docs/development/plugins/expressions/public/kibana-plugin-plugins-expressions-public.execution.contract.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-plugins-expressions-public](./kibana-plugin-plugins-expressions-public.md) &gt; [Execution](./kibana-plugin-plugins-expressions-public.execution.md) &gt; [contract](./kibana-plugin-plugins-expressions-public.execution.contract.md)
+
+## Execution.contract property
+
+Contract is a public representation of `Execution` instances. Contract we can return to other plugins for their consumption.
+
+<b>Signature:</b>
+
+```typescript
+readonly contract: ExecutionContract<ExtraContext, Input, Output, InspectorAdapters>;
+```

docs/development/plugins/expressions/public/kibana-plugin-plugins-expressions-public.execution.expression.md

@@ -0,0 +1,11 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-plugins-expressions-public](./kibana-plugin-plugins-expressions-public.md) &gt; [Execution](./kibana-plugin-plugins-expressions-public.execution.md) &gt; [expression](./kibana-plugin-plugins-expressions-public.execution.expression.md)
+
+## Execution.expression property
+
+<b>Signature:</b>
+
+```typescript
+readonly expression: string;
+```