diff --git a/src/plugins/unified_search/public/query_string_input/text_based_languages_editor/esql_documentation_sections.tsx b/src/plugins/unified_search/public/query_string_input/text_based_languages_editor/esql_documentation_sections.tsx index 6b8a3b350b427..a3984d37814c5 100644 --- a/src/plugins/unified_search/public/query_string_input/text_based_languages_editor/esql_documentation_sections.tsx +++ b/src/plugins/unified_search/public/query_string_input/text_based_languages_editor/esql_documentation_sections.tsx @@ -14,45 +14,47 @@ export const initialSection = ( markdown={i18n.translate( 'unifiedSearch.query.textBasedLanguagesEditor.documentationESQL.markdown', { - defaultMessage: `## How it works -Elasticsearch ESQL is a piped language where you can combine aggregations, filters, transformations, and projections in a single expression. - -ESQL query example: - + defaultMessage: `## ESQL + +An ESQL (Elasticsearch query language) query consists of a series of commands, separated by pipe characters: \`|\`. Each query starts with a **source command**, which produces a table, typically with data from Elasticsearch. + +A source command can be followed by one or more **processing commands**. Processing commands can change the output table of the previous command by adding, removing, and changing rows and columns. + \`\`\` -from index | stats average = avg(field) by field2 +source-command +| processing-command1 +| processing-command2 \`\`\` - + +The result of a query is the table produced by the final processing command. `, } )} /> ); -export const commands = { - label: i18n.translate('unifiedSearch.query.textBasedLanguagesEditor.commands', { - defaultMessage: 'Commands', +export const sourceCommands = { + label: i18n.translate('unifiedSearch.query.textBasedLanguagesEditor.sourceCommands', { + defaultMessage: 'Source commands', }), description: i18n.translate('unifiedSearch.query.textBasedLanguagesEditor.commandsDescription', { - defaultMessage: `To create Elasticsearch ESQL expressions, use the supported commands.`, + defaultMessage: `A source command produces a table, typically with data from Elasticsearch. ESQL supports the following source commands.`, }), items: [ { label: i18n.translate('unifiedSearch.query.textBasedLanguagesEditor.documentation.from', { - defaultMessage: 'from', + defaultMessage: 'FROM', }), description: ( + ), + }, + { + label: i18n.translate('unifiedSearch.query.textBasedLanguagesEditor.documentation.show', { + defaultMessage: 'SHOW', + }), + description: ( + \` source command returns information about the deployment and its capabilities: + +* Use \`SHOW INFO\` to return the deployment's version, build date and hash. +* Use \`SHOW FUNCTIONS\` to return a list of all supported functions and a synopsis of each function. + `, + description: + 'Text is in markdown. Do not translate function names, special characters, or field names like sum(bytes)', + } + )} + /> + ), + }, + ], +}; + +export const processingCommands = { + label: i18n.translate('unifiedSearch.query.textBasedLanguagesEditor.processingCommands', { + defaultMessage: 'Processing commands', + }), + description: i18n.translate( + 'unifiedSearch.query.textBasedLanguagesEditor.processingCommandsDescription', + { + defaultMessage: `Processing commands change an input table by adding, removing, or changing rows and columns. ESQL supports the following processing commands.`, + } + ), + items: [ + { + label: i18n.translate('unifiedSearch.query.textBasedLanguagesEditor.documentation.dissect', { + defaultMessage: 'DISSECT', + }), + description: ( + + ), + }, + { + label: i18n.translate('unifiedSearch.query.textBasedLanguagesEditor.documentation.drop', { + defaultMessage: 'DROP', + }), + description: ( + specified. -For example, to fetch only the top 10 results: + defaultMessage: `### LIMIT +The \`LIMIT\` processing command enables you to limit the number of rows: \`\`\` -from index | limit 10 +FROM employees +| LIMIT 5 \`\`\` `, description: @@ -158,20 +273,36 @@ from index | limit 10 ), }, { - label: i18n.translate('unifiedSearch.query.textBasedLanguagesEditor.documentation.where', { - defaultMessage: 'where', + label: i18n.translate('unifiedSearch.query.textBasedLanguagesEditor.documentation.project', { + defaultMessage: 'PROJECT', }), description: ( to filter search results. A predicate expression, when evaluated, returns TRUE or FALSE. The where command only returns the results that evaluate to TRUE. -For example, to filter results for a specific field value: + defaultMessage: `### PROJECT +The \`PROJECT\` command enables you to specify what columns are returned and the order in which they are returned. + +To limit the columns that are returned, use a comma-separated list of column names. The columns are returned in the specified order: \`\`\` -from index where field="value" +FROM employees +| PROJECT first_name, last_name, height +\`\`\` + +Rather than specify each column by name, you can use wildcards to return all columns with a name that matches a pattern: + +\`\`\` +FROM employees +| PROJECT h* +\`\`\` + +The asterisk wildcard (\`*\`) by itself translates to all columns that do not match the other arguments. This query will first return all columns with a name that starts with an h, followed by all other columns: + +\`\`\` +FROM employees +| PROJECT h*, * \`\`\` `, description: @@ -181,39 +312,191 @@ from index where field="value" /> ), }, - ], -}; + { + label: i18n.translate('unifiedSearch.query.textBasedLanguagesEditor.documentation.rename', { + defaultMessage: 'RENAME', + }), + description: ( + + ), + }, { - defaultMessage: `Supported mathematical functions.`, - } - ), - items: [ + label: i18n.translate('unifiedSearch.query.textBasedLanguagesEditor.documentation.sort', { + defaultMessage: 'SORT', + }), + description: ( + + ), + }, { - label: i18n.translate( - 'unifiedSearch.query.textBasedLanguagesEditor.documentation.roundFunction', - { - defaultMessage: 'round', - } + label: i18n.translate('unifiedSearch.query.textBasedLanguagesEditor.documentation.statsby', { + defaultMessage: 'STATS ... BY', + }), + description: ( + ), + }, + { + label: i18n.translate('unifiedSearch.query.textBasedLanguagesEditor.documentation.where', { + defaultMessage: 'WHERE', + }), description: ( \` + * larger than or equal: \`>=\` + +You can use the following boolean operators: + +* \`AND\` +* \`OR\` +* \`NOT\` + +\`\`\` +FROM employees +| PROJECT first_name, last_name, height, still_hired +| WHERE height > 2 AND NOT still_hired +\`\`\` + +#### Functions +\`WHERE\` supports various functions for calculating values. Refer to Functions for more information. + `, description: 'Text is in markdown. Do not translate function names, special characters, or field names like sum(bytes)', } @@ -224,32 +507,36 @@ eval rounded = round(field) ], }; -export const operators = { - label: i18n.translate('unifiedSearch.query.textBasedLanguagesEditor.operators', { - defaultMessage: 'Operators', +export const functions = { + label: i18n.translate('unifiedSearch.query.textBasedLanguagesEditor.functions', { + defaultMessage: 'Functions', }), description: i18n.translate( - 'unifiedSearch.query.textBasedLanguagesEditor.operatorsDocumentationDescription', + 'unifiedSearch.query.textBasedLanguagesEditor.functionsDocumentationESQLDescription', { - defaultMessage: `Operations you can perform with the eval command.`, + defaultMessage: `Functions are supported by ROW, EVAL and WHERE.`, } ), items: [ { label: i18n.translate( - 'unifiedSearch.query.textBasedLanguagesEditor.documentation.AddOperator', + 'unifiedSearch.query.textBasedLanguagesEditor.documentationESQL.absFunction', { - defaultMessage: 'Add', + defaultMessage: 'ABS', } ), description: ( ), }, - ], -}; - -export const aggregateFunctions = { - label: i18n.translate('unifiedSearch.query.textBasedLanguagesEditor.aggregateFunctions', { - defaultMessage: 'Aggregate functions', - }), - description: i18n.translate( - 'unifiedSearch.query.textBasedLanguagesEditor.aggregateFunctionsDocumentationESQLDescription', - { - defaultMessage: `Calculates aggregate statistics, such as average, count, and sum, over the incoming search results set. This is similar to SQL aggregation.`, - } - ), - items: [ { label: i18n.translate( - 'unifiedSearch.query.textBasedLanguagesEditor.documentationESQL.averageFunction', + 'unifiedSearch.query.textBasedLanguagesEditor.documentation.isNullFunction', { - defaultMessage: 'Average', + defaultMessage: 'IS_NULL', } ), description: ( { }; } if (language === 'esql') { - const { commands, operators, mathematicalFunctions, initialSection, aggregateFunctions } = - await import('./esql_documentation_sections'); + const { sourceCommands, processingCommands, initialSection, functions } = await import( + './esql_documentation_sections' + ); groups.push({ - label: i18n.translate('unifiedSearch.query.textBasedLanguagesEditor.howItWorks', { - defaultMessage: 'How it works', + label: i18n.translate('unifiedSearch.query.textBasedLanguagesEditor.esql', { + defaultMessage: 'ESQL', }), items: [], }); - groups.push(commands, operators, mathematicalFunctions, aggregateFunctions); + groups.push(sourceCommands, processingCommands, functions); return { groups, initialSection,