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,