[Canvas] Update canvas function docs to match in app and vice versa (#125259)

* Update canvas function docs to match in app and vice versa

* Update src/plugins/expressions/common/expression_functions/specs/math_column.ts

Co-authored-by: Catherine Liu <catherineqliu@outlook.com>

* Update src/plugins/expressions/common/expression_functions/specs/math_column.ts

Co-authored-by: Catherine Liu <catherineqliu@outlook.com>

* Fix translations

Co-authored-by: Kaarina Tungseth <kaarina.tungseth@elastic.co>
Co-authored-by: Catherine Liu <catherineqliu@outlook.com>
Co-authored-by: Kibana Machine <42973632+kibanamachine@users.noreply.github.com>

src/plugins/expressions/common/expression_functions/specs/clog.ts

@@ -13,7 +13,7 @@ export type ExpressionFunctionClog = ExpressionFunctionDefinition<'clog', unknow
 export const clog: ExpressionFunctionClog = {
   name: 'clog',
   args: {},
-  help: 'Outputs the context to the console',
+  help: 'Outputs the _input_ in the console. This function is for debug purposes',
   fn: (input: unknown) => {
     // eslint-disable-next-line no-console
     console.log(input);

src/plugins/expressions/common/expression_functions/specs/math_column.ts

@@ -28,12 +28,11 @@ export const mathColumn: ExpressionFunctionDefinition<
   inputTypes: ['datatable'],
   help: i18n.translate('expressions.functions.mathColumnHelpText', {
     defaultMessage:
-      'Adds a column calculated as the result of other columns. ' +
-      'Changes are made only when you provide arguments.' +
-      'See also {alterColumnFn} and {staticColumnFn}.',
+      'Adds a column by evaluating {tinymath} on each row. ' +
+      'This function is optimized for math and performs better than using a math expression in {mapColumnFn}.',
     values: {
-      alterColumnFn: '`alterColumn`',
-      staticColumnFn: '`staticColumn`',
+      mapColumnFn: '`mapColumn`',
+      tinymath: '`TinyMath`',
     },
   }),
   args: {

x-pack/plugins/canvas/i18n/functions/dict/alter_column.ts

@@ -15,7 +15,7 @@ export const help: FunctionHelp<FunctionFactory<typeof alterColumn>> = {
   help: i18n.translate('xpack.canvas.functions.alterColumnHelpText', {
     defaultMessage:
       'Converts between core types, including {list}, and {end}, and renames columns. ' +
-      'See also {mapColumnFn} and {staticColumnFn}.',
+      'See also {mapColumnFn}, {mathColumnFn}, and {staticColumnFn}.',
     values: {
       list: Object.values(DATATABLE_COLUMN_TYPES)
         .slice(0, -1)
@@ -24,6 +24,7 @@ export const help: FunctionHelp<FunctionFactory<typeof alterColumn>> = {
       end: `\`${Object.values(DATATABLE_COLUMN_TYPES).slice(-1)[0]}\``,
       mapColumnFn: '`mapColumn`',
       staticColumnFn: '`staticColumn`',
+      mathColumnFn: '`mathColumn`',
     },
   }),
   args: {

x-pack/plugins/canvas/i18n/functions/dict/static_column.ts

@@ -13,10 +13,11 @@ import { FunctionFactory } from '../../../types';
 export const help: FunctionHelp<FunctionFactory<typeof staticColumn>> = {
   help: i18n.translate('xpack.canvas.functions.staticColumnHelpText', {
     defaultMessage:
-      'Adds a column with the same static value in every row. See also {alterColumnFn} and {mapColumnFn}.',
+      'Adds a column with the same static value in every row. See also {alterColumnFn}, {mapColumnFn}, and {mathColumnFn}',
     values: {
       alterColumnFn: '`alterColumn`',
       mapColumnFn: '`mapColumn`',
+      mathColumnFn: '`mathColumn`',
     },
   }),
   args: {

x-pack/plugins/canvas/public/components/function_reference_generator/function_examples.ts

@@ -134,6 +134,20 @@ case if={lte 50} then="green"`,
       help: 'This sets the color of the progress indicator and the color of the label to `"green"` if the value is less than or equal to `0.5`, `"orange"` if the value is greater than `0.5` and less than or equal to `0.75`, and `"red"` if `none` of the case conditions are met.',
     },
   },
+  clog: {
+    syntax: `clog`,
+    usage: {
+      expression: `kibana
+| demodata
+| clog
+| filterrows fn={getCell "age" | gt 70}
+| clog
+| pointseries x="time" y="mean(price)"
+| plot defaultStyle={seriesStyle lines=1 fill=1}
+| render`,
+      help: 'This prints the `datatable` objects in the browser console before and after the `filterrows` function.',
+    },
+  },
   columns: {
     syntax: `columns include="@timestamp, projects, cost"
 columns exclude="username, country, age"`,
@@ -199,6 +213,23 @@ containerStyle backgroundImage={asset id=asset-f40d2292-cf9e-4f2c-8c6f-a504a25e9
       help: 'Using the `context` function allows us to pass the output, or _context_, of the previous function as a value to an argument in the next function. Here we get the formatted date string from the previous function and pass it as `content` for the markdown element.',
     },
   },
+  createTable: {
+    syntax: `createTable id="a" id="b"    
+createTable id="a" name="A" id="b" name="B" rowCount=5`,
+    usage: {
+      expression: `var_set
+name="logs" value={essql "select count(*) as a from kibana_sample_data_logs"}
+name="commerce" value={essql "select count(*) as b from kibana_sample_data_ecommerce"}
+| createTable ids="totalA" ids="totalB"
+| staticColumn name="totalA" value={var "logs" | getCell "a"}
+| alterColumn column="totalA" type="number"
+| staticColumn name="totalB" value={var "commerce" | getCell "b"}
+| alterColumn column="totalB" type="number"
+| mathColumn id="percent" name="percent" expression="totalA / totalB"
+| render`,
+      help: 'This creates a table based on the results of two `essql` queries, joined into one table.',
+    },
+  },
   csv: {
     syntax: `csv "fruit, stock
   kiwi, 10

x-pack/plugins/canvas/public/components/function_reference_generator/generate_function_reference.ts

@@ -26,12 +26,32 @@ const fnList = [
   ...browserFunctions.map((fn) => fn().name),
   ...serverFunctions.map((fn) => fn().name),
   'asset',
+  'clog',
+  'createTable',
+  'embeddable',
   'filters',
+  'font',
+  'image',
+  'kibana',
+  'mapColumn',
+  'math',
+  'mathColumn',
+  'metric',
+  'palette',
+  'pie',
+  'plot',
+  'progress',
+  'removeFilter',
+  'repeatImage',
+  'revealImage',
+  'selectFilter',
+  'shape',
   'timelion',
   'to',
-  'font',
+  'uiSetting',
   'var',
   'var_set',
+
   // ignore unsupported embeddables functions for now
 ].filter((fn) => !['savedSearch'].includes(fn));
 

x-pack/plugins/translations/translations/ja-JP.json

@@ -3226,7 +3226,6 @@
     "expressions.functions.mathColumn.args.nameHelpText": "結果の列の名前です。名前は一意である必要はありません。",
     "expressions.functions.mathColumn.arrayValueError": "{name}で配列値に対する演算を実行できません",
     "expressions.functions.mathColumn.uniqueIdError": "IDは一意でなければなりません",
-    "expressions.functions.mathColumnHelpText": "他の列の結果として計算された列を追加します。引数が指定された場合のみ変更が加えられます。{alterColumnFn}と{staticColumnFn}もご参照ください。",
     "expressions.functions.mathHelpText": "{TYPE_NUMBER}または{DATATABLE}を{CONTEXT}として使用して、{TINYMATH}数式を解釈します。{DATATABLE}列は列名で表示されます。{CONTEXT}が数字の場合は、{value}と表示されます。",
     "expressions.functions.movingAverage.args.byHelpText": "移動平均計算を分割する列",
     "expressions.functions.movingAverage.args.inputColumnIdHelpText": "移動平均を計算する列",
@@ -8086,7 +8085,6 @@
     "xpack.canvas.functions.alterColumn.args.typeHelpText": "列の変換語のタイプです。タイプを変更しない場合は未入力のままにします。",
     "xpack.canvas.functions.alterColumn.cannotConvertTypeErrorMessage": "「{type}」に変換できません",
     "xpack.canvas.functions.alterColumn.columnNotFoundErrorMessage": "列が見つかりません。'{column}'",
-    "xpack.canvas.functions.alterColumnHelpText": "{list}、{end}などのコアタイプを変換し、列名を変更します。{mapColumnFn}および{staticColumnFn}も参照してください。",
     "xpack.canvas.functions.any.args.conditionHelpText": "確認する条件です。",
     "xpack.canvas.functions.anyHelpText": "少なくとも 1 つの条件が満たされている場合、{BOOLEAN_TRUE} が返されます。{all_fn} もご参照ください。",
     "xpack.canvas.functions.as.args.nameHelpText": "列に付ける名前です。",
@@ -8287,7 +8285,6 @@
     "xpack.canvas.functions.sortHelpText": "{DATATABLE}を指定された列で並べ替えます。",
     "xpack.canvas.functions.staticColumn.args.nameHelpText": "新しい列の名前です。",
     "xpack.canvas.functions.staticColumn.args.valueHelpText": "新しい列の各行に挿入する値です。ヒント：部分式を使用して他の列を静的値にロールアップします。",
-    "xpack.canvas.functions.staticColumnHelpText": "すべての行に同じ静的値の列を追加します。{alterColumnFn}および{mapColumnFn}も参照してください。",
     "xpack.canvas.functions.string.args.valueHelpText": "1 つの文字列に結合する値です。必要な場所にスペースを入れてください。",
     "xpack.canvas.functions.stringHelpText": "すべての引数を 1 つの文字列に連結させます。",
     "xpack.canvas.functions.switch.args.caseHelpText": "確認する条件です。",

x-pack/plugins/translations/translations/zh-CN.json

@@ -3234,7 +3234,6 @@
     "expressions.functions.mathColumn.args.nameHelpText": "结果列的名称。名称不需要唯一。",
     "expressions.functions.mathColumn.arrayValueError": "无法对 {name} 的数组值执行数学运算",
     "expressions.functions.mathColumn.uniqueIdError": "ID 必须唯一",
-    "expressions.functions.mathColumnHelpText": "添加计算为其他列的结果的列。只有提供参数时，才会执行更改。另请参见 {alterColumnFn} 和 {staticColumnFn}。",
     "expressions.functions.mathHelpText": "使用 {TYPE_NUMBER} 或 {DATATABLE} 作为 {CONTEXT} 来解释 {TINYMATH} 数学表达式。{DATATABLE} 列按列名使用。如果 {CONTEXT} 是数字，则作为 {value} 使用。",
     "expressions.functions.movingAverage.args.byHelpText": "用于移动平均值计算拆分依据的列",
     "expressions.functions.movingAverage.args.inputColumnIdHelpText": "要计算移动平均值的列",
@@ -8104,7 +8103,6 @@
     "xpack.canvas.functions.alterColumn.args.typeHelpText": "将列转换成的类型。留空将不更改类型。",
     "xpack.canvas.functions.alterColumn.cannotConvertTypeErrorMessage": "无法转换为“{type}”",
     "xpack.canvas.functions.alterColumn.columnNotFoundErrorMessage": "找不到列：“{column}”",
-    "xpack.canvas.functions.alterColumnHelpText": "在核心类型（包括 {list} 和 {end}）之间转换，并重命名列。另请参见 {mapColumnFn} 和 {staticColumnFn}。",
     "xpack.canvas.functions.any.args.conditionHelpText": "要检查的条件。",
     "xpack.canvas.functions.anyHelpText": "至少满足一个条件时，返回 {BOOLEAN_TRUE}。另见 {all_fn}。",
     "xpack.canvas.functions.as.args.nameHelpText": "要为列提供的名称。",
@@ -8306,7 +8304,6 @@
     "xpack.canvas.functions.sortHelpText": "按指定列对 {DATATABLE} 进行排序。",
     "xpack.canvas.functions.staticColumn.args.nameHelpText": "新列的名称。",
     "xpack.canvas.functions.staticColumn.args.valueHelpText": "要在新列的每一行中插入的值。提示：使用子表达式可将其他列汇总为静态值。",
-    "xpack.canvas.functions.staticColumnHelpText": "添加每一行都具有相同静态值的列。另请参见 {alterColumnFn} 和 {mapColumnFn}。",
     "xpack.canvas.functions.string.args.valueHelpText": "要连结成一个字符串的值。根据需要加入空格。",
     "xpack.canvas.functions.stringHelpText": "将所有参数串联成单个字符串。",
     "xpack.canvas.functions.switch.args.caseHelpText": "要检查的条件。",