|
| 1 | +--- |
| 2 | +id: kibDevTutorialExpressions |
| 3 | +slug: /kibana-dev-docs/tutorials/expressions |
| 4 | +title: Kibana Expressions Service |
| 5 | +summary: Kibana Expressions Service |
| 6 | +date: 2021-06-01 |
| 7 | +tags: ['kibana', 'onboarding', 'dev', 'architecture'] |
| 8 | +--- |
| 9 | + |
| 10 | +## Expressions service |
| 11 | + |
| 12 | +Expression service exposes a registry of reusable functions primary used for fetching and transposing data and a registry of renderer functions that can render data into a DOM element. |
| 13 | +Adding functions is easy and so is reusing them. An expression is a chain of functions with provided arguments, which given a single input translates to a single output. |
| 14 | +Each expression is representable by a human friendly string which a user can type. |
| 15 | + |
| 16 | +### creating expressions |
| 17 | + |
| 18 | +Here is a very simple expression string: |
| 19 | + |
| 20 | + essql 'select column1, column2 from myindex' | mapColumn name=column3 fn='{ column1 + 3 }' | table |
| 21 | + |
| 22 | + |
| 23 | +It consists of 3 functions: |
| 24 | + |
| 25 | + - essql which runs given sql query against elasticsearch and returns the results |
| 26 | + - `mapColumn`, which computes a new column from existing ones; |
| 27 | + - `table`, which prepares the data for rendering in a tabular format. |
| 28 | + |
| 29 | +The same expression could also be constructed in the code: |
| 30 | + |
| 31 | +```ts |
| 32 | +import { buildExpression, buildExpressionFunction } from 'src/plugins/expressions'; |
| 33 | + |
| 34 | +const expression = buildExpression([ |
| 35 | + buildExpressionFunction<ExpressionFunctionEssql>('essql', [ q: 'select column1, column2 from myindex' ]), |
| 36 | + buildExpressionFunction<ExpressionFunctionMapColumn>('mapColumn', [ name: 'column3', expression: 'column1 + 3' ]), |
| 37 | + buildExpressionFunction<ExpressionFunctionTable>('table'), |
| 38 | +] |
| 39 | +``` |
| 40 | +
|
| 41 | +Note: Consumers need to be aware which plugin registers specific functions with expressions function registry and import correct type definitions from there. |
| 42 | +
|
| 43 | +<DocCallOut title="Server Side Search"> |
| 44 | + The `expressions` service is available on both server and client, with similar APIs. |
| 45 | +</DocCallOut> |
| 46 | +
|
| 47 | +### Running expressions |
| 48 | +
|
| 49 | +Expression service exposes `execute` method which allows you to execute an expression: |
| 50 | +
|
| 51 | +```ts |
| 52 | +const executionContract = expressions.execute(expression, input); |
| 53 | +const result = await executionContract.getData(); |
| 54 | +``` |
| 55 | +
|
| 56 | +<DocCallOut title="Server Side Search"> |
| 57 | + Check the full spec of execute function [here](https://github.com/elastic/kibana/blob/master/docs/development/plugins/expressions/public/kibana-plugin-plugins-expressions-public.execution.md) |
| 58 | +</DocCallOut> |
| 59 | +
|
| 60 | +In addition, on the browser side, there are two additional ways to run expressions and render the results. |
| 61 | +
|
| 62 | +#### React expression renderer component |
| 63 | +
|
| 64 | +This is the easiest way to get expressions rendered inside your application. |
| 65 | +
|
| 66 | +```ts |
| 67 | +<ReactExpressionRenderer expression={expression} /> |
| 68 | +``` |
| 69 | +
|
| 70 | +<DocCallOut title="Server Side Search"> |
| 71 | + Check the full spec of ReactExpressionRenderer component props [here](https://github.com/elastic/kibana/blob/master/docs/development/plugins/expressions/public/kibana-plugin-plugins-expressions-public.reactexpressionrendererprops.md) |
| 72 | +</DocCallOut> |
| 73 | +
|
| 74 | +#### Expression loader |
| 75 | +
|
| 76 | +If you are not using React, you can use the loader expression service provides to achieve the same: |
| 77 | +
|
| 78 | +```ts |
| 79 | +const handler = loader(domElement, expression, params); |
| 80 | +``` |
| 81 | +
|
| 82 | +<DocCallOut title="Server Side Search"> |
| 83 | + Check the full spec of expression loader params [here](https://github.com/elastic/kibana/blob/master/docs/development/plugins/expressions/public/kibana-plugin-plugins-expressions-public.iexpressionloaderparams.md) |
| 84 | +</DocCallOut> |
| 85 | +
|
| 86 | +### Creating new expression functions |
| 87 | +
|
| 88 | +Creating a new expression function is easy, just call `registerFunction` method on expressions service setup contract with your function definition: |
| 89 | +
|
| 90 | +```ts |
| 91 | +const functionDefinition = { |
| 92 | + name: 'clog', |
| 93 | + args: {}, |
| 94 | + help: 'Outputs the context to the console', |
| 95 | + fn: (input: unknown) => { |
| 96 | + // eslint-disable-next-line no-console |
| 97 | + console.log(input); |
| 98 | + return input; |
| 99 | + }, |
| 100 | +}; |
| 101 | + |
| 102 | +expressions.registerFunction(functionDefinition); |
| 103 | +``` |
| 104 | +
|
| 105 | +<DocCallOut title="Server Side Search"> |
| 106 | + Check the full interface of ExpressionFuntionDefinition [here](https://github.com/elastic/kibana/blob/master/docs/development/plugins/expressions/public/kibana-plugin-plugins-expressions-public.expressionfunctiondefinition.md) |
| 107 | +</DocCallOut> |
| 108 | +
|
| 109 | +### Creating new expression renderers |
| 110 | +
|
| 111 | +Adding new renderers is just as easy as adding functions: |
| 112 | +
|
| 113 | +```ts |
| 114 | +const rendererDefinition = { |
| 115 | + name: 'debug', |
| 116 | + help: 'Outputs the context to the dom element', |
| 117 | + render: (domElement, input, handlers) => { |
| 118 | + // eslint-disable-next-line no-console |
| 119 | + domElement.innerText = JSON.strinfigy(input); |
| 120 | + handlers.done(); |
| 121 | + }, |
| 122 | +}; |
| 123 | + |
| 124 | +expressions.registerRenderer(rendererDefinition); |
| 125 | +``` |
| 126 | +
|
| 127 | +<DocCallOut title="Server Side Search"> |
| 128 | + Check the full interface of ExpressionRendererDefinition [here](https://github.com/elastic/kibana/blob/master/docs/development/plugins/expressions/public/kibana-plugin-plugins-expressions-public.expressionrenderdefinition.md) |
| 129 | +</DocCallOut> |
0 commit comments