diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/scripts/evaluation/cli.ts b/x-pack/plugins/observability_solution/observability_ai_assistant_app/scripts/evaluation/cli.ts index 61504b7ea46d2..23fb67f77bbd7 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/scripts/evaluation/cli.ts +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/scripts/evaluation/cli.ts @@ -13,9 +13,29 @@ export enum EvaluateWith { other = 'other', } -export function options(y: Argv) { - const config = readKibanaConfig(); +const config = readKibanaConfig(); + +export const kibanaOption = { + describe: 'Where Kibana is running', + string: true as const, + default: process.env.KIBANA_HOST || 'http://localhost:5601', +}; +export const elasticsearchOption = { + alias: 'es', + describe: 'Where Elasticsearch is running', + string: true as const, + default: format({ + ...parse(config['elasticsearch.hosts']), + auth: `${config['elasticsearch.username']}:${config['elasticsearch.password']}`, + }), +}; + +export const connectorIdOption = { + describe: 'The ID of the connector', + string: true as const, +}; +export function options(y: Argv) { return y .option('files', { string: true as const, @@ -27,30 +47,15 @@ export function options(y: Argv) { array: false, describe: 'A string or regex to filter scenarios by', }) - .option('kibana', { - describe: 'Where Kibana is running', - string: true, - default: process.env.KIBANA_HOST || 'http://localhost:5601', - }) + .option('kibana', kibanaOption) .option('spaceId', { describe: 'The space to use. If space is set, conversations will only be cleared for that spaceId', string: true, array: false, }) - .option('elasticsearch', { - alias: 'es', - describe: 'Where Elasticsearch is running', - string: true, - default: format({ - ...parse(config['elasticsearch.hosts']), - auth: `${config['elasticsearch.username']}:${config['elasticsearch.password']}`, - }), - }) - .option('connectorId', { - describe: 'The ID of the connector', - string: true, - }) + .option('elasticsearch', elasticsearchOption) + .option('connectorId', connectorIdOption) .option('persist', { describe: 'Whether the conversations should be stored. Adding this will generate a link at which the conversation can be opened.', diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/scripts/evaluation/evaluation.ts b/x-pack/plugins/observability_solution/observability_ai_assistant_app/scripts/evaluation/evaluation.ts index 98fe6903ba620..2b1dbf47bcdf5 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/scripts/evaluation/evaluation.ts +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/scripts/evaluation/evaluation.ts @@ -8,7 +8,6 @@ import { Client } from '@elastic/elasticsearch'; import { run } from '@kbn/dev-cli-runner'; import * as fastGlob from 'fast-glob'; -import inquirer from 'inquirer'; import yargs from 'yargs'; import chalk from 'chalk'; import { castArray, omit } from 'lodash'; @@ -18,7 +17,6 @@ import Path from 'path'; import * as table from 'table'; import { TableUserConfig } from 'table'; import { format, parse } from 'url'; -import { ToolingLog } from '@kbn/tooling-log'; import { MessageRole } from '@kbn/observability-ai-assistant-plugin/common'; import { EvaluateWith, options } from './cli'; import { getServiceUrls } from './get_service_urls'; @@ -26,40 +24,7 @@ import { KibanaClient } from './kibana_client'; import { initServices } from './services'; import { setupSynthtrace } from './setup_synthtrace'; import { EvaluationResult } from './types'; - -async function selectConnector({ - connectors, - preferredId, - log, - message = 'Select a connector', -}: { - connectors: Awaited>; - preferredId?: string; - log: ToolingLog; - message?: string; -}) { - let connector = connectors.find((item) => item.id === preferredId); - - if (!connector && preferredId) { - log.warning(`Could not find connector ${preferredId}`); - } - - if (!connector && connectors.length === 1) { - connector = connectors[0]; - log.debug('Using the only connector found'); - } else if (!connector) { - const connectorChoice = await inquirer.prompt({ - type: 'list', - name: 'connector', - message, - choices: connectors.map((item) => ({ name: `${item.name} (${item.id})`, value: item.id })), - }); - - connector = connectors.find((item) => item.id === connectorChoice.connector)!; - } - - return connector; -} +import { selectConnector } from './select_connector'; function runEvaluations() { yargs(process.argv.slice(2)) diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/scripts/evaluation/get_service_urls.ts b/x-pack/plugins/observability_solution/observability_ai_assistant_app/scripts/evaluation/get_service_urls.ts index ce909c7a97394..859b47987a470 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/scripts/evaluation/get_service_urls.ts +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/scripts/evaluation/get_service_urls.ts @@ -117,10 +117,6 @@ export async function getServiceUrls({ elasticsearch = 'http://127.0.0.1:9200'; } - if (!elasticsearch) { - throw new Error('Could not determine an Elasticsearch target'); - } - const parsedTarget = parse(elasticsearch); let auth = parsedTarget.auth; diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/scripts/evaluation/kibana_client.ts b/x-pack/plugins/observability_solution/observability_ai_assistant_app/scripts/evaluation/kibana_client.ts index 0de3d3cebabe3..b81cacc6d565e 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/scripts/evaluation/kibana_client.ts +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/scripts/evaluation/kibana_client.ts @@ -45,10 +45,7 @@ import { } from 'rxjs'; import { format, parse, UrlObject } from 'url'; import { inspect } from 'util'; -import type { - ObservabilityAIAssistantAPIClientRequestParamsOf, - APIReturnType, -} from '@kbn/observability-ai-assistant-plugin/public'; +import type { ObservabilityAIAssistantAPIClientRequestParamsOf } from '@kbn/observability-ai-assistant-plugin/public'; import { EvaluationResult } from './types'; // eslint-disable-next-line spaced-comment @@ -171,7 +168,7 @@ export class KibanaClient { connectorId: string; evaluationConnectorId: string; persist: boolean; - suite: Mocha.Suite; + suite?: Mocha.Suite; }): ChatClient { function getMessages(message: string | Array): Array { if (typeof message === 'string') { @@ -187,34 +184,25 @@ export class KibanaClient { const that = this; - async function getFunctions() { - const { - data: { functionDefinitions }, - }: AxiosResponse> = - await that.axios.get( - that.getUrl({ pathname: '/internal/observability_ai_assistant/functions' }) - ); - - return { functionDefinitions }; - } - let currentTitle: string = ''; - suite.beforeEach(function () { - const currentTest: Mocha.Test = this.currentTest; - const titles: string[] = []; - titles.push(this.currentTest.title); - let parent = currentTest.parent; - while (parent) { - titles.push(parent.title); - parent = parent.parent; - } - currentTitle = titles.reverse().join(' '); - }); + if (suite) { + suite.beforeEach(function () { + const currentTest: Mocha.Test = this.currentTest; + const titles: string[] = []; + titles.push(this.currentTest.title); + let parent = currentTest.parent; + while (parent) { + titles.push(parent.title); + parent = parent.parent; + } + currentTitle = titles.reverse().join(' '); + }); - suite.afterEach(function () { - currentTitle = ''; - }); + suite.afterEach(function () { + currentTitle = ''; + }); + } const onResultCallbacks: Array<{ callback: (result: EvaluationResult) => void; @@ -246,13 +234,12 @@ export class KibanaClient { { message: error.message, status: error.status, - response: error.response?.data, }, { depth: 10 } ) ); } else { - that.log.error(inspect(error, { depth: 10 })); + that.log.error(inspect(error, { depth: 5 })); } if ( @@ -329,14 +316,13 @@ export class KibanaClient { return { chat: async (message) => { - const { functionDefinitions } = await getFunctions(); const messages = [ ...getMessages(message).map((msg) => ({ message: msg, '@timestamp': new Date().toISOString(), })), ]; - return chat('chat', { messages, functions: functionDefinitions }); + return chat('chat', { messages, functions: [] }); }, complete: async (...args) => { that.log.info(`Complete`); diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/scripts/evaluation/scenarios/esql/index.spec.ts b/x-pack/plugins/observability_solution/observability_ai_assistant_app/scripts/evaluation/scenarios/esql/index.spec.ts index 3bd6fc6a0c207..e4467f1d078de 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/scripts/evaluation/scenarios/esql/index.spec.ts +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/scripts/evaluation/scenarios/esql/index.spec.ts @@ -29,7 +29,7 @@ async function evaluateEsqlQuery({ ...(expected ? [ `Returns a ES|QL query that is functionally equivalent to: - ${expected}`, + ${expected}. It's OK if column names are slightly different, as long as the expected end result is the same.`, ] : []), ...(execute @@ -90,7 +90,7 @@ describe('ES|QL query generation', () => { it('top 10 unique domains', async () => { await evaluateEsqlQuery({ question: - 'For standard Elastic ECS compliant packetbeat data view, shows the top 10 unique destination.domain with more docs', + 'For standard Elastic ECS compliant packetbeat data view, show me the top 10 unique destination.domain with the most docs', expected: `FROM packetbeat-* | STATS doc_count = COUNT(*) BY destination.domain | SORT doc_count DESC diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/scripts/evaluation/select_connector.ts b/x-pack/plugins/observability_solution/observability_ai_assistant_app/scripts/evaluation/select_connector.ts new file mode 100644 index 0000000000000..f2aecfabdba76 --- /dev/null +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/scripts/evaluation/select_connector.ts @@ -0,0 +1,44 @@ +/* + * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one + * or more contributor license agreements. Licensed under the Elastic License + * 2.0; you may not use this file except in compliance with the Elastic License + * 2.0. + */ + +import inquirer from 'inquirer'; +import { ToolingLog } from '@kbn/tooling-log'; +import { KibanaClient } from './kibana_client'; + +export async function selectConnector({ + connectors, + preferredId, + log, + message = 'Select a connector', +}: { + connectors: Awaited>; + preferredId?: string; + log: ToolingLog; + message?: string; +}) { + let connector = connectors.find((item) => item.id === preferredId); + + if (!connector && preferredId) { + log.warning(`Could not find connector ${preferredId}`); + } + + if (!connector && connectors.length === 1) { + connector = connectors[0]; + log.debug('Using the only connector found'); + } else if (!connector) { + const connectorChoice = await inquirer.prompt({ + type: 'list', + name: 'connector', + message, + choices: connectors.map((item) => ({ name: `${item.name} (${item.id})`, value: item.id })), + }); + + connector = connectors.find((item) => item.id === connectorChoice.connector)!; + } + + return connector; +} diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/scripts/load_esql_docs/format_esql_examples.ts b/x-pack/plugins/observability_solution/observability_ai_assistant_app/scripts/load_esql_docs/format_esql_examples.ts deleted file mode 100644 index 4bb578f91f6c1..0000000000000 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/scripts/load_esql_docs/format_esql_examples.ts +++ /dev/null @@ -1,19 +0,0 @@ -/* - * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one - * or more contributor license agreements. Licensed under the Elastic License - * 2.0; you may not use this file except in compliance with the Elastic License - * 2.0. - */ - -export function formatEsqlExamples(content: string) { - // Regular expression to match the queries - const queryRegex = /(\s*(FROM |ROW |SHOW ).*?)(?=\n[^|\s]|$)/gs; - - // Function to format a matched query - const formatQuery = (match: string) => { - return `\n\`\`\`esql\n${match.trim()}\n\`\`\`\n`; - }; - - // Replace all matches in the input string - return content.replace(queryRegex, formatQuery); -} diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/scripts/load_esql_docs/load_esql_docs.ts b/x-pack/plugins/observability_solution/observability_ai_assistant_app/scripts/load_esql_docs/load_esql_docs.ts index 1584afe55063e..b8a90c2b62e46 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/scripts/load_esql_docs/load_esql_docs.ts +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/scripts/load_esql_docs/load_esql_docs.ts @@ -9,28 +9,78 @@ import $, { load } from 'cheerio'; import { SingleBar } from 'cli-progress'; import FastGlob from 'fast-glob'; import Fs from 'fs/promises'; -import { once, partition } from 'lodash'; +import { once, partition, compact } from 'lodash'; import pLimit from 'p-limit'; import Path from 'path'; import git, { SimpleGitProgressEvent } from 'simple-git'; import yargs, { Argv } from 'yargs'; +import { MessageRole } from '@kbn/observability-ai-assistant-plugin/common'; +import { validateQuery } from '@kbn/esql-validation-autocomplete'; +import { EditorError, ESQLMessage, getAstAndSyntaxErrors } from '@kbn/esql-ast'; +import { connectorIdOption, elasticsearchOption, kibanaOption } from '../evaluation/cli'; +import { getServiceUrls } from '../evaluation/get_service_urls'; +import { KibanaClient } from '../evaluation/kibana_client'; +import { selectConnector } from '../evaluation/select_connector'; import { extractSections } from './extract_sections'; -import { formatEsqlExamples } from './format_esql_examples'; +import { correctCommonEsqlMistakes } from '../../server/functions/query/correct_common_esql_mistakes'; +import { INLINE_ESQL_QUERY_REGEX } from '../../server/functions/query/constants'; yargs(process.argv.slice(2)) .command( '*', 'Extract ES|QL documentation for the Observability AI Assistant', (y: Argv) => - y.option('logLevel', { - describe: 'Log level', - string: true, - default: process.env.LOG_LEVEL || 'info', - choices: ['info', 'debug', 'silent', 'verbose'], - }), + y + .option('logLevel', { + describe: 'Log level', + string: true, + default: process.env.LOG_LEVEL || 'info', + choices: ['info', 'debug', 'silent', 'verbose'], + }) + .option('only', { + describe: 'Only regenerate these files', + string: true, + array: true, + }) + .option('dryRun', { + describe: 'Do not write or delete any files', + boolean: true, + default: false, + }) + .option('kibana', kibanaOption) + .option('elasticsearch', elasticsearchOption) + .option('connectorId', connectorIdOption), (argv) => { run( async ({ log }) => { + const serviceUrls = await getServiceUrls({ + log, + elasticsearch: argv.elasticsearch, + kibana: argv.kibana, + }); + + const kibanaClient = new KibanaClient(log, serviceUrls.kibanaUrl); + + const connectors = await kibanaClient.getConnectors(); + + if (!connectors.length) { + throw new Error('No connectors found'); + } + + const connector = await selectConnector({ + connectors, + preferredId: argv.connectorId, + log, + }); + + const chatClient = kibanaClient.createChatClient({ + connectorId: connector.id, + evaluationConnectorId: connector.id, + persist: false, + }); + + log.info(`Using connector ${connector.id}`); + const builtDocsDir = Path.join(__dirname, '../../../../../../../built-docs'); log.debug(`Looking in ${builtDocsDir} for built-docs repository`); @@ -91,144 +141,187 @@ yargs(process.argv.slice(2)) throw new Error('No files found'); } - const limiter = pLimit(10); + const fsLimiter = pLimit(10); stop(); log.info(`Processing ${files.length} files`); - const documents: Array> = await Promise.all( - files.map((file) => - limiter(async () => { - const fileContents = await Fs.readFile(file); - const $element = load(fileContents.toString())('*'); - - function getSimpleText() { - $element.remove('.navfooter'); - $element.remove('#sticky_content'); - $element.find('code').each(function () { - $(this).replaceWith('`' + $(this).text() + '`'); - }); - return $element - .find('.section,section,.part') - .last() - .text() - .replaceAll(/([\n]\s*){2,}/g, '\n'); - } + async function extractContents( + file: string + ): Promise< + Array<{ title: string; content: string; instructions?: string; skip?: boolean }> + > { + const fileContents = await Fs.readFile(file); + const $element = load(fileContents.toString())('*'); + + function getSimpleText() { + $element.remove('.navfooter'); + $element.remove('#sticky_content'); + $element.find('code').each(function () { + $(this).replaceWith('`' + $(this).text() + '`'); + }); + return $element + .find('.section,section,.part') + .last() + .text() + .replaceAll(/([\n]\s*){2,}/g, '\n'); + } - switch (Path.basename(file)) { - case 'esql-commands.html': - return extractSections($element); - - case 'esql-limitations.html': - return [ - { - title: 'Limitations', - content: getSimpleText(), - }, - ]; - - case 'esql-syntax.html': - return [ - { - title: 'Syntax', - content: getSimpleText(), - }, - ]; - case 'esql.html': - return [ - { - title: 'Overview', - content: getSimpleText().replace( - /The ES\|QL documentation is organized in these sections(.*)$/, - '' - ), - }, - ]; - - case 'esql-cross-clusters.html': - return [ - { - title: 'CROSS_CLUSTER', - content: getSimpleText(), - }, - ]; - - case 'esql-query-api.html': - return [ - { - title: 'API', - content: getSimpleText(), - }, - ]; - - case 'esql-kibana.html': - return [ - { - title: 'Kibana', - content: getSimpleText(), - }, - ]; - - case 'esql-functions-operators.html': - const sections = extractSections($element); - - const searches = [ - 'Binary operators', - 'Equality', - 'Inequality', - 'Less than', - 'Greater than', - 'Add +', - 'Subtract -', - 'Multiply *', - 'Divide /', - 'Modulus %', - 'Unary operators', - 'Logical operators', - 'IS NULL', - ]; - - const matches = [ - 'CIDR_MATCH', - 'ENDS_WITH', - 'IN', - 'IS_FINITE', - 'IS_INFINITE', - 'IS_NAN', - 'LIKE', - 'RLIKE', - 'STARTS_WITH', - ]; - - const [operatorSections, allOtherSections] = partition(sections, (section) => { - return ( - matches.includes(section.title) || - searches.some((search) => - section.title.toLowerCase().startsWith(search.toLowerCase()) - ) - ); - }); + switch (Path.basename(file)) { + case 'esql-commands.html': + return extractSections($element) + .filter(({ title }) => !!title.match(/^[A-Z_]+$/)) + .map((doc) => ({ + ...doc, + instructions: `For this command, generate a Markdown document containing the following sections: + + ## {Title} + + {What this command does, the use cases, and any limitations from this document or esql-limitations.txt} + + ### Examples + + {example ES|QL queries using this command. prefer to copy mentioned queries, but make sure there are at least three different examples, focusing on different usages of this command}`, + })); + + case 'esql-limitations.html': + return [ + { + title: 'Limitations', + content: getSimpleText(), + skip: true, + }, + ]; + + case 'esql-syntax.html': + return [ + { + title: 'Syntax', + content: getSimpleText(), + instructions: `Generate a description of ES|QL syntax. Be as complete as possible. + For timespan literals, generate at least five examples of full ES|QL queries, using a mix commands and functions, using different intervals and units. + **Make sure you use timespan literals, such as \`1 day\` or \`24h\` or \`7 weeks\` in these examples**. + Combine ISO timestamps with time span literals and NOW(). + Make sure the example queries are using different combinations of syntax, commands and functions for each. + When using DATE_TRUNC, make sure you DO NOT wrap the timespan in single or double quotes. + Do not use the Cast operator. + `, + }, + ]; + + case 'esql.html': + return [ + { + title: 'Overview', + content: getSimpleText().replace( + /The ES\|QL documentation is organized in these sections(.*)$/, + '' + ), + instructions: `Generate a description of ES|QL as a language. Ignore links to other documents. From Limitations, include the known limitations, but ignore limitations that are specific to a command. + Include a summary of what is mentioned in the CROSS_CLUSTER, Kibana and API sections. Explain how to use the REST API with an example and mention important information for Kibana usage and cross cluster querying.`, + }, + ]; + + case 'esql-cross-clusters.html': + return [ + { + title: 'CROSS_CLUSTER', + content: getSimpleText(), + skip: true, + }, + ]; + + case 'esql-query-api.html': + return [ + { + title: 'API', + content: getSimpleText(), + skip: true, + }, + ]; + + case 'esql-kibana.html': + return [ + { + title: 'Kibana', + content: getSimpleText(), + skip: true, + }, + ]; + + case 'esql-functions-operators.html': + const sections = extractSections($element); + + const searches = [ + 'Binary operators', + 'Equality', + 'Inequality', + 'Less than', + 'Greater than', + 'Add +', + 'Subtract -', + 'Multiply *', + 'Divide /', + 'Modulus %', + 'Unary operators', + 'Logical operators', + 'IS NULL', + 'IS NOT NULL', + 'Cast (::)', + ]; + + const matches = ['IN', 'LIKE', 'RLIKE']; + + const [operatorSections, allOtherSections] = partition(sections, (section) => { + return ( + matches.includes(section.title) || + searches.some((search) => + section.title.toLowerCase().startsWith(search.toLowerCase()) + ) + ); + }); - return allOtherSections.concat({ - title: 'Operators', - content: operatorSections - .map(({ title, content }) => `${title}\n${content}`) - .join('\n'), - }); + return allOtherSections + .map((section) => ({ + ...section, + instructions: `For each function, use the following template: + + ## {Title} + + {description of what this function does} + + ### Examples + + {at least two examples of full ES|QL queries. prefer the ones in the document verbatim} + `, + })) + .concat({ + title: 'Operators', + content: operatorSections + .map(({ title, content }) => `${title}\n${content}`) + .join('\n'), + instructions: + 'Generate a document describing the operators. For each type of operator (binary, unary, logical, and the remaining), generate a section. For each operator, generate at least one full ES|QL query as an example of its usage. Keep it short, e.g. only a ```esql\nFROM ...\n| WHERE ... ```', + }); - default: - log.debug('Dropping file', file); - break; - } - return []; - }) - ) + default: + log.debug('Dropping file', file); + break; + } + return []; + } + + const documents = await Promise.all( + files.map((file) => fsLimiter(() => extractContents(file))) ); const flattened = documents.flat().filter((doc) => { // ES|QL aggregate functions, ES|QL mathematical functions, ES|QL string functions etc - const isOverviewArticle = doc.title.startsWith('ES|QL'); + const isOverviewArticle = + doc.title.startsWith('ES|QL') || + doc.title === 'Functions overview' || + doc.title === 'Operators overview'; if (isOverviewArticle) { log.debug('Dropping overview article', doc.title); @@ -241,36 +334,167 @@ yargs(process.argv.slice(2)) '../../../observability_ai_assistant_app/server/functions/query/esql_docs' ); - log.info(`Writing ${flattened.length} documents to disk to ${outDir}`); - - log.debug(`Clearing ${outDir}`); + if (!argv.dryRun) { + log.info(`Writing ${flattened.length} documents to disk to ${outDir}`); + } - await Fs.rm(outDir, { recursive: true }); + if (!argv.only && !argv.dryRun) { + log.debug(`Clearing ${outDir}`); - await Fs.mkdir(outDir); + await Fs.rm(outDir, { recursive: true }).catch((error) => + error.code === 'ENOENT' ? Promise.resolve() : error + ); + } - await Promise.all( - flattened.map((doc) => - limiter(async () => { - const fileName = Path.join( - outDir, - `esql-${doc.title.replaceAll(' ', '-').toLowerCase()}.txt` + if (!argv.dryRun) { + await Fs.mkdir(outDir).catch((error) => + error.code === 'EEXIST' ? Promise.resolve() : error + ); + } + const chatLimiter = pLimit(10); + + const allContent = flattened + .map((doc) => `## ${doc.title}\n\n${doc.content}\n\(end of ${doc.title})`) + .join('\n\n'); + + const allErrors: Array<{ + title: string; + fileName: string; + errors: Array<{ query: string; errors: Array }>; + }> = []; + + async function writeFile(doc: { title: string; content: string }) { + const fileName = Path.join( + outDir, + `esql-${doc.title.replaceAll(' ', '-').toLowerCase()}.txt` + ); + + doc.content = doc.content.replaceAll(INLINE_ESQL_QUERY_REGEX, (match, query) => { + const correctionResult = correctCommonEsqlMistakes(query); + if (correctionResult.isCorrection) { + log.info( + `Corrected ES|QL, from:\n${correctionResult.input}\nto:\n${correctionResult.output}` ); + } + return '```esql\n' + correctionResult.output + '\n```'; + }); + + const queriesWithSyntaxErrors = compact( + await Promise.all( + Array.from(doc.content.matchAll(INLINE_ESQL_QUERY_REGEX)).map( + async ([match, query]) => { + const { errors, warnings } = await validateQuery(query, getAstAndSyntaxErrors, { + // setting this to true, we don't want to validate the index / fields existence + ignoreOnMissingCallbacks: true, + }); - // We ask the LLM to output queries wrapped in ```esql...```, - // so we try to format ES|QL examples in the docs in the same - // way. The hope is that this creates a stronger relation in the - // output. - const formattedContent = formatEsqlExamples(doc.content); + const all = [...errors, ...warnings]; + if (all.length) { + log.warning( + `Error in ${fileName}:\n${JSON.stringify({ errors, warnings }, null, 2)}` + ); + return { + errors: all, + query, + }; + } + } + ) + ) + ); + + if (queriesWithSyntaxErrors.length) { + allErrors.push({ + title: doc.title, + fileName, + errors: queriesWithSyntaxErrors, + }); + } - log.debug({ - content: doc.content, - formattedContent, - }); + if (!argv.dryRun) { + await Fs.writeFile(fileName, doc.content); + } + } + + await Promise.all( + flattened.map(async (doc) => { + if (doc.skip || (argv.only && !argv.only.includes(doc.title))) { + return undefined; + } + + if (!doc.instructions) { + return fsLimiter(() => writeFile(doc)); + } + + return chatLimiter(async () => { + try { + const response = await chatClient.chat([ + { + role: MessageRole.System, + content: `## System instructions + + Your job is to generate Markdown documentation off of content that is scraped from the Elasticsearch website. + + The documentation is about ES|QL, or the Elasticsearch Query Language, which is a new piped language that can be + used for loading, extracting and transforming data stored in Elasticsearch. The audience for the documentation + you generate, is intended for an LLM, to be able to answer questions about ES|QL or generate and execute ES|QL + queries. + + If you need to generate example queries, make sure they are different, in that they use different commands, and arguments, + to show case how a command, function or operator can be used in different ways. + + When you generate a complete ES|QL query, always wrap it in code blocks with the language being \`esql\`.. Here's an example: + + \`\`\`esql + FROM logs-* + | WHERE @timestamp <= NOW() + \`\`\` + + **If you are describing the syntax of a command, only wrap it in SINGLE backticks. + Leave out the esql part**. Eg: + ### Syntax: + + \`DISSECT input "pattern" [APPEND_SEPARATOR=""]\` + + #### Context + + These is the entire documentation, use it as context for answering questions + + ${allContent} + `, + }, + { + role: MessageRole.User, + content: `Generate Markdown for the following document: + + ## ${doc.title} + + ### Instructions + + ${doc.instructions} + + ### Content of file + + ${doc.content}`, + }, + ]); + + return fsLimiter(() => + writeFile({ title: doc.title, content: response.content! }) + ); + } catch (error) { + log.error(`Error processing ${doc.title}: ${error.message}`); + } + }); + }) + ); - await Fs.writeFile(fileName, formattedContent); - }) - ) + log.warning( + `Please verify the following queries that had syntax errors\n${JSON.stringify( + allErrors, + null, + 2 + )}` ); }, { log: { defaultLevel: argv.logLevel as any }, flags: { allowUnexpected: true } } diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/constants.ts b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/constants.ts new file mode 100644 index 0000000000000..99d7def64d4ff --- /dev/null +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/constants.ts @@ -0,0 +1,8 @@ +/* + * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one + * or more contributor license agreements. Licensed under the Elastic License + * 2.0; you may not use this file except in compliance with the Elastic License + * 2.0. + */ + +export const INLINE_ESQL_QUERY_REGEX = /```esql\s*(.*?)\s*```/gms; diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/correct_common_esql_mistakes.test.ts b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/correct_common_esql_mistakes.test.ts index ffb26e035cf0f..ad8e0f6cfd664 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/correct_common_esql_mistakes.test.ts +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/correct_common_esql_mistakes.test.ts @@ -4,23 +4,15 @@ * 2.0; you may not use this file except in compliance with the Elastic License * 2.0. */ -import dedent from 'dedent'; -import { noop } from 'lodash'; import { correctCommonEsqlMistakes } from './correct_common_esql_mistakes'; describe('correctCommonEsqlMistakes', () => { - const fakeLogger = { - debug: noop, - } as any; - - function renderQuery(query: string) { - return '```esql\n' + dedent(query) + '\n```'; + function normalize(input: string) { + return input.replaceAll(/[\t|\s]*\n[\t|\s]*/gms, '\n'); } function expectQuery(input: string, expectedOutput: string) { - expect(correctCommonEsqlMistakes(renderQuery(input), fakeLogger)).toEqual( - renderQuery(expectedOutput) - ); + expect(normalize(correctCommonEsqlMistakes(input).output)).toEqual(normalize(expectedOutput)); } it('replaces aliasing via the AS keyword with the = operator', () => { @@ -106,6 +98,11 @@ describe('correctCommonEsqlMistakes', () => { `FROM logs-* | KEEP date, whatever | RENAME whatever AS forever | SORT forever DESC`, `FROM logs-*\n| KEEP date, whatever\n| RENAME whatever AS forever\n| SORT forever DESC` ); + + expectQuery( + 'FROM employees\n| KEEP first_name, last_name\n| RENAME first_name AS fn, last_name AS ln', + 'FROM employees\n| KEEP first_name, last_name\n| RENAME first_name AS fn, last_name AS ln' + ); }); it(`escapes the column name if SORT uses an expression`, () => { @@ -118,6 +115,20 @@ describe('correctCommonEsqlMistakes', () => { 'FROM logs-* \n| STATS COUNT(*) by service.name\n| SORT COUNT(*) DESC, @timestamp ASC', 'FROM logs-*\n| STATS COUNT(*) BY service.name\n| SORT `COUNT(*)` DESC, @timestamp ASC' ); + + expectQuery( + `FROM employees\n| KEEP first_name, last_name, height\n| SORT first_name ASC NULLS FIRST`, + `FROM employees\n| KEEP first_name, last_name, height\n| SORT first_name ASC NULLS FIRST` + ); + + expectQuery( + `FROM employees + | STATS my_count = COUNT() BY LEFT(last_name, 1) + | SORT \`LEFT(last_name, 1)\``, + `FROM employees + | STATS my_count = COUNT() BY LEFT(last_name, 1) + | SORT \`LEFT(last_name, 1)\`` + ); }); it(`handles complicated queries correctly`, () => { @@ -140,10 +151,10 @@ describe('correctCommonEsqlMistakes', () => { | EVAL total_events = span.destination.service.response_time.count | EVAL total_latency = span.destination.service.response_time.sum.us | EVAL is_failure = CASE(event.outcome == "failure", 1, 0) - | STATS - avg_throughput = AVG(total_events), - avg_latency_per_request = AVG(total_latency / total_events), - failure_rate = AVG(is_failure) + | STATS + avg_throughput = AVG(total_events), + avg_latency_per_request = AVG(total_latency / total_events), + failure_rate = AVG(is_failure) BY span.destination.service.resource`, `FROM metrics-apm* | WHERE metricset.name == "service_destination" AND @timestamp > NOW() - 24 hours @@ -152,5 +163,20 @@ describe('correctCommonEsqlMistakes', () => { | EVAL is_failure = CASE(event.outcome == "failure", 1, 0) | STATS avg_throughput = AVG(total_events), avg_latency_per_request = AVG(total_latency / total_events), failure_rate = AVG(is_failure) BY span.destination.service.resource` ); + + expectQuery( + `FROM sample_data + | EVAL successful = CASE( + STARTS_WITH(message, "Connected to"), 1, + message == "Connection error", 0 + ) + | STATS success_rate = AVG(successful)`, + `FROM sample_data + | EVAL successful = CASE( + STARTS_WITH(message, "Connected to"), 1, + message == "Connection error", 0 + ) + | STATS success_rate = AVG(successful)` + ); }); }); diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/correct_common_esql_mistakes.ts b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/correct_common_esql_mistakes.ts index 4c20f979a42d7..73f2d31b4b35b 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/correct_common_esql_mistakes.ts +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/correct_common_esql_mistakes.ts @@ -5,10 +5,7 @@ * 2.0. */ -import { isArray } from 'lodash'; -import type { Logger } from '@kbn/logging'; - -const DELIMITER_TOKENS = ['`', "'", '"', ['(', ')']]; +const STRING_DELIMITER_TOKENS = ['`', "'", '"']; const ESCAPE_TOKEN = '\\\\'; // this function splits statements by a certain token, @@ -18,6 +15,9 @@ function split(value: string, splitToken: string) { const statements: string[] = []; let delimiterToken: string | undefined; + + let groupingCount: number = 0; + let currentStatement: string = ''; const trimmed = value.trim().split(''); @@ -27,6 +27,7 @@ function split(value: string, splitToken: string) { if ( !delimiterToken && + groupingCount === 0 && trimmed .slice(index, index + splitToken.length) .join('') @@ -44,13 +45,16 @@ function split(value: string, splitToken: string) { // end identifier delimiterToken = undefined; } else if (!delimiterToken && trimmed[index - 1] !== ESCAPE_TOKEN) { - const applicableToken = DELIMITER_TOKENS.find( - (token) => token === char || (isArray(token) && token[0] === char) - ); + const applicableToken = STRING_DELIMITER_TOKENS.includes(char) ? char : undefined; + if (applicableToken) { // start identifier - delimiterToken = isArray(applicableToken) ? applicableToken[1] : applicableToken; + delimiterToken = applicableToken; continue; + } else if (char === '(') { + groupingCount++; + } else if (char === ')') { + groupingCount--; } } } @@ -104,7 +108,7 @@ function isValidColumnName(column: string) { } function escapeColumns(line: string) { - const [, command, body] = line.match(/^([A-Za-z_]+)(.*)$/s) ?? ['', '', '']; + const [, command, body] = line.match(/^([A-Za-z_]+)(.*)$/ms) ?? ['', '', '']; const escapedBody = split(body.trim(), ',') .map((statement) => { @@ -130,7 +134,7 @@ function verifyKeepColumns( const availableColumns = columnsInKeep.concat(); for (const { name, command } of nextCommands) { - if (['STATS', 'KEEP', 'DROP', 'DISSECT', 'GROK', 'ENRICH'].includes(name || '')) { + if (['STATS', 'KEEP', 'DROP', 'DISSECT', 'GROK', 'ENRICH', 'RENAME'].includes(name || '')) { // these operations alter columns in a way that is hard to analyze, so we abort break; } @@ -179,14 +183,15 @@ function escapeExpressionsInSort(sortCommand: string) { const columnsInSort = split(sortCommand.replace(/^SORT\s*/, ''), ',') .map((statement) => split(statement, '=')?.[0].trim()) .map((columnAndSortOrder) => { - let [, column, sortOrder = ''] = columnAndSortOrder.match(/^(.*?)\s*(ASC|DESC)?$/i) || []; + let [, column, sortOrder = ''] = + columnAndSortOrder.match(/^(.*?)\s+(ASC|DESC\s*([A-Z\s]+)?)?$/i) || []; if (!column) { return columnAndSortOrder; } if (sortOrder) sortOrder = ` ${sortOrder}`; - if (!column.match(/^[a-zA-Z0-9_\.@]+$/)) { + if (!column.match(/^`?[a-zA-Z0-9_\.@]+`?$/)) { column = `\`${column}\``; } @@ -220,59 +225,63 @@ function ensureEqualityOperators(whereCommand: string) { return `WHERE ${next}`; } -export function correctCommonEsqlMistakes(content: string, log: Logger) { - return content.replaceAll(/```esql\n(.*?)\n```/gms, (_, query: string) => { - const commands = splitIntoCommands(query.trim()); - - const formattedCommands: string[] = commands.map(({ name, command }, index) => { - let formattedCommand = command; - - switch (name) { - case 'FROM': - formattedCommand = formattedCommand - .replaceAll(/FROM "(.*)"/g, 'FROM $1') - .replaceAll(/FROM '(.*)'/g, 'FROM $1') - .replaceAll(/FROM `(.*)`/g, 'FROM $1'); - break; - - case 'WHERE': - formattedCommand = replaceSingleQuotesWithDoubleQuotes(formattedCommand); - formattedCommand = ensureEqualityOperators(formattedCommand); - break; - - case 'EVAL': - formattedCommand = replaceSingleQuotesWithDoubleQuotes(formattedCommand); - formattedCommand = escapeColumns(formattedCommand); - break; - - case 'STATS': - formattedCommand = replaceAsKeywordWithAssignments(formattedCommand); - const [before, after] = split(formattedCommand, ' BY '); - formattedCommand = escapeColumns(before); - if (after) { - formattedCommand += ` BY ${after}`; - } - break; - - case 'KEEP': - formattedCommand = verifyKeepColumns(formattedCommand, commands.slice(index + 1)); - break; - - case 'SORT': - formattedCommand = escapeExpressionsInSort(formattedCommand); - break; - } - return formattedCommand; - }); - - const correctedFormattedQuery = formattedCommands.join('\n| '); +export function correctCommonEsqlMistakes(query: string): { + isCorrection: boolean; + input: string; + output: string; +} { + const commands = splitIntoCommands(query.trim()); + + const formattedCommands: string[] = commands.map(({ name, command }, index) => { + let formattedCommand = command; + + switch (name) { + case 'FROM': + formattedCommand = formattedCommand + .replaceAll(/FROM "(.*)"/g, 'FROM $1') + .replaceAll(/FROM '(.*)'/g, 'FROM $1') + .replaceAll(/FROM `(.*)`/g, 'FROM $1'); + break; + + case 'WHERE': + formattedCommand = replaceSingleQuotesWithDoubleQuotes(formattedCommand); + formattedCommand = ensureEqualityOperators(formattedCommand); + break; + + case 'EVAL': + formattedCommand = replaceSingleQuotesWithDoubleQuotes(formattedCommand); + formattedCommand = escapeColumns(formattedCommand); + break; + + case 'STATS': + formattedCommand = replaceAsKeywordWithAssignments(formattedCommand); + const [before, after] = split(formattedCommand, ' BY '); + formattedCommand = escapeColumns(before); + if (after) { + formattedCommand += ` BY ${after}`; + } + break; - const originalFormattedQuery = commands.map((cmd) => cmd.command).join('\n| '); + case 'KEEP': + formattedCommand = verifyKeepColumns(formattedCommand, commands.slice(index + 1)); + break; - if (originalFormattedQuery !== correctedFormattedQuery) { - log.debug(`Modified query from: ${originalFormattedQuery}\nto:\n${correctedFormattedQuery}`); + case 'SORT': + formattedCommand = escapeExpressionsInSort(formattedCommand); + break; } - - return '```esql\n' + correctedFormattedQuery + '\n```'; + return formattedCommand; }); + + const output = formattedCommands.join('\n| '); + + const originalFormattedQuery = commands.map((cmd) => cmd.command).join('\n| '); + + const isCorrection = output !== originalFormattedQuery; + + return { + input: query, + output, + isCorrection, + }; } diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-abs.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-abs.txt index 5c436a9dfa0ce..c31ec9882e371 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-abs.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-abs.txt @@ -1,18 +1,30 @@ -ABS - -Syntax -Parameters -number -Numeric expression. If null, the function returns null. -DescriptionReturns the absolute value.Supported types -Examples +## ABS + +The `ABS` function in ES|QL returns the absolute value of a numeric expression. + +### Syntax + +`ABS(number)` + +#### Parameters + +`number`: Numeric expression. If null, the function returns null. + +### Examples + +Here are a couple of examples of how to use the `ABS` function in ES|QL: + ```esql ROW number = -1.0 | EVAL abs_number = ABS(number) ``` +In this example, the `ABS` function is used to calculate the absolute value of `-1.0`, which results in `1.0`. + ```esql FROM employees | KEEP first_name, last_name, height | EVAL abs_height = ABS(0.0 - height) ``` + +In this example, the `ABS` function is used to calculate the absolute value of the height of employees. The height is subtracted from `0.0` to get a negative value, and then the `ABS` function is applied to get the absolute value. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-acos.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-acos.txt index d4befd0a17aa2..2a5dab6453787 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-acos.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-acos.txt @@ -1,12 +1,29 @@ -ACOS - -Syntax -Parameters -number -Number between -1 and 1. If null, the function returns null. -DescriptionReturns the arccosine of n as an angle, expressed in radians.Supported types -Example +## ACOS + +The `ACOS` function in ES|QL returns the arccosine of a number as an angle, expressed in radians. The number should be between -1 and 1. If the input is null, the function will return null. + +### Syntax + +`ACOS(number)` + +#### Parameters + +`number`: A number between -1 and 1. If null, the function returns null. + +### Examples + +Here are a couple of examples of how to use the `ACOS` function in ES|QL queries: + ```esql ROW a=.9 -| EVAL acos=ACOS(a) +| EVAL acos = ACOS(a) +``` + +In this example, the `ACOS` function is used to calculate the arccosine of 0.9. + +```esql +ROW a=-.5 +| EVAL acos = ACOS(a) ``` + +In this example, the `ACOS` function is used to calculate the arccosine of -0.5. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-api.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-api.txt deleted file mode 100644 index 30555ee481ca9..0000000000000 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-api.txt +++ /dev/null @@ -1,61 +0,0 @@ - -ES|QL query APIedit -Returns search results for an ES|QL (Elasticsearch query language) query. -POST /_query -{ - "query": """ -```esql -FROM library - | EVAL year = DATE_TRUNC(1 YEARS, release_date) - | STATS MAX(page_count) BY year - | SORT year - | LIMIT 5 - """, -``` - -} -Requestedit -`POST _query` -Prerequisitesedit -If the Elasticsearch security features are enabled, you must have the `read` -index privilege for the data stream, index, -or alias you search. -Query parametersedit -`delimiter` -(Optional, string) Separator for CSV results. Defaults to `,`. The API only -supports this parameter for CSV responses. -`drop_null_columns` -(Optional, boolean) Should columns that are entirely `null` be removed from -the `columns` and `values` portion of the results? Defaults to `false`. If -`true` the the response will include an extra section under the name -`all_columns` which has the name of all columns. -`format` -(Optional, string) Format for the response. For valid values, refer to -Response formats. -You can also specify a format using the `Accept` HTTP header. If you specify -both this parameter and the `Accept` HTTP header, this parameter takes -precedence. -Request bodyedit -`columnar` -(Optional, Boolean) If `true`, returns results in a columnar format. Defaults to -`false`. The API only supports this parameter for CBOR, JSON, SMILE, and YAML -responses. See Columnar results. -`locale` -(Optional, string) Returns results (especially dates) formatted per the conventions of the locale. -For syntax, refer to Returning localized results. -`params` -(Optional, array) Values for parameters in the `query`. For syntax, refer to -Passing parameters to a query. -`query` -(Required, string) ES|QL query to run. For syntax, refer to Syntax reference. -Response bodyedit -`columns` -(array of objects) -Column `name` and `type` for each column returned in `values`. Each object is a single column. -`all_columns` -(array of objects) -Column `name` and `type` for each queried column. Each object is a single column. This is only -returned if `drop_null_columns` is sent with the request. -`rows` -(array of arrays) -Values for the search results. diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-asin.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-asin.txt index 79abf14656d69..0c03646864a7a 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-asin.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-asin.txt @@ -1,12 +1,21 @@ -ASIN - -Syntax -Parameters -number -Number between -1 and 1. If null, the function returns null. -DescriptionReturns the arcsine of the input numeric expression as an angle, expressed in radians.Supported types -Example +## ASIN + +The `ASIN` function in ES|QL returns the arcsine of the input numeric expression as an angle, expressed in radians. This function only accepts numbers between -1 and 1. If the input is null, the function will return null. + +### Examples + +Here are a couple of examples of how you can use the `ASIN` function in your ES|QL queries: + ```esql ROW a=.9 -| EVAL asin=ASIN(a) +| EVAL asin = ASIN(a) ``` + +In this example, the `ASIN` function is used to calculate the arcsine of 0.9. The result is stored in the `asin` column. + +```esql +ROW a=-.5 +| EVAL asin_value = ASIN(a) +``` + +In this second example, the `ASIN` function is used to calculate the arcsine of -0.5. The result is stored in the `asin_value` column. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-atan.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-atan.txt index 9c8f0a080a1fd..3c40607d25a82 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-atan.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-atan.txt @@ -1,12 +1,29 @@ -ATAN - -Syntax -Parameters -number -Numeric expression. If null, the function returns null. -DescriptionReturns the arctangent of the input numeric expression as an angle, expressed in radians.Supported types -Example +## ATAN + +The `ATAN` function in ES|QL is used to calculate the arctangent of a given numeric expression. The result is expressed in radians. If the input is null, the function will return null. + +### Syntax + +`ATAN(number)` + +#### Parameters + +- `number`: A numeric expression. If null, the function returns null. + +### Examples + +Here are a couple of examples of how you can use the `ATAN` function in ES|QL: + ```esql ROW a=12.9 -| EVAL atan=ATAN(a) +| EVAL atan = ATAN(a) +``` + +In this example, the `ATAN` function is used to calculate the arctangent of the number 12.9. + +```esql +ROW b=7.5 +| EVAL atan_value = ATAN(b) ``` + +In this second example, the `ATAN` function is used to calculate the arctangent of the number 7.5. The result is stored in the `atan_value` variable. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-atan2.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-atan2.txt index 9caa5eca10d50..9377a71c2eb6d 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-atan2.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-atan2.txt @@ -1,14 +1,30 @@ -ATAN2 - -Syntax -Parameters -y_coordinate -y coordinate. If null, the function returns null. -x_coordinate -x coordinate. If null, the function returns null. -DescriptionThe angle between the positive x-axis and the ray from the origin to the point (x , y) in the Cartesian plane, expressed in radians.Supported types -Example +## ATAN2 + +ATAN2 is a function in ES|QL that calculates the angle between the positive x-axis and the ray from the origin to the point (x , y) in the Cartesian plane, expressed in radians. + +### Syntax + +`ATAN2(y_coordinate, x_coordinate)` + +#### Parameters + +- `y_coordinate`: The y coordinate. If null, the function returns null. +- `x_coordinate`: The x coordinate. If null, the function returns null. + +### Examples + +Here are a couple of examples of how you can use the `ATAN2` function in ES|QL queries: + ```esql ROW y=12.9, x=.6 -| EVAL atan2=ATAN2(y, x) +| EVAL atan2 = ATAN2(y, x) +``` + +In this example, the `ATAN2` function is used to calculate the angle between the positive x-axis and the ray from the origin to the point (0.6 , 12.9) in the Cartesian plane. + +```esql +ROW y=5, x=3 +| EVAL atan2 = ATAN2(y, x) ``` + +In this second example, the `ATAN2` function is used to calculate the angle between the positive x-axis and the ray from the origin to the point (3 , 5) in the Cartesian plane. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-avg.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-avg.txt index 5ee99389900ed..bfd9c161bba1f 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-avg.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-avg.txt @@ -1,19 +1,21 @@ -AVG +## AVG -Syntax -AVG(expression) -expression -Numeric expression. -DescriptionThe average of a numeric expression.Supported typesThe result is always a double no matter the input type.Examples -```esql +The `AVG` function in ES|QL calculates the average of a numeric expression. The result is always a double, regardless of the input type. + +### Examples + +Here are a couple of examples of how you can use the `AVG` function in ES|QL queries: + +1. Calculating the average height of employees: + + ```esql FROM employees | STATS AVG(height) ``` -The expression can use inline functions. For example, to calculate the average -over a multivalued column, first use MV_AVG to average the multiple values per -row, and use the result with the AVG function: -```esql +2. Calculating the average salary change, where the salary change is a multivalued column. In this case, the `MV_AVG` function is used to first average the multiple values per row, and then the `AVG` function is used on the result: + + ```esql FROM employees | STATS avg_salary_change = ROUND(AVG(MV_AVG(salary_change)), 10) -``` +``` \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-bucket.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-bucket.txt index d74334af52ed7..2eed9008f6870 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-bucket.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-bucket.txt @@ -1,103 +1,22 @@ -BUCKET +## BUCKET -Syntax -Parameters -field -Numeric or date expression from which to derive buckets. -buckets -Target number of buckets. -from -Start of the range. Can be a number or a date expressed as a string. -to -End of the range. Can be a number or a date expressed as a string. -DescriptionCreates groups of values - buckets - out of a datetime or numeric input. The size of the buckets can either be provided directly, or chosen based on a recommended count and values range.Supported types -ExamplesBUCKET can work in two modes: one in which the size of the bucket is computed -based on a buckets count recommendation (four parameters) and a range, and -another in which the bucket size is provided directly (two parameters).Using a target number of buckets, a start of a range, and an end of a range, -BUCKET picks an appropriate bucket size to generate the target number of buckets or fewer. -For example, asking for at most 20 buckets over a year results in monthly buckets: -```esql -FROM employees -| WHERE hire_date >= "1985-01-01T00:00:00Z" AND hire_date < "1986-01-01T00:00:00Z" -| STATS hire_date = MV_SORT(VALUES(hire_date)) BY month = BUCKET(hire_date, 20, "1985-01-01T00:00:00Z", "1986-01-01T00:00:00Z") -| SORT hire_date -``` +BUCKET function creates groups of values - buckets - out of a datetime or numeric input. The size of the buckets can either be provided directly, or chosen based on a recommended count and values range. -The goal isn’t to provide exactly the target number of buckets, -it’s to pick a range that people are comfortable with that provides at most the target number of buckets.Combine BUCKET with an aggregation to create a histogram: -```esql -FROM employees -| WHERE hire_date >= "1985-01-01T00:00:00Z" AND hire_date < "1986-01-01T00:00:00Z" -| STATS hires_per_month = COUNT(*) BY month = BUCKET(hire_date, 20, "1985-01-01T00:00:00Z", "1986-01-01T00:00:00Z") -| SORT month -``` +### Examples -BUCKET does not create buckets that don’t match any documents. -That’s why this example is missing 1985-03-01 and other dates. -Asking for more buckets can result in a smaller range. -For example, asking for at most 100 buckets in a year results in weekly buckets: -```esql -FROM employees -| WHERE hire_date >= "1985-01-01T00:00:00Z" AND hire_date < "1986-01-01T00:00:00Z" -| STATS hires_per_week = COUNT(*) BY week = BUCKET(hire_date, 100, "1985-01-01T00:00:00Z", "1986-01-01T00:00:00Z") -| SORT week -``` +In this example, BUCKET function is used to create a histogram of salaries: -BUCKET does not filter any rows. It only uses the provided range to pick a good bucket size. -For rows with a value outside of the range, it returns a bucket value that corresponds to a bucket outside the range. -Combine`BUCKET` with WHERE to filter rows. -If the desired bucket size is known in advance, simply provide it as the second -argument, leaving the range out: ```esql FROM employees -| WHERE hire_date >= "1985-01-01T00:00:00Z" AND hire_date < "1986-01-01T00:00:00Z" -| STATS hires_per_week = COUNT(*) BY week = BUCKET(hire_date, 1 week) -| SORT week -``` - -When providing the bucket size as the second parameter, it must be a time -duration or date period. -BUCKET can also operate on numeric fields. For example, to create a salary histogram: -```esql -FROM employees -| STATS COUNT(*) by bs = BUCKET(salary, 20, 25324, 74999) +| STATS COUNT(*) BY bs = BUCKET(salary, 20, 25324, 74999) | SORT bs ``` -Unlike the earlier example that intentionally filters on a date range, you rarely want to filter on a numeric range. -You have to find the min and max separately. ES|QL doesn’t yet have an easy way to do that automatically.The range can be omitted if the desired bucket size is known in advance. Simply -provide it as the second argument: -```esql -FROM employees -| WHERE hire_date >= "1985-01-01T00:00:00Z" AND hire_date < "1986-01-01T00:00:00Z" -| STATS c = COUNT(1) BY b = BUCKET(salary, 5000.) -| SORT b -``` - -When providing the bucket size as the second parameter, it must be -of a floating point type. -Create hourly buckets for the last 24 hours, and calculate the number of events per hour: -```esql -FROM sample_data -| WHERE @timestamp >= NOW() - 1 day and @timestamp < NOW() -| STATS COUNT(*) BY bucket = BUCKET(@timestamp, 25, NOW() - 1 day, NOW()) -``` +In the following example, BUCKET function is used to create monthly buckets for the year 1985, and calculate the average salary by hiring month: -Create monthly buckets for the year 1985, and calculate the average salary by hiring month ```esql FROM employees | WHERE hire_date >= "1985-01-01T00:00:00Z" AND hire_date < "1986-01-01T00:00:00Z" | STATS AVG(salary) BY bucket = BUCKET(hire_date, 20, "1985-01-01T00:00:00Z", "1986-01-01T00:00:00Z") | SORT bucket -``` - -BUCKET may be used in both the aggregating and grouping part of the -STATS …​ BY …​ command provided that in the aggregating -part the function is referenced by an alias defined in the -grouping part, or that it is invoked with the exact same expression: -```esql -FROM employees -| STATS s1 = b1 + 1, s2 = BUCKET(salary / 1000 + 999, 50.) + 2 BY b1 = BUCKET(salary / 100 + 99, 50.), b2 = BUCKET(salary / 1000 + 999, 50.) -| SORT b1, b2 -| KEEP s1, b1, s2, b2 -``` +``` \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-case.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-case.txt index a8d2ca35fb1c8..66fed29cea823 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-case.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-case.txt @@ -1,19 +1,13 @@ -CASE - -Syntax -CASE(condition1, value1[, ..., conditionN, valueN][, default_value]) -Parameters -conditionX -A condition. -valueX -The value that’s returned when the corresponding condition is the first to -evaluate to true. -default_value -The default value that’s is returned when no condition matches. -DescriptionAccepts pairs of conditions and values. The function returns the value that -belongs to the first condition that evaluates to true.If the number of arguments is odd, the last argument is the default value which -is returned when no condition matches. If the number of arguments is even, and -no condition matches, the function returns null.ExampleDetermine whether employees are monolingual, bilingual, or polyglot: +## CASE + +The `CASE` function in ES|QL accepts pairs of conditions and values. It returns the value that belongs to the first condition that evaluates to true. If the number of arguments is odd, the last argument is the default value which is returned when no condition matches. If the number of arguments is even, and no condition matches, the function returns null. + +### Examples + +Here are a couple of examples of how you can use the `CASE` function in ES|QL: + +1. Determine whether employees are monolingual, bilingual, or polyglot: + ```esql FROM employees | EVAL type = CASE( @@ -23,7 +17,8 @@ FROM employees | KEEP emp_no, languages, type ``` -Calculate the total connection success rate based on log messages: +2. Calculate the total connection success rate based on log messages: + ```esql FROM sample_data | EVAL successful = CASE( @@ -33,12 +28,12 @@ FROM sample_data | STATS success_rate = AVG(successful) ``` -Calculate an hourly error rate as a percentage of the total number of log -messages: +3. Calculate an hourly error rate as a percentage of the total number of log messages: + ```esql FROM sample_data | EVAL error = CASE(message LIKE "*error*", 1, 0) | EVAL hour = DATE_TRUNC(1 hour, @timestamp) -| STATS error_rate = AVG(error) by hour +| STATS error_rate = AVG(error) BY hour | SORT hour -``` +``` \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-cbrt.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-cbrt.txt new file mode 100644 index 0000000000000..4a5af259aabeb --- /dev/null +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-cbrt.txt @@ -0,0 +1,29 @@ +## CBRT + +The `CBRT` function in ES|QL is used to calculate the cube root of a number. The input can be any numeric value and the return value is always a double. If the input is an infinity, the function returns null. + +### Syntax + +`CBRT(number)` + +#### Parameters + +- `number`: A numeric expression. If null, the function returns null. + +### Examples + +Here are a couple of examples of how to use the `CBRT` function in ES|QL: + +```esql +ROW d = 27.0 +| EVAL c = CBRT(d) +``` + +In this example, the `CBRT` function is used to calculate the cube root of 27. The result would be 3. + +```esql +ROW d = 64.0 +| EVAL c = CBRT(d) +``` + +In this example, the `CBRT` function is used to calculate the cube root of 64. The result would be 4. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-ceil.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-ceil.txt index d8bea9d574ea1..3cac4dbf7c63b 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-ceil.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-ceil.txt @@ -1,14 +1,21 @@ -CEIL - -Syntax -Parameters -number -Numeric expression. If null, the function returns null. -DescriptionRound a number up to the nearest integer. -This is a noop for long (including unsigned) and integer. For double this picks the closest double value to the integer similar to Math.ceil. -Supported types -Example +## CEIL + +The `CEIL` function in ES|QL is used to round a number up to the nearest integer. This function does not perform any operation for long (including unsigned) and integer types. For double, this function picks the closest double value to the integer, similar to the `Math.ceil` function in JavaScript. + +### Examples + +Here are a couple of examples of how you can use the `CEIL` function in ES|QL queries: + ```esql ROW a=1.8 -| EVAL a=CEIL(a) +| EVAL a = CEIL(a) ``` + +In this example, the `CEIL` function is used to round the value of `a` (1.8) up to the nearest integer (2). + +```esql +ROW b=3.3 +| EVAL b = CEIL(b) +``` + +In this second example, the `CEIL` function is used to round the value of `b` (3.3) up to the nearest integer (4). \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-cidr_match.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-cidr_match.txt new file mode 100644 index 0000000000000..d66963e5efaaa --- /dev/null +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-cidr_match.txt @@ -0,0 +1,32 @@ +## CIDR_MATCH + +CIDR_MATCH is a function in ES|QL that checks if a provided IP address is contained in one or more provided CIDR blocks. It returns a boolean value - true if the IP is contained in the CIDR block(s), and false if it is not. + +### Syntax + +`CIDR_MATCH(ip, blockX)` + +### Parameters + +- `ip`: IP address of type ip (both IPv4 and IPv6 are supported). +- `blockX`: CIDR block to test the IP against. + +### Examples + +Here are a couple of examples of how you can use the CIDR_MATCH function in ES|QL queries: + +```esql +FROM hosts +| WHERE CIDR_MATCH(ip1, "127.0.0.2/32", "127.0.0.3/32") +| KEEP card, host, ip0, ip1 +``` + +In this example, the query checks if the `ip1` field of the `hosts` index is contained in either the "127.0.0.2/32" or "127.0.0.3/32" CIDR blocks. If it is, the `card`, `host`, `ip0`, and `ip1` fields are kept in the results. + +```esql +FROM network_logs +| WHERE CIDR_MATCH(source_ip, "192.168.1.0/24") +| KEEP timestamp, source_ip, destination_ip +``` + +In this second example, the query checks if the `source_ip` field of the `network_logs` index is contained in the "192.168.1.0/24" CIDR block. If it is, the `timestamp`, `source_ip`, and `destination_ip` fields are kept in the results. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-coalesce.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-coalesce.txt index 87e4de6189078..f1fbc77e6c341 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-coalesce.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-coalesce.txt @@ -1,14 +1,30 @@ -COALESCE - -Syntax -COALESCE(expression1 [, ..., expressionN]) -Parameters -first -Expression to evaluate -rest -Other expression to evaluate -DescriptionReturns the first of its arguments that is not null. If all arguments are null, it returns null.Example +## COALESCE + +The `COALESCE` function in ES|QL is used to return the first of its arguments that is not null. If all arguments are null, it returns null. + +### Syntax + +`COALESCE(first, rest)` + +#### Parameters + +- `first`: The first expression to evaluate. +- `rest`: Other expressions to evaluate. + +### Examples + +Here are a couple of examples of how you can use the `COALESCE` function in ES|QL: + ```esql ROW a=null, b="b" | EVAL COALESCE(a, b) ``` + +In this example, the `COALESCE` function is used to evaluate the expressions `a` and `b`. Since `a` is null, the function returns the value of `b`, which is "b". + +```esql +ROW a=null, b=null, c="c" +| EVAL COALESCE(a, b, c) +``` + +In this second example, the `COALESCE` function evaluates the expressions `a`, `b`, and `c`. Since both `a` and `b` are null, the function returns the value of `c`, which is "c". \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-concat.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-concat.txt index b58d7e13649f7..60f1c33a6fa57 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-concat.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-concat.txt @@ -1,15 +1,22 @@ -CONCAT - -Syntax -Parameters -string1 -Strings to concatenate. -string2 -Strings to concatenate. -DescriptionConcatenates two or more strings.Supported types -Example +## CONCAT + +The `CONCAT` function in ES|QL is used to concatenate two or more strings together. + +### Examples + +Here are a couple of examples of how you can use the `CONCAT` function in ES|QL: + ```esql FROM employees | KEEP first_name, last_name | EVAL fullname = CONCAT(first_name, " ", last_name) ``` + +In this example, the `CONCAT` function is used to combine the `first_name` and `last_name` fields from the `employees` index, with a space in between, to create a new field called `fullname`. + +```esql +FROM logs-* +| EVAL message = CONCAT("Error occurred at ", @timestamp, ": ", error_message) +``` + +In this second example, the `CONCAT` function is used to create a descriptive error message by combining a static string, the `@timestamp` field, and the `error_message` field from the `logs-*` index. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-cos.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-cos.txt index 09154626e1853..1489bfcfedf7a 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-cos.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-cos.txt @@ -1,12 +1,21 @@ -COS - -Syntax -Parameters -angle -An angle, in radians. If null, the function returns null. -DescriptionReturns the cosine of an angle.Supported types -Example +## COS + +The `COS` function in ES|QL is used to calculate the cosine of an angle. The angle should be provided in radians. + +### Examples + +Here are a couple of examples of how you can use the `COS` function in ES|QL: + ```esql ROW a=1.8 -| EVAL cos=COS(a) +| EVAL cos = COS(a) ``` + +In this example, the `COS` function is used to calculate the cosine of the angle `1.8` radians. The result is stored in the `cos` column. + +```esql +ROW a=3.14 +| EVAL cos_value = COS(a) +``` + +In this second example, the `COS` function is used to calculate the cosine of the angle `3.14` radians (which is approximately equal to π, the angle for which the cosine is `-1`). The result is stored in the `cos_value` column. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-cosh.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-cosh.txt index 5fa95d2a204b4..903746bb07c02 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-cosh.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-cosh.txt @@ -1,12 +1,21 @@ -COSH - -Syntax -Parameters -angle -An angle, in radians. If null, the function returns null. -DescriptionReturns the hyperbolic cosine of an angle.Supported types -Example +## COSH + +The `COSH` function in ES|QL returns the hyperbolic cosine of an angle. The angle should be provided in radians. If the provided angle is null, the function will return null. + +### Examples + +Here are a couple of examples of how you can use the `COSH` function in ES|QL: + ```esql ROW a=1.8 -| EVAL cosh=COSH(a) +| EVAL cosh = COSH(a) ``` + +In this example, the `COSH` function is used to calculate the hyperbolic cosine of the angle `1.8` radians. + +```esql +ROW a=0 +| EVAL cosh = COSH(a) +``` + +In this second example, the `COSH` function is used to calculate the hyperbolic cosine of the angle `0` radians. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-count.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-count.txt index 326d5c2e1caae..97c49b44471a7 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-count.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-count.txt @@ -1,27 +1,35 @@ -COUNT - -Syntax -COUNT([expression]) -Parameters -expression -Expression that outputs values to be counted. -If omitted, equivalent to COUNT(*) (the number of rows). -DescriptionReturns the total number (count) of input values.Supported typesCan take any field type as input.Examples +## COUNT + +The `COUNT` function in ES|QL returns the total number (count) of input values. It can take any field type as input. If the expression is omitted, it is equivalent to `COUNT(*)` which counts the number of rows. + +### Examples + +Here are a couple of examples of how you can use the `COUNT` function in ES|QL: + +1. Counting a specific field: + ```esql FROM employees | STATS COUNT(height) ``` -To count the number of rows, use COUNT() or COUNT(*): +In this example, the `COUNT` function is used to count the number of `height` values in the `employees` index. + +2. Counting the number of rows: + ```esql FROM employees | STATS count = COUNT(*) BY languages | SORT languages DESC ``` -The expression can use inline functions. This example splits a string into -multiple values using the SPLIT function and counts the values: +In this example, the `COUNT(*)` function is used to count the number of rows in the `employees` index, grouped by `languages`. + +3. Using inline functions with `COUNT`: + ```esql ROW words="foo;bar;baz;qux;quux;foo" | STATS word_count = COUNT(SPLIT(words, ";")) ``` + +In this example, the `SPLIT` function is used to split a string into multiple values, and then the `COUNT` function is used to count these values. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-count_distinct.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-count_distinct.txt index db129e784b2e1..bc977ed744b07 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-count_distinct.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-count_distinct.txt @@ -1,54 +1,37 @@ -COUNT_DISTINCT - -Syntax -COUNT_DISTINCT(expression[, precision_threshold]) -Parameters -expression -Expression that outputs the values on which to perform a distinct count. -precision_threshold -Precision threshold. Refer to Counts are approximate. The -maximum supported value is 40000. Thresholds above this number will have the -same effect as a threshold of 40000. The default value is 3000. -DescriptionReturns the approximate number of distinct values.Supported typesCan take any field type as input.Examples +## COUNT_DISTINCT + +The `COUNT_DISTINCT` function returns the approximate number of distinct values. It can take any field type as input. This function is based on the HyperLogLog++ algorithm, which counts based on the hashes of the values with some interesting properties such as configurable precision, excellent accuracy on low-cardinality sets, and fixed memory usage. + +### Syntax + +`COUNT_DISTINCT(expression[, precision_threshold])` + +#### Parameters + +- `expression`: Expression that outputs the values on which to perform a distinct count. +- `precision_threshold`: Precision threshold. The maximum supported value is 40000. Thresholds above this number will have the same effect as a threshold of 40000. The default value is 3000. + +### Examples + +Here are a couple of examples of how to use the `COUNT_DISTINCT` function in ES|QL queries: + ```esql FROM hosts | STATS COUNT_DISTINCT(ip0), COUNT_DISTINCT(ip1) ``` -With the optional second parameter to configure the precision threshold: +In this example, the `COUNT_DISTINCT` function is used to count the distinct values of `ip0` and `ip1` from the `hosts` index. + ```esql FROM hosts | STATS COUNT_DISTINCT(ip0, 80000), COUNT_DISTINCT(ip1, 5) ``` -The expression can use inline functions. This example splits a string into -multiple values using the SPLIT function and counts the unique values: +In this example, the `COUNT_DISTINCT` function is used with an optional second parameter to configure the precision threshold. + ```esql ROW words="foo;bar;baz;qux;quux;foo" | STATS distinct_word_count = COUNT_DISTINCT(SPLIT(words, ";")) ``` -Counts are approximateeditComputing exact counts requires loading values into a set and returning its -size. This doesn’t scale when working on high-cardinality sets and/or large -values as the required memory usage and the need to communicate those -per-shard sets between nodes would utilize too many resources of the cluster.This COUNT_DISTINCT function is based on the -HyperLogLog++ -algorithm, which counts based on the hashes of the values with some interesting -properties: -configurable precision, which decides on how to trade memory for accuracy, -excellent accuracy on low-cardinality sets, -fixed memory usage: no matter if there are tens or billions of unique values, -memory usage only depends on the configured precision. -For a precision threshold of c, the implementation that we are using requires -about c * 8 bytes.The following chart shows how the error varies before and after the threshold:For all 3 thresholds, counts have been accurate up to the configured threshold. -Although not guaranteed, this is likely to be the case. Accuracy in practice depends -on the dataset in question. In general, most datasets show consistently good -accuracy. Also note that even with a threshold as low as 100, the error -remains very low (1-6% as seen in the above graph) even when counting millions of items.The HyperLogLog++ algorithm depends on the leading zeros of hashed -values, the exact distributions of hashes in a dataset can affect the -accuracy of the cardinality.The COUNT_DISTINCT function takes an optional second parameter to configure -the precision threshold. The precision_threshold options allows to trade memory -for accuracy, and defines a unique count below which counts are expected to be -close to accurate. Above this value, counts might become a bit more fuzzy. The -maximum supported value is 40000, thresholds above this number will have the -same effect as a threshold of 40000. The default value is 3000. \ No newline at end of file +In this example, the `COUNT_DISTINCT` function is used with the `SPLIT` function to count the unique values in a string. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-cross_cluster.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-cross_cluster.txt deleted file mode 100644 index 715a15fa06edd..0000000000000 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-cross_cluster.txt +++ /dev/null @@ -1,225 +0,0 @@ - -Prerequisitesedit -Cross-cluster search requires remote clusters. To set up remote clusters on Elasticsearch Service, -see configure remote clusters on Elasticsearch Service. If you -run Elasticsearch on your own hardware, see Remote clusters. -To ensure your remote cluster configuration supports cross-cluster search, see -Supported cross-cluster search configurations. -For full cross-cluster search capabilities, the local and remote cluster must be on the same -subscription level. -The local coordinating node must have the -`remote_cluster_client` node role. -If you use sniff mode, the local coordinating node -must be able to connect to seed and gateway nodes on the remote cluster. -We recommend using gateway nodes capable of serving as coordinating nodes. -The seed nodes can be a subset of these gateway nodes. -If you use proxy mode, the local coordinating node must be able -to connect to the configured `proxy_address`. The proxy at this address must be -able to route connections to gateway and coordinating nodes on the remote -cluster. -Cross-cluster search requires different security privileges on the local cluster and -remote cluster. See Configure privileges for cross-cluster search and -Remote clusters. -Remote cluster setupedit -The following cluster update settings API request -adds three remote clusters: `cluster_one`, `cluster_two`, and `cluster_three`. -response = client.cluster.put_settings( - body: { - persistent: { - cluster: { - remote: { - cluster_one: { - seeds: [ - '35.238.149.1:9300' - ], - skip_unavailable: true - }, - cluster_two: { - seeds: [ - '35.238.149.2:9300' - ], - skip_unavailable: false - }, - cluster_three: { - seeds: [ - '35.238.149.3:9300' - ] - } - } - } - } - } -) -puts response -PUT _cluster/settings -{ - "persistent": { - "cluster": { - "remote": { - "cluster_one": { - "seeds": [ - "35.238.149.1:9300" - ], - "skip_unavailable": true - }, - "cluster_two": { - "seeds": [ - "35.238.149.2:9300" - ], - "skip_unavailable": false - }, - "cluster_three": { - "seeds": [ - "35.238.149.3:9300" - ] - } - } - } - } -} -Since `skip_unavailable` was not set on `cluster_three`, it uses -the default of `false`. See the Optional remote clusters -section for details. -Query across multiple clustersedit -In the `FROM` command, specify data streams and indices on remote clusters -using the format `:`. For instance, the following -ES|QL request queries the `my-index-000001` index on a single remote cluster -named `cluster_one`: -```esql -FROM cluster_one:my-index-000001 -| LIMIT 10 -``` - -Similarly, this ES|QL request queries the `my-index-000001` index from -three clusters: -The local ("querying") cluster -Two remote clusters, `cluster_one` and `cluster_two` -```esql -FROM my-index-000001,cluster_one:my-index-000001,cluster_two:my-index-000001 -| LIMIT 10 -``` - -Likewise, this ES|QL request queries the `my-index-000001` index from all -remote clusters (`cluster_one`, `cluster_two`, and `cluster_three`): -```esql -FROM *:my-index-000001 -| LIMIT 10 -``` - -Enrich across clustersedit -Enrich in ES|QL across clusters operates similarly to local enrich. -If the enrich policy and its enrich indices are consistent across all clusters, simply -write the enrich command as you would without remote clusters. In this default mode, -ES|QL can execute the enrich command on either the querying cluster or the fulfilling -clusters, aiming to minimize computation or inter-cluster data transfer. Ensuring that -the policy exists with consistent data on both the querying cluster and the fulfilling -clusters is critical for ES|QL to produce a consistent query result. -In the following example, the enrich with `hosts` policy can be executed on -either the querying cluster or the remote cluster `cluster_one`. -```esql -FROM my-index-000001,cluster_one:my-index-000001 -| ENRICH hosts ON ip -| LIMIT 10 -``` - -Enrich with an ES|QL query against remote clusters only can also happen on -the querying cluster. This means the below query requires the `hosts` enrich -policy to exist on the querying cluster as well. -```esql -FROM cluster_one:my-index-000001,cluster_two:my-index-000001 -| LIMIT 10 -| ENRICH hosts ON ip -``` - -Enrich with coordinator modeedit -ES|QL provides the enrich `_coordinator` mode to force ES|QL to execute the enrich -command on the querying cluster. This mode should be used when the enrich policy is -not available on the remote clusters or maintaining consistency of enrich indices -across clusters is challenging. -```esql -FROM my-index-000001,cluster_one:my-index-000001 -| ENRICH _coordinator:hosts ON ip -| SORT host_name -| LIMIT 10 -``` - -Enrich with the `_coordinator` mode usually increases inter-cluster data transfer and -workload on the querying cluster. -Enrich with remote modeedit -ES|QL also provides the enrich `_remote` mode to force ES|QL to execute the enrich -command independently on each fulfilling cluster where the target indices reside. -This mode is useful for managing different enrich data on each cluster, such as detailed -information of hosts for each region where the target (main) indices contain -log events from these hosts. -In the below example, the `hosts` enrich policy is required to exist on all -fulfilling clusters: the `querying` cluster (as local indices are included), -the remote cluster `cluster_one`, and `cluster_two`. -```esql -FROM my-index-000001,cluster_one:my-index-000001,cluster_two:my-index-000001 -| ENRICH _remote:hosts ON ip -| SORT host_name -| LIMIT 10 -``` - -A `_remote` enrich cannot be executed after a stats -command. The following example would result in an error: -```esql -FROM my-index-000001,cluster_one:my-index-000001,cluster_two:my-index-000001 -| STATS COUNT(*) BY ip -| ENRICH _remote:hosts ON ip -| SORT host_name -| LIMIT 10 -``` - -Multiple enrich commandsedit -You can include multiple enrich commands in the same query with different -modes. ES|QL will attempt to execute them accordingly. For example, this -query performs two enriches, first with the `hosts` policy on any cluster -and then with the `vendors` policy on the querying cluster. -```esql -FROM my-index-000001,cluster_one:my-index-000001,cluster_two:my-index-000001 -| ENRICH hosts ON ip -| ENRICH _coordinator:vendors ON os -| LIMIT 10 -``` - -A `_remote` enrich command can’t be executed after a `_coordinator` enrich -command. The following example would result in an error. -```esql -FROM my-index-000001,cluster_one:my-index-000001,cluster_two:my-index-000001 -| ENRICH _coordinator:hosts ON ip -| ENRICH _remote:vendors ON os -| LIMIT 10 -``` - -Excluding clusters or indices from ES|QL queryedit -To exclude an entire cluster, prefix the cluster alias with a minus sign in -the `FROM` command, for example: `-my_cluster:*`: -```esql -FROM my-index-000001,cluster*:my-index-000001,-cluster_three:* -| LIMIT 10 -``` - -To exclude a specific remote index, prefix the index with a minus sign in -the `FROM` command, such as `my_cluster:-my_index`: -```esql -FROM my-index-000001,cluster*:my-index-*,cluster_three:-my-index-000001 -| LIMIT 10 -``` - -Optional remote clustersedit -Cross-cluster search for ES|QL currently does not respect the `skip_unavailable` -setting. As a result, if a remote cluster specified in the request is -unavailable or failed, cross-cluster search for ES|QL queries will fail regardless of the setting. -We are actively working to align the behavior of cross-cluster search for ES|QL with other -cross-cluster search APIs. This includes providing detailed execution information for each cluster -in the response, such as execution time, selected target indices, and shards. -Query across clusters during an upgradeedit -You can still search a remote cluster while performing a -rolling upgrade on the local cluster. However, the local -coordinating node’s "upgrade from" and "upgrade to" version must be compatible -with the remote cluster’s gateway node. -Running multiple versions of Elasticsearch in the same cluster beyond the -duration of an upgrade is not supported. -For more information about upgrades, see -Upgrading Elasticsearch. diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-date_diff.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-date_diff.txt index b93f502498591..ef9ccdb30d44b 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-date_diff.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-date_diff.txt @@ -1,21 +1,33 @@ -DATE_DIFF - -Syntax -Parameters -unit -Time difference unit -startTimestamp -A string representing a start timestamp -endTimestamp -A string representing an end timestamp -DescriptionSubtracts the startTimestamp from the endTimestamp and returns the difference in multiples of unit. If startTimestamp is later than the endTimestamp, negative values are returned. -Note that while there is an overlap between the function’s supported units and -ES|QL’s supported time span literals, these sets are distinct and not -interchangeable. Similarly, the supported abbreviations are conveniently shared -with implementations of this function in other established products and not -necessarily common with the date-time nomenclature used by Elasticsearch.Supported types -Example +## DATE_DIFF + +The `DATE_DIFF` function subtracts the `startTimestamp` from the `endTimestamp` and returns the difference in multiples of a specified unit. If `startTimestamp` is later than the `endTimestamp`, negative values are returned. + +Note that while there is an overlap between the function’s supported units and ES|QL’s supported time span literals, these sets are distinct and not interchangeable. Similarly, the supported abbreviations are conveniently shared with implementations of this function in other established products and not necessarily common with the date-time nomenclature used by Elasticsearch. + +### Syntax + +`DATE_DIFF(unit, startTimestamp, endTimestamp)` + +#### Parameters + +- `unit`: Time difference unit +- `startTimestamp`: A string representing a start timestamp +- `endTimestamp`: A string representing an end timestamp + +### Examples + +Here are a couple of examples of how to use the `DATE_DIFF` function in ES|QL queries: + ```esql ROW date1 = TO_DATETIME("2023-12-02T11:00:00.000Z"), date2 = TO_DATETIME("2023-12-02T11:00:00.001Z") | EVAL dd_ms = DATE_DIFF("microseconds", date1, date2) ``` + +In this example, the `DATE_DIFF` function is used to calculate the difference in microseconds between two timestamps. + +```esql +ROW date1 = TO_DATETIME("2023-12-02T11:00:00.000Z"), date2 = TO_DATETIME("2023-12-03T11:00:00.000Z") +| EVAL dd_days = DATE_DIFF("days", date1, date2) +``` + +In this second example, the `DATE_DIFF` function is used to calculate the difference in days between two timestamps. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-date_extract.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-date_extract.txt index 0debd6f2eeb51..36c0272e3c479 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-date_extract.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-date_extract.txt @@ -1,20 +1,28 @@ -DATE_EXTRACT - -Syntax -Parameters -datePart -Part of the date to extract. Can be: aligned_day_of_week_in_month, aligned_day_of_week_in_year, aligned_week_of_month, aligned_week_of_year, ampm_of_day, clock_hour_of_ampm, clock_hour_of_day, day_of_month, day_of_week, day_of_year, epoch_day, era, hour_of_ampm, hour_of_day, instant_seconds, micro_of_day, micro_of_second, milli_of_day, milli_of_second, minute_of_day, minute_of_hour, month_of_year, nano_of_day, nano_of_second, offset_seconds, proleptic_month, second_of_day, second_of_minute, year, or year_of_era. Refer to java.time.temporal.ChronoField for a description of these values. If null, the function returns null. -date -Date expression. If null, the function returns null. -DescriptionExtracts parts of a date, like year, month, day, hour.Supported types -Examples +## DATE_EXTRACT + +The `DATE_EXTRACT` function is used to extract specific parts of a date, such as the year, month, day, or hour. + +### Syntax + +`DATE_EXTRACT(datePart, date)` + +#### Parameters + +- `datePart`: Part of the date to extract. Can be: `aligned_day_of_week_in_month`, `aligned_day_of_week_in_year`, `aligned_week_of_month`, `aligned_week_of_year`, `ampm_of_day`, `clock_hour_of_ampm`, `clock_hour_of_day`, `day_of_month`, `day_of_week`, `day_of_year`, `epoch_day`, `era`, `hour_of_ampm`, `hour_of_day`, `instant_seconds`, `micro_of_day`, `micro_of_second`, `milli_of_day`, `milli_of_second`, `minute_of_day`, `minute_of_hour`, `month_of_year`, `nano_of_day`, `nano_of_second`, `offset_seconds`, `proleptic_month`, `second_of_day`, `second_of_minute`, `year`, or `year_of_era`. Refer to `java.time.temporal.ChronoField` for a description of these values. If null, the function returns null. +- `date`: Date expression. If null, the function returns null. + +### Examples + +The following ES|QL query uses the `DATE_EXTRACT` function to extract the year from a date: + ```esql ROW date = DATE_PARSE("yyyy-MM-dd", "2022-05-06") | EVAL year = DATE_EXTRACT("year", date) ``` -Find all events that occurred outside of business hours (before 9 AM or after 5PM), on any given date: +This ES|QL query uses the `DATE_EXTRACT` function to find all events that occurred outside of business hours (before 9 AM or after 5 PM), on any given date: + ```esql FROM sample_data | WHERE DATE_EXTRACT("hour_of_day", @timestamp) < 9 AND DATE_EXTRACT("hour_of_day", @timestamp) >= 17 -``` +``` \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-date_format.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-date_format.txt index 481b9fed4695f..c2221c5add437 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-date_format.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-date_format.txt @@ -1,15 +1,32 @@ -DATE_FORMAT - -Syntax -Parameters -dateFormat -Date format (optional). If no format is specified, the yyyy-MM-dd'T'HH:mm:ss.SSSZ format is used. If null, the function returns null. -date -Date expression. If null, the function returns null. -DescriptionReturns a string representation of a date, in the provided format.Supported types -Example +## DATE_FORMAT + +The `DATE_FORMAT` function in ES|QL is used to return a string representation of a date, in the provided format. If no format is specified, the `yyyy-MM-dd'T'HH:mm:ss.SSSZ` format is used. + +### Syntax + +`DATE_FORMAT(dateFormat, date)` + +#### Parameters + +- `dateFormat`: Date format (optional). If no format is specified, the `yyyy-MM-dd'T'HH:mm:ss.SSSZ` format is used. If null, the function returns null. +- `date`: Date expression. If null, the function returns null. + +### Examples + +Here are a couple of examples of how you can use the `DATE_FORMAT` function in your ES|QL queries: + ```esql FROM employees | KEEP first_name, last_name, hire_date | EVAL hired = DATE_FORMAT("YYYY-MM-dd", hire_date) ``` + +In this example, the `DATE_FORMAT` function is used to format the `hire_date` field in the "YYYY-MM-dd" format. + +```esql +FROM logs-* +| WHERE @timestamp <= NOW() +| EVAL log_date = DATE_FORMAT("YYYY-MM-dd HH:mm:ss", @timestamp) +``` + +In this second example, the `DATE_FORMAT` function is used to format the `@timestamp` field in the "YYYY-MM-dd HH:mm:ss" format. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-date_parse.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-date_parse.txt index 98650dd05f73a..0eab64ed4fcf2 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-date_parse.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-date_parse.txt @@ -1,14 +1,30 @@ -DATE_PARSE - -Syntax -Parameters -datePattern -The date format. Refer to the DateTimeFormatter documentation for the syntax. If null, the function returns null. -dateString -Date expression as a string. If null or an empty string, the function returns null. -DescriptionReturns a date by parsing the second argument using the format specified in the first argument.Supported types -Example +## DATE_PARSE + +DATE_PARSE is a function in ES|QL that allows you to parse a date string using a specified format. This function is useful when you need to convert a string into a date format for further processing or analysis. + +### Syntax + +`DATE_PARSE(datePattern, dateString)` + +#### Parameters + +- `datePattern`: The date format. Refer to the DateTimeFormatter documentation for the syntax. If null, the function returns null. +- `dateString`: Date expression as a string. If null or an empty string, the function returns null. + +### Examples + +Here are a couple of examples of how you can use the DATE_PARSE function in ES|QL queries: + ```esql ROW date_string = "2022-05-06" | EVAL date = DATE_PARSE("yyyy-MM-dd", date_string) ``` + +In this example, the DATE_PARSE function is used to convert the string "2022-05-06" into a date format using the "yyyy-MM-dd" pattern. + +```esql +ROW date_string = "06-05-2022" +| EVAL date = DATE_PARSE("dd-MM-yyyy", date_string) +``` + +In this second example, the DATE_PARSE function is used to convert the string "06-05-2022" into a date format using the "dd-MM-yyyy" pattern. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-date_trunc.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-date_trunc.txt index 073ac87c7ab3b..5e8c1318fc2c3 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-date_trunc.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-date_trunc.txt @@ -1,21 +1,30 @@ -DATE_TRUNC - -Syntax -Parameters -interval -Interval; expressed using the timespan literal syntax. -date -Date expression -DescriptionRounds down a date to the closest interval.Supported types -Examples +## DATE_TRUNC + +The `DATE_TRUNC` function in ES|QL rounds down a date to the closest interval. This can be useful for creating date histograms or calculating rates over specific time intervals. + +### Syntax + +`DATE_TRUNC(interval, date)` + +#### Parameters + +- `interval`: Interval; expressed using the timespan literal syntax. +- `date`: Date expression + +### Examples + +Here are a couple of examples of how you can use the `DATE_TRUNC` function in ES|QL queries: + +1. To round down the hire date of employees to the closest year and keep the first name, last name, and hire date: + ```esql FROM employees | KEEP first_name, last_name, hire_date | EVAL year_hired = DATE_TRUNC(1 year, hire_date) ``` -Combine DATE_TRUNC with STATS ... BY to create date histograms. For -example, the number of hires per year: +2. To create a date histogram showing the number of hires per year: + ```esql FROM employees | EVAL year = DATE_TRUNC(1 year, hire_date) @@ -23,11 +32,12 @@ FROM employees | SORT year ``` -Or an hourly error rate: +3. To calculate an hourly error rate: + ```esql FROM sample_data | EVAL error = CASE(message LIKE "*error*", 1, 0) | EVAL hour = DATE_TRUNC(1 hour, @timestamp) -| STATS error_rate = AVG(error) by hour +| STATS error_rate = AVG(error) BY hour | SORT hour -``` +``` \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-dissect.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-dissect.txt index f323c2078a79b..ec764da51518b 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-dissect.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-dissect.txt @@ -1,30 +1,47 @@ -DISSECT - -Syntax -DISSECT input "pattern" [APPEND_SEPARATOR=""] -Parameters -input -The column that contains the string you want to structure. If the column has -multiple values, DISSECT will process each value. -pattern -A dissect pattern. - -A string used as the separator between appended values, when using the append modifier. -DescriptionDISSECT enables you to extract -structured data out of a string. DISSECT matches the string against a -delimiter-based pattern, and extracts the specified keys as columns.Refer to Process data with DISSECT for the syntax of dissect patterns.ExamplesThe following example parses a string that contains a timestamp, some text, and -an IP address: +## DISSECT + +The `DISSECT` command in ES|QL allows you to extract structured data from a string. It matches the string against a delimiter-based pattern and extracts the specified keys as columns. This can be particularly useful when you need to parse a string that contains multiple pieces of information, such as a timestamp, some text, and an IP address. + +### Syntax + +The syntax for the `DISSECT` command is as follows: + + +`DISSECT input "pattern" [APPEND_SEPARATOR=""]` + +Here, `input` is the column that contains the string you want to structure. If the column has multiple values, `DISSECT` will process each value. `pattern` is a dissect pattern that you want to match against the string. `` is an optional string used as the separator between appended values when using the append modifier. + +### Examples + +Here are some examples of how you can use the `DISSECT` command in ES|QL: + +**Example 1:** + ```esql ROW a = "2023-01-23T12:15:00.000Z - some text - 127.0.0.1" | DISSECT a "%{date} - %{msg} - %{ip}" | KEEP date, msg, ip ``` -By default, DISSECT outputs keyword string columns. To convert to another -type, use Type conversion functions: +In this example, the `DISSECT` command is used to parse a string that contains a timestamp, some text, and an IP address. The command matches the string against the pattern `"%{date} - %{msg} - %{ip}"` and extracts the date, message, and IP address as separate columns. + +**Example 2:** + ```esql ROW a = "2023-01-23T12:15:00.000Z - some text - 127.0.0.1" | DISSECT a "%{date} - %{msg} - %{ip}" | KEEP date, msg, ip | EVAL date = TO_DATETIME(date) ``` + +This example is similar to the first one, but it also includes a `TO_DATETIME` function to convert the `date` column to a datetime type. + +**Example 3:** + +```esql +ROW a = "John Doe - john.doe@example.com - 123 Main St" +| DISSECT a "%{name} - %{email} - %{address}" +| KEEP name, email, address +``` + +In this example, the `DISSECT` command is used to parse a string that contains a name, email address, and physical address. The command matches the string against the pattern `"%{name} - %{email} - %{address}"` and extracts the name, email, and address as separate columns. diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-drop.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-drop.txt index f84f9b9613de0..5484d69dd191e 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-drop.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-drop.txt @@ -1,19 +1,46 @@ -DROP +## DROP -Syntax +The `DROP` command in ES|QL is used to remove one or more columns from the data. This can be useful in scenarios where certain columns are not needed for further data processing or analysis. + +The command supports the use of wildcards, allowing for the removal of all columns that match a specific pattern. This can be particularly useful when dealing with large datasets with numerous columns. + +### Syntax + +The syntax for the `DROP` command is as follows: + +``` DROP columns -Parameters -columns -A comma-separated list of columns to remove. Supports wildcards. -DescriptionThe DROP processing command removes one or more columns.Examples +``` + +Here, `columns` is a comma-separated list of columns to be removed. Wildcards are supported. + +### Examples + +Here are some examples of how the `DROP` command can be used in ES|QL queries: + +1. Removing a single column: + ```esql FROM employees | DROP height ``` -Rather than specify each column by name, you can use wildcards to drop all -columns with a name that matches a pattern: +In this example, the `height` column is removed from the `employees` data. + +2. Removing multiple columns: + +```esql +FROM employees +| DROP height, weight, age +``` + +Here, the `height`, `weight`, and `age` columns are all removed from the `employees` data. + +3. Using wildcards to remove all columns that match a pattern: + ```esql FROM employees | DROP height* ``` + +In this example, all columns that start with `height` are removed from the `employees` data. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-e.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-e.txt index 48a4adf1d3186..10bb5d6cd667b 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-e.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-e.txt @@ -1,8 +1,19 @@ -E +## E + +The `E` function in ES|QL returns Euler's number. + +### Examples + +Here are a couple of examples of how you can use the `E` function in ES|QL queries: -Syntax -ParametersDescriptionReturns Euler’s number.Supported types -Example ```esql ROW E() ``` + +This query simply returns the Euler's number. + +```esql +ROW a = E() +``` + +This query assigns the Euler's number to a variable `a`. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-ends_with.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-ends_with.txt new file mode 100644 index 0000000000000..0ea4ca64a5245 --- /dev/null +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-ends_with.txt @@ -0,0 +1,33 @@ +## ENDS_WITH + +The `ENDS_WITH` function in ES|QL is used to check if a keyword string ends with another string. It returns a boolean value indicating the result of this check. + +### Syntax + +The syntax for using the `ENDS_WITH` function is as follows: + +`ENDS_WITH(str, suffix)` + +#### Parameters + +- `str`: This is a string expression. If null, the function returns null. +- `suffix`: This is a string expression. If null, the function returns null. + +### Examples + +Here are a couple of examples showing how to use the `ENDS_WITH` function in ES|QL queries: + +```esql +FROM employees +| KEEP last_name +| EVAL ln_E = ENDS_WITH(last_name, "d") +``` + +In this example, the `ENDS_WITH` function is used to check if the `last_name` of employees ends with the letter "d". The result is stored in the `ln_E` field. + +```esql +FROM logs-* +| WHERE ENDS_WITH(file_path, ".log") +``` + +In this second example, the `ENDS_WITH` function is used in a `WHERE` clause to filter out logs that don't have a file path ending with ".log". \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-enrich.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-enrich.txt index 39b03a08f1c3d..c18a8cddbcb86 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-enrich.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-enrich.txt @@ -1,62 +1,50 @@ -ENRICH - -Syntax -ENRICH policy [ON match_field] [WITH [new_name1 = ]field1, [new_name2 = ]field2, ...] -Parameters -policy -The name of the enrich policy. You need to create -and execute the enrich policy first. -mode -The mode of the enrich command in cross cluster ES|QL. -See enrich across clusters. -match_field -The match field. ENRICH uses its value to look for records in the enrich -index. If not specified, the match will be performed on the column with the same -name as the match_field defined in the enrich policy. -fieldX -The enrich fields from the enrich index that are added to the result as new -columns. If a column with the same name as the enrich field already exists, the -existing column will be replaced by the new column. If not specified, each of -the enrich fields defined in the policy is added -new_nameX -Enables you to change the name of the column that’s added for each of the enrich -fields. Defaults to the enrich field name. -DescriptionENRICH enables you to add data from existing indices as new columns using an -enrich policy. Refer to Data enrichment for information about setting up a -policy. -Before you can use ENRICH, you need to create -and execute an enrich policy. -ExamplesThe following example uses the languages_policy enrich policy to add a new -column for each enrich field defined in the policy. The match is performed using -the match_field defined in the enrich policy and -requires that the input table has a column with the same name (language_code -in this example). ENRICH will look for records in the -enrich index based on the match field value. +## ENRICH + +The `ENRICH` command in ES|QL allows you to add data from existing indices as new columns using an enrich policy. This can be particularly useful when you need to supplement your query data with additional information stored in other indices. + +Before you can use `ENRICH`, you need to create and execute an enrich policy. Refer to the [Data enrichment](https://www.elastic.co/guide/en/elasticsearch/reference/current/ingest-enriching-data.html) documentation for information about setting up a policy. + +Please note that in case of name collisions, the newly created columns will override existing columns. + +### Syntax + +`ENRICH policy [ON match_field] [WITH [new_name1 = ]field1, [new_name2 = ]field2, ...]` + +#### Parameters + +- `policy`: The name of the enrich policy. You need to create and execute the enrich policy first. +- `match_field`: The match field. ENRICH uses its value to look for records in the enrich index. If not specified, the match will be performed on the column with the same name as the match_field defined in the enrich policy. +- `fieldX`: The enrich fields from the enrich index that are added to the result as new columns. If a column with the same name as the enrich field already exists, the existing column will be replaced by the new column. If not specified, each of the enrich fields defined in the policy is added. +- `new_nameX`: Enables you to change the name of the column that’s added for each of the enrich fields. Defaults to the enrich field name. + +### Examples + +The following examples showcase different usages of the `ENRICH` command: + +1. Using the `languages_policy` enrich policy to add a new column for each enrich field defined in the policy. The match is performed using the `match_field` defined in the enrich policy and requires that the input table has a column with the same name (`language_code` in this example). + ```esql ROW language_code = "1" | ENRICH languages_policy ``` -To use a column with a different name than the match_field defined in the -policy as the match field, use ON : +2. Using a column with a different name than the `match_field` defined in the policy as the match field: + ```esql ROW a = "1" | ENRICH languages_policy ON a ``` -By default, each of the enrich fields defined in the policy is added as a -column. To explicitly select the enrich fields that are added, use -WITH , , ...: +3. Explicitly selecting the enrich fields that are added using `WITH , , ...`: + ```esql ROW a = "1" | ENRICH languages_policy ON a WITH language_name ``` -You can rename the columns that are added using WITH new_name=: +4. Renaming the columns that are added using `WITH new_name=`: + ```esql ROW a = "1" | ENRICH languages_policy ON a WITH name = language_name -``` - -In case of name collisions, the newly created columns will override existing -columns. \ No newline at end of file +``` \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-eval.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-eval.txt index 991fae551af1e..f98b4987a9e06 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-eval.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-eval.txt @@ -1,46 +1,44 @@ -EVAL - -Syntax -EVAL [column1 =] value1[, ..., [columnN =] valueN] -Parameters -columnX -The column name. -valueX -The value for the column. Can be a literal, an expression, or a -function. -DescriptionThe EVAL processing command enables you to append new columns with calculated -values. EVAL supports various functions for calculating values. Refer to -Functions for more information.Examples -```esql +## EVAL + +The `EVAL` command in ES|QL allows you to append new columns with calculated values to your data. It supports various functions for calculating these values. This command is particularly useful when you need to perform calculations on your data and store the results in new columns for further analysis or visualization. + +However, it's important to note that if the specified column already exists, the existing column will be dropped, and the new column will be appended to the table. + +### Examples + +Here are some examples of how you can use the `EVAL` command in ES|QL: + +1. Calculate the height of employees in feet and centimeters and store the results in new columns: + + ```esql FROM employees | SORT emp_no | KEEP first_name, last_name, height | EVAL height_feet = height * 3.281, height_cm = height * 100 ``` -If the specified column already exists, the existing column will be dropped, and -the new column will be appended to the table: -```esql +2. Overwrite an existing column with new calculated values: + + ```esql FROM employees | SORT emp_no | KEEP first_name, last_name, height | EVAL height = height * 3.281 ``` -Specifying the output column name is optional. If not specified, the new column -name is equal to the expression. The following query adds a column named -height*3.281: -```esql +3. Add a new column with a name that is equal to the expression: + + ```esql FROM employees | SORT emp_no | KEEP first_name, last_name, height | EVAL height * 3.281 ``` -Because this name contains special characters, it needs to be -quoted with backticks (`) when using it in subsequent commands: -```esql + Since this name contains special characters, it needs to be quoted with backticks (`) when using it in subsequent commands: + + ```esql FROM employees | EVAL height * 3.281 | STATS avg_height_feet = AVG(`height * 3.281`) -``` +``` \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-floor.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-floor.txt index d994fd9439fc4..7daabcc3954f3 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-floor.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-floor.txt @@ -1,16 +1,29 @@ -FLOOR - -Syntax -Parameters -number -Numeric expression. If null, the function returns null. -DescriptionRound a number down to the nearest integer. -This is a noop for long (including unsigned) and integer. -For double this picks the closest double value to the integer -similar to Math.floor. -Supported types -Example +## FLOOR + +The `FLOOR` function in ES|QL is used to round a number down to the nearest integer. This operation is a no-op for long (including unsigned) and integer types. For double types, this function picks the closest double value to the integer, similar to the `Math.floor` function in JavaScript. + +### Syntax + +`FLOOR(number)` + +#### Parameters + +- `number`: Numeric expression. If null, the function returns null. + +### Examples + +Here are a couple of examples of how to use the `FLOOR` function in ES|QL: + ```esql ROW a=1.8 -| EVAL a=FLOOR(a) +| EVAL a = FLOOR(a) +``` + +In this example, the `FLOOR` function is used to round down the value of `a` (1.8) to the nearest integer (1). + +```esql +ROW b=3.14159 +| EVAL b = FLOOR(b) ``` + +In this second example, the `FLOOR` function is used to round down the value of `b` (3.14159) to the nearest integer (3). \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-from.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-from.txt index 54f6b16211fb8..98548000a334e 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-from.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-from.txt @@ -1,63 +1,53 @@ -FROM +## FROM -Syntax -```esql -FROM index_pattern [METADATA fields] -``` - -Parameters -index_pattern -A list of indices, data streams or aliases. Supports wildcards and date math. -fields -A comma-separated list of metadata fields to retrieve. -DescriptionThe -```esql -FROM source command returns a table with data from a data stream, index, -``` +The `FROM` command in ES|QL is a source command that returns a table with data from a data stream, index, or alias. Each row in the resulting table represents a document, and each column corresponds to a field, which can be accessed by the name of that field. -or alias. Each row in the resulting table represents a document. Each column -corresponds to a field, and can be accessed by the name of that field. -By default, an ES|QL query without an explicit LIMIT uses an implicit -limit of 1000. This applies to -```esql -FROM too. A FROM command without LIMIT: -``` +By default, an ES|QL query without an explicit `LIMIT` uses an implicit limit of 1000. This applies to `FROM` too. For example, a `FROM` command without `LIMIT`: ```esql FROM employees ``` is executed as: + ```esql FROM employees | LIMIT 1000 ``` -Examples -```esql -FROM employees -``` +You can use date math to refer to indices, aliases and data streams, which can be useful for time series data. For example, to access today’s index: -You can use date math to refer to indices, aliases -and data streams. This can be useful for time series data, for example to access -today’s index: ```esql FROM ``` -Use comma-separated lists or wildcards to query multiple data streams, indices, -or aliases: +You can use comma-separated lists or wildcards to query multiple data streams, indices, or aliases: + ```esql FROM employees-00001,other-employees-* ``` -Use the format : to query data streams and indices -on remote clusters: +You can also use the format `:` to query data streams and indices on remote clusters: + ```esql FROM cluster_one:employees-00001,cluster_two:other-employees-* ``` -See using ES|QL across clusters.Use the optional METADATA directive to enable metadata fields: +The optional `METADATA` directive can be used to enable metadata fields: + ```esql FROM employees METADATA _id ``` + +### Syntax + +`FROM index_pattern [METADATA fields]` + +#### Parameters + +- `index_pattern`: A list of indices, data streams or aliases. Supports wildcards and date math. +- `fields`: A comma-separated list of metadata fields to retrieve. + +### Limitations + +Please note that the `FROM` command does not support querying time series data streams (TSDS). For more details on the limitations of ES|QL, refer to the [ES|QL limitations](https://www.elastic.co/guide/en/elasticsearch/reference/current/sql-limitations.html) documentation. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-from_base64.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-from_base64.txt index c6a1f21e67090..7e7c6b8ee3ab7 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-from_base64.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-from_base64.txt @@ -1,10 +1,19 @@ -FROM_BASE64 - -Syntax -Parameters -string -A base64 string. -DescriptionDecode a base64 string.Supported types -Example -row a = "ZWxhc3RpYw==" -| eval d = from_base64(a) +## FROM_BASE64 + +FROM_BASE64 function decodes a base64 string. + +### Examples + +Here are a couple of examples of full ES|QL queries using the FROM_BASE64 function: + +Example 1: +```esql +ROW a = "ZWxhc3RpYw==" +| EVAL d = FROM_BASE64(a) +``` + +Example 2: +```esql +ROW b = "SGVsbG8gd29ybGQ=" +| EVAL e = FROM_BASE64(b) +``` \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-functions-overview.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-functions-overview.txt deleted file mode 100644 index 637d66d3ff681..0000000000000 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-functions-overview.txt +++ /dev/null @@ -1,125 +0,0 @@ -Functions overview - - -Aggregate functions -AVG -COUNT -COUNT_DISTINCT -MAX -MEDIAN -MEDIAN_ABSOLUTE_DEVIATION -MIN -PERCENTILE -[preview] -This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. -ST_CENTROID_AGG -SUM -VALUES -Grouping functions -BUCKET -Conditional functions and expressions -CASE -COALESCE -GREATEST -LEAST -Date and time functions -DATE_DIFF -DATE_EXTRACT -DATE_FORMAT -DATE_PARSE -DATE_TRUNC -NOW -IP functions -CIDR_MATCH -Math functions -ABS -ACOS -ASIN -ATAN -ATAN2 -CEIL -COS -COSH -E -FLOOR -LOG -LOG10 -PI -POW -ROUND -SIGNUM -SIN -SINH -SQRT -TAN -TANH -TAU -Spatial functions -[preview] -This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. -ST_INTERSECTS -[preview] -This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. -ST_DISJOINT -[preview] -This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. -ST_CONTAINS -[preview] -This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. -ST_WITHIN -[preview] -This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. -ST_X -[preview] -This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. -ST_Y -String functions -CONCAT -ENDS_WITH -FROM_BASE64 -LEFT -LENGTH -LOCATE -LTRIM -REPLACE -RIGHT -RTRIM -SPLIT -STARTS_WITH -SUBSTRING -TO_BASE64 -TO_LOWER -TO_UPPER -TRIM -Type conversion functions -TO_BOOLEAN -TO_CARTESIANPOINT -TO_CARTESIANSHAPE -TO_DATETIME -TO_DEGREES -TO_DOUBLE -TO_GEOPOINT -TO_GEOSHAPE -TO_INTEGER -TO_IP -TO_LONG -TO_RADIANS -TO_STRING -[preview] -This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. -TO_UNSIGNED_LONG -TO_VERSION -Multi value functions -MV_AVG -MV_CONCAT -MV_COUNT -MV_DEDUPE -MV_FIRST -MV_LAST -MV_MAX -MV_MEDIAN -MV_MIN -MV_SORT -MV_SLICE -MV_SUM -MV_ZIP diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-greatest.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-greatest.txt index 740bb14a7c141..5ab87d292bea4 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-greatest.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-greatest.txt @@ -1,19 +1,30 @@ -GREATEST - -Syntax -Parameters -first -First of the columns to evaluate. -rest -The rest of the columns to evaluate. -DescriptionReturns the maximum value from multiple columns. This is similar to MV_MAX -except it is intended to run on multiple columns at once. -When run on keyword or text fields, this returns the last string - in alphabetical order. When run on boolean columns this will return - true if any values are true. -Supported types -Example +## GREATEST + +The `GREATEST` function in ES|QL returns the maximum value from multiple columns. This function is similar to `MV_MAX` but is intended to run on multiple columns at once. When run on keyword or text fields, this function returns the last string in alphabetical order. When run on boolean columns, this function will return true if any values are true. + +### Syntax + +`GREATEST(first, rest)` + +#### Parameters + +- `first`: First of the columns to evaluate. +- `rest`: The rest of the columns to evaluate. + +### Examples + +Here are a couple of examples of how to use the `GREATEST` function in ES|QL: + ```esql ROW a = 10, b = 20 | EVAL g = GREATEST(a, b) ``` + +In this example, the `GREATEST` function is used to find the maximum value between the columns `a` and `b`. + +```esql +ROW a = 10, b = 20, c = 30, d = 40 +| EVAL g = GREATEST(a, b, c, d) +``` + +In this example, the `GREATEST` function is used to find the maximum value among the columns `a`, `b`, `c`, and `d`. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-grok.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-grok.txt index 4b940e5c2c7f1..9c5e1354e681c 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-grok.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-grok.txt @@ -1,36 +1,42 @@ -GROK - -Syntax -GROK input "pattern" -Parameters -input -The column that contains the string you want to structure. If the column has -multiple values, GROK will process each value. -pattern -A grok pattern. -DescriptionGROK enables you to extract -structured data out of a string. GROK matches the string against patterns, -based on regular expressions, and extracts the specified patterns as columns.Refer to Process data with GROK for the syntax of grok patterns.ExamplesThe following example parses a string that contains a timestamp, an IP address, -an email address, and a number: +## GROK + +The `GROK` command in ES|QL enables you to extract structured data out of a string. It matches the string against patterns, based on regular expressions, and extracts the specified patterns as columns. This can be particularly useful when you need to parse a string that contains multiple pieces of information, such as a timestamp, an IP address, an email address, and a number. + +### Limitations + +By default, `GROK` outputs keyword string columns. Integer (`int`) and float types can be converted by appending `:type` to the semantics in the pattern. For other type conversions, you need to use Type conversion functions. + +### Examples + +Here are some examples of how you can use the `GROK` command in ES|QL: + +**Example 1: Parsing a string with multiple pieces of information** + ```esql ROW a = "2023-01-23T12:15:00.000Z 127.0.0.1 some.email@foo.com 42" | GROK a "%{TIMESTAMP_ISO8601:date} %{IP:ip} %{EMAILADDRESS:email} %{NUMBER:num}" | KEEP date, ip, email, num ``` -By default, GROK outputs keyword string columns. int and float types can -be converted by appending :type to the semantics in the pattern. For example -{NUMBER:num:int}: +In this example, the `GROK` command is used to parse a string that contains a timestamp, an IP address, an email address, and a number. The `KEEP` command is then used to keep only the extracted date, IP, email, and number columns. + +**Example 2: Converting types with GROK** + ```esql ROW a = "2023-01-23T12:15:00.000Z 127.0.0.1 some.email@foo.com 42" | GROK a "%{TIMESTAMP_ISO8601:date} %{IP:ip} %{EMAILADDRESS:email} %{NUMBER:num:int}" | KEEP date, ip, email, num ``` -For other type conversions, use Type conversion functions: +In this example, the `GROK` command is used similarly to the first example, but with an additional `:int` appended to the `NUMBER` semantic in the pattern. This converts the extracted number to an integer type. + +**Example 3: Using type conversion functions with GROK** + ```esql ROW a = "2023-01-23T12:15:00.000Z 127.0.0.1 some.email@foo.com 42" | GROK a "%{TIMESTAMP_ISO8601:date} %{IP:ip} %{EMAILADDRESS:email} %{NUMBER:num:int}" | KEEP date, ip, email, num | EVAL date = TO_DATETIME(date) ``` + +In this example, the `GROK` command is used to parse a string and convert the extracted number to an integer type. Then, the `EVAL` command is used with the `TO_DATETIME` function to convert the extracted date string to a datetime type. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-keep.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-keep.txt index d1a3753abb26e..d51104612b7cb 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-keep.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-keep.txt @@ -1,52 +1,48 @@ -KEEP - -Syntax -KEEP columns -Parameters -columns -A comma-separated list of columns to keep. Supports wildcards. -DescriptionThe KEEP processing command enables you to specify what columns are returned -and the order in which they are returned.Precedence rules are applied when a field name matches multiple expressions. -Fields are added in the order they appear. If one field matches multiple expressions, the following precedence rules apply (from highest to lowest priority): -Complete field name (no wildcards) -Partial wildcard expressions (for example: fieldNam*) -Wildcard only (*) -If a field matches two expressions with the same precedence, the right-most expression wins.Refer to the examples for illustrations of these precedence rules.ExamplesThe columns are returned in the specified order: +## KEEP + +The `KEEP` command in ES|QL allows you to specify which columns are returned and the order in which they are returned. This can be particularly useful when you want to focus on specific data in your Elasticsearch indices and ignore the rest. + +The command supports wildcards, allowing you to match and return all columns with a name that fits a certain pattern. Precedence rules are applied when a field name matches multiple expressions. If a field matches two expressions with the same precedence, the right-most expression wins. + +### Limitations + +There are no known limitations for the `KEEP` command in ES|QL. + +### Examples + +Here are some examples of how you can use the `KEEP` command in ES|QL: + +1. Return specified columns in the order they are listed: + ```esql FROM employees | KEEP emp_no, 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: +2. Use wildcards to return all columns with a name that matches a pattern: + ```esql FROM employees | KEEP 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 h, followed by all other columns: +3. Use the asterisk wildcard by itself to return all columns that do not match the other arguments: + ```esql FROM employees | KEEP h*, * ``` -The following examples show how precedence rules work when a field name matches multiple expressions.Complete field name has precedence over wildcard expressions: -```esql -FROM employees -| KEEP first_name, last_name, first_name* -``` +4. Show how precedence rules work when a field name matches multiple expressions: -Wildcard expressions have the same priority, but last one wins (despite being less specific): ```esql FROM employees | KEEP first_name*, last_name, first_na* ``` -A simple wildcard expression * has the lowest precedence. -Output order is determined by the other arguments: +5. Use a simple wildcard expression `*` which has the lowest precedence: + ```esql FROM employees | KEEP *, first_name -``` +``` \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-kibana.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-kibana.txt deleted file mode 100644 index 798a9befd7647..0000000000000 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-kibana.txt +++ /dev/null @@ -1,158 +0,0 @@ - -Using ES|QL in Kibanaedit -You can use ES|QL in Kibana to query and aggregate your data, create -visualizations, and set up alerts. -This guide shows you how to use ES|QL in Kibana. To follow along with the -queries, load the "Sample web logs" sample data set by clicking Try sample -data from the Kibana Home, selecting Other sample data sets, and clicking Add -data on the Sample web logs card. -Get started with ES|QLedit -To get started with ES|QL in Discover, open the main menu and select -Discover. Next, from the Data views menu, select Try ES|QL. -The ability to select ES|QL from the Data views menu can be enabled and -disabled using the `discover:enableESQL` setting from -Advanced Settings. -The query baredit -After switching to ES|QL mode, the query bar shows a sample query. For example: -from kibana_sample_data_logs | limit 10 -Every query starts with a source command. In this query, the -source command is `FROM`. `FROM` retrieves data from data streams, indices, or -aliases. In this example, the data is retrieved from `kibana_sample_data_logs`. -A source command can be followed by one or more processing -commands. In this query, the processing command is `LIMIT`. `LIMIT` -limits the number of rows that are retrieved. -Click the help icon () to open the -in-product reference documentation for all commands and functions. -To make it easier to write queries, auto-complete offers suggestions with -possible commands and functions: -ES|QL keywords are case-insensitive. The following query is identical to the -previous one: -```esql -FROM kibana_sample_data_logs | LIMIT 10 -``` - -Expand the query baredit -For readability, you can put each processing command on a new line. The -following query is identical to the previous one: -```esql -FROM kibana_sample_data_logs -| LIMIT 10 -``` - -To make it easier to write multi-line queries, click the double-headed arrow -button () to expand the query -bar: -To return to a compact query bar, click the minimize editor button -(). -Warningsedit -A query may result in warnings, for example when querying an unsupported field -type. When that happens, a warning symbol is shown in the query bar. To see the -detailed warning, expand the query bar, and click warnings. -The results tableedit -For the example query, the results table shows 10 rows. Omitting the `LIMIT` -command, the results table defaults to up to 1000 rows. Using `LIMIT`, you can -increase the limit to up to 10,000 rows. -the 10,000 row limit only applies to the number of rows that are retrieved -by the query and displayed in Discover. Any query or aggregation runs on the -full data set. -Each row shows two columns for the example query: a column with the `@timestamp` -field and a column with the full document. To display specific fields from the -documents, use the `KEEP` command: -```esql -FROM kibana_sample_data_logs -| KEEP @timestamp, bytes, geo.dest -``` - -To display all fields as separate columns, use `KEEP *`: -```esql -FROM kibana_sample_data_logs -| KEEP * -``` - -The maximum number of columns in Discover is 50. If a query returns more -than 50 columns, Discover only shows the first 50. -Sortingedit -To sort on one of the columns, click the column name you want to sort on and -select the sort order. Note that this performs client-side sorting. It only -sorts the rows that were retrieved by the query, which may not be the full -dataset because of the (implicit) limit. To sort the full data set, use the -`SORT` command: -```esql -FROM kibana_sample_data_logs -| KEEP @timestamp, bytes, geo.dest -| SORT bytes DESC -``` - -Time filteringedit -To display data within a specified time range, use the -time filter. The time filter is only enabled -when the indices you’re querying have a field called `@timestamp`. -If your indices do not have a timestamp field called `@timestamp`, you can limit -the time range using the `WHERE` command and the `NOW` function. -For example, if the timestamp field is called `timestamp`, to query the last 15 -minutes of data: -```esql -FROM kibana_sample_data_logs -| WHERE timestamp > NOW() - 15minutes -``` - -Analyze and visualize dataedit -Between the query bar and the results table, Discover shows a date histogram -visualization. If the indices you’re querying do not contain an `@timestamp` -field, the histogram is not shown. -The visualization adapts to the query. A query’s nature determines the type of -visualization. For example, this query aggregates the total number of bytes per -destination country: -```esql -FROM kibana_sample_data_logs -| STATS total_bytes = SUM(bytes) BY geo.dest -| SORT total_bytes DESC -| LIMIT 3 -``` - -The resulting visualization is a bar chart showing the top 3 countries: -To change the visualization into another type, click the visualization type -dropdown: -To make other changes to the visualization, like the axes and colors, click the -pencil button (). This opens -an in-line editor: -You can save the visualization to a new or existing dashboard by clicking the -save button (). Once saved -to a dashboard, you can continue to make changes to visualization. Click the -options button in the top-right () and -select Edit ESQL visualization to open the in-line editor: -Create an enrich policyedit -The ES|QL `ENRICH` command enables you to enrich -your query dataset with fields from another dataset. Before you can use -`ENRICH`, you need to create and execute an enrich -policy. If a policy exists, it will be suggested by auto-complete. If not, -click Click to create to create one. -Next, you can enter a policy name, the policy type, source indices, and -optionally a query: -Click Next to select the match field and enrich fields: -Finally, click Create and execute. -Now, you can use the enrich policy in an ES|QL query: -Create an alerting ruleedit -You can use ES|QL queries to create alerts. From Discover, click Alerts and -select Create search threshold rule. This opens a panel that enables you to -create a rule using an ES|QL query. Next, you can test the query, add a -connector, and save the rule. -Limitationsedit -The user interface to filter data is not enabled when Discover is in ES|QL -mode. To filter data, write a query that uses the `WHERE` command -instead. -In ES|QL mode, clicking a field in the field list in Discover does not show -quick statistics for that field. -Discover shows no more than 10,000 rows. This limit only applies to the number -of rows that are retrieved by the query and displayed in Discover. Queries and -aggregations run on the full data set. -Discover shows no more than 50 columns. If a query returns -more than 50 columns, Discover only shows the first 50. -CSV export from Discover shows no more than 10,000 rows. This limit only applies to the number -of rows that are retrieved by the query and displayed in Discover. Queries and -aggregations run on the full data set. -Querying many indices at once without any filters can cause an error in -kibana which looks like `[esql] > Unexpected error from Elasticsearch: The -content length (536885793) is bigger than the maximum allowed string -(536870888)`. The response from ES|QL is too long. Use `DROP` or -`KEEP` to limit the number of fields returned. diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-least.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-least.txt index ee76f5a43ac0d..4c34db4d38e01 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-least.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-least.txt @@ -1,19 +1,30 @@ -LEAST - -Syntax -Parameters -first -First of the columns to evaluate. -rest -The rest of the columns to evaluate. -DescriptionReturns the minimum value from multiple columns. This is similar to -MV_MIN except it is intended to run on multiple columns at once. -When run on keyword or text fields, this returns the first string - in alphabetical order. When run on boolean columns this will return - false if any values are false. -Supported types -Example +## LEAST + +The `LEAST` function in ES|QL is used to return the minimum value from multiple columns. This function is similar to `MV_MIN` but is intended to run on multiple columns at once. + +### Syntax + +`LEAST(first, rest)` + +#### Parameters + +- `first`: The first column to evaluate. +- `rest`: The rest of the columns to evaluate. + +### Examples + +Here are a couple of examples of how to use the `LEAST` function in ES|QL: + ```esql ROW a = 10, b = 20 | EVAL l = LEAST(a, b) ``` + +In this example, the `LEAST` function is used to find the minimum value between the columns `a` and `b`. + +```esql +ROW a = 10, b = 20, c = 30, d = 40 +| EVAL l = LEAST(a, b, c, d) +``` + +In this second example, the `LEAST` function is used to find the minimum value among four columns: `a`, `b`, `c`, and `d`. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-left.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-left.txt index 1aae39f111122..e62a50ae7a273 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-left.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-left.txt @@ -1,13 +1,20 @@ -LEFT - -Syntax -Parameters -string -The string from which to return a substring. -length -The number of characters to return. -DescriptionReturns the substring that extracts length chars from string starting from the left.Supported types -Example +## LEFT + +The `LEFT` function in ES|QL is used to extract a substring from a string, starting from the left. The number of characters to return is specified by the `length` parameter. + +### Syntax + +`LEFT(string, length)` + +#### Parameters + +- `string`: The string from which to return a substring. +- `length`: The number of characters to return. + +### Examples + +Here are a couple of examples of how to use the `LEFT` function in ES|QL: + ```esql FROM employees | KEEP last_name @@ -15,3 +22,12 @@ FROM employees | SORT last_name ASC | LIMIT 5 ``` + +In this example, the `LEFT` function is used to extract the first three characters from the `last_name` field of the `employees` index. The query then sorts the results in ascending order by `last_name` and limits the output to the first 5 records. + +```esql +FROM logs-* +| EVAL left_chars = LEFT(message, 10) +``` + +In this second example, the `LEFT` function is used to extract the first 10 characters from the `message` field of the `logs-*` index. The result is stored in the `left_chars` field. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-length.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-length.txt index e63ea02da87eb..8ed8bf3f31a2c 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-length.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-length.txt @@ -1,13 +1,29 @@ -LENGTH - -Syntax -Parameters -string -String expression. If null, the function returns null. -DescriptionReturns the character length of a string.Supported types -Example +## LENGTH + +The `LENGTH` function in ES|QL is used to return the character length of a string. + +### Syntax + +`LENGTH(string)` + +#### Parameters + +- `string`: This is a string expression. If null, the function returns null. + +### Examples + +Here are a couple of examples of how you can use the `LENGTH` function in ES|QL: + ```esql FROM employees -| KEEP first_name, last_name -| EVAL fn_length = LENGTH(first_name) +| EVAL name_length = LENGTH(first_name) +``` + +In this example, the `LENGTH` function is used to calculate the length of the `first_name` field for each record in the `employees` index. + +```esql +FROM logs-* +| EVAL message_length = LENGTH(message) ``` + +In this second example, the `LENGTH` function is used to calculate the length of the `message` field for each record in the `logs-*` index. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-limit.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-limit.txt index 5ee1f5fd6999d..4d0dce6fe6edd 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-limit.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-limit.txt @@ -1,26 +1,42 @@ -LIMIT - -Syntax -LIMIT max_number_of_rows -Parameters -max_number_of_rows -The maximum number of rows to return. -DescriptionThe LIMIT processing command enables you to limit the number of rows that are -returned. -Queries do not return more than 10,000 rows, regardless of the LIMIT command’s -value.This limit only applies to the number of rows that are retrieved by the query. -Queries and aggregations run on the full data set.To overcome this limitation: -Reduce the result set size by modifying the query to only return relevant -data. Use WHERE to select a smaller subset of the data. -Shift any post-query processing to the query itself. You can use the ES|QL -STATS ... BY command to aggregate data in the query. -The default and maximum limits can be changed using these dynamic cluster -settings: -esql.query.result_truncation_default_size -esql.query.result_truncation_max_size -Example -```esql +## LIMIT + +The `LIMIT` command in ES|QL is a processing command that allows you to limit the number of rows that are returned in a query. This can be particularly useful in scenarios where you only need a specific number of rows from a larger dataset. + +However, it's important to note that queries do not return more than 10,000 rows, regardless of the `LIMIT` command’s value. This limit only applies to the number of rows that are retrieved by the query. Queries and aggregations run on the full data set. + +To overcome this limitation, you can: + +- Reduce the result set size by modifying the query to only return relevant data. Use `WHERE` to select a smaller subset of the data. +- Shift any post-query processing to the query itself. You can use the ES|QL `STATS ... BY` command to aggregate data in the query. + +The default and maximum limits can be changed using these dynamic cluster settings: + +- `esql.query.result_truncation_default_size` +- `esql.query.result_truncation_max_size` + +### Examples + +Here are some examples of how you can use the `LIMIT` command in ES|QL: + +1. Limit the number of rows returned to 5, sorted by employee number in ascending order: + + ```esql FROM employees | SORT emp_no ASC | LIMIT 5 ``` + +2. Retrieve only the top 10 employees with the highest salary: + + ```esql +FROM employees +| SORT salary DESC +| LIMIT 10 +``` + +3. Get the first 100 rows from a logs data stream: + + ```esql +FROM logs-* +| LIMIT 100 +``` \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-limitations.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-limitations.txt deleted file mode 100644 index 03c4cf1416eb6..0000000000000 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-limitations.txt +++ /dev/null @@ -1,166 +0,0 @@ - -You are looking at preliminary documentation for a future release. -Not what you want? See the -current release documentation. -Elastic Docs -›Elasticsearch Guide [master] -›ES|QL -« ES|QL language versions -ES|QL examples » -ES|QL limitationsedit -Result set size limitedit -By default, an ES|QL query returns up to 1000 rows. You can increase the number -of rows up to 10,000 using the `LIMIT` command. -Queries do not return more than 10,000 rows, regardless of the `LIMIT` command’s -value. -This limit only applies to the number of rows that are retrieved by the query. -Queries and aggregations run on the full data set. -To overcome this limitation: -Reduce the result set size by modifying the query to only return relevant -data. Use `WHERE` to select a smaller subset of the data. -Shift any post-query processing to the query itself. You can use the ES|QL -`STATS ... BY` command to aggregate data in the query. -The default and maximum limits can be changed using these dynamic cluster -settings: -`esql.query.result_truncation_default_size` -`esql.query.result_truncation_max_size` -Field typesedit -Supported typesedit -ES|QL currently supports the following field types: -`alias` -`boolean` -`date` -`double` (`float`, `half_float`, `scaled_float` are represented as `double`) -`ip` -`keyword` family including `keyword`, `constant_keyword`, and `wildcard` -`int` (`short` and `byte` are represented as `int`) -`long` -`null` -`text` -[preview] -This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. -`unsigned_long` -`version` -Spatial types -`geo_point` -`geo_shape` -`point` -`shape` -Unsupported typesedit -ES|QL does not yet support the following field types: -TSDB metrics -`counter` -`position` -`aggregate_metric_double` -Date/time -`date_nanos` -`date_range` -Other types -`binary` -`completion` -`dense_vector` -`double_range` -`flattened` -`float_range` -`histogram` -`integer_range` -`ip_range` -`long_range` -`nested` -`rank_feature` -`rank_features` -`search_as_you_type` -Querying a column with an unsupported type returns an error. If a column with an -unsupported type is not explicitly used in a query, it is returned with `null` -values, with the exception of nested fields. Nested fields are not returned at -all. -Limitations on supported typesedit -Some field types are not supported in all contexts: -Spatial types are not supported in the SORT processing command. -Specifying a column of one of these types as a sort parameter will result in an error: -`geo_point` -`geo_shape` -`cartesian_point` -`cartesian_shape` -_source availabilityedit -ES|QL does not support configurations where the -_source field is disabled. -[preview] -This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. -ES|QL’s support for synthetic `_source` -is currently experimental. -Full-text search is not supportededit -Because of the way ES|QL treats `text` values, -full-text search is not yet supported. Queries on `text` fields are like queries -on `keyword` fields: they are case-sensitive and need to match the full string. -For example, after indexing a field of type `text` with the value `Elasticsearch -query language`, the following `WHERE` clause does not match because the `LIKE` -operator is case-sensitive: -| WHERE field LIKE "elasticsearch query language" -The following `WHERE` clause does not match either, because the `LIKE` operator -tries to match the whole string: -| WHERE field LIKE "Elasticsearch" -As a workaround, use wildcards and regular expressions. For example: -| WHERE field RLIKE "[Ee]lasticsearch.*" -`text` fields behave like `keyword` fieldsedit -While ES|QL supports `text` fields, ES|QL does not treat these fields -like the Search API does. ES|QL queries do not query or aggregate the -analyzed string. Instead, an ES|QL query will try to get a `text` -field’s subfield of the keyword family type and query/aggregate -that. If it’s not possible to retrieve a `keyword` subfield, ES|QL will get the -string from a document’s `_source`. If the `_source` cannot be retrieved, for -example when using synthetic source, `null` is returned. -Note that ES|QL’s retrieval of `keyword` subfields may have unexpected -consequences. An ES|QL query on a `text` field is case-sensitive. Furthermore, -a subfield may have been mapped with a normalizer, which can -transform the original string. Or it may have been mapped with `ignore_above`, -which can truncate the string. None of these mapping operations are applied to -an ES|QL query, which may lead to false positives or negatives. -To avoid these issues, a best practice is to be explicit about the field that -you query, and query `keyword` sub-fields instead of `text` fields. -Time series data streams are not supportededit -ES|QL does not support querying time series data streams (TSDS). -Date math limitationsedit -Date math expressions work well when the leftmost expression is a datetime, for -example: -now() + 1 year - 2hour + ... -But using parentheses or putting the datetime to the right is not always supported yet. For example, the following expressions fail: -1year + 2hour + now() -now() + (1year + 2hour) -Date math does not allow subtracting two datetimes, for example: -now() - 2023-10-26 -Enrich limitationsedit -The ES|QL `ENRICH` command only supports enrich policies of type `match`. -Furthermore, `ENRICH` only supports enriching on a column of type `keyword`. -Dissect limitationsedit -The `DISSECT` command does not support reference keys. -Grok limitationsedit -The `GROK` command does not support configuring custom -patterns, or multiple patterns. The `GROK` command is not -subject to Grok watchdog settings. -Multivalue limitationsedit -ES|QL supports multivalued fields, but functions -return `null` when applied to a multivalued field, unless documented otherwise. -Work around this limitation by converting the field to single value with one of -the multivalue functions. -Timezone supportedit -ES|QL only supports the UTC timezone. -Kibana limitationsedit -The user interface to filter data is not enabled when Discover is in ES|QL -mode. To filter data, write a query that uses the `WHERE` command -instead. -In ES|QL mode, clicking a field in the field list in Discover does not show -quick statistics for that field. -Discover shows no more than 10,000 rows. This limit only applies to the number -of rows that are retrieved by the query and displayed in Discover. Queries and -aggregations run on the full data set. -Discover shows no more than 50 columns. If a query returns -more than 50 columns, Discover only shows the first 50. -CSV export from Discover shows no more than 10,000 rows. This limit only applies to the number -of rows that are retrieved by the query and displayed in Discover. Queries and -aggregations run on the full data set. -Querying many indices at once without any filters can cause an error in -kibana which looks like `[esql] > Unexpected error from Elasticsearch: The -content length (536885793) is bigger than the maximum allowed string -(536870888)`. The response from ES|QL is too long. Use `DROP` or -`KEEP` to limit the number of fields returned. diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-locate.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-locate.txt index 0c47550b219dc..605a287841440 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-locate.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-locate.txt @@ -1,14 +1,35 @@ -LOCATE - -Syntax -Parameters -string -An input string -substring -A substring to locate in the input string -start -The start index -DescriptionReturns an integer that indicates the position of a keyword substring within another stringSupported types -Example -row a = "hello" -| eval a_ll = locate(a, "ll") +## LOCATE + +LOCATE function in ES|QL returns an integer that indicates the position of a keyword substring within another string. + +### Syntax + +`LOCATE(string, substring, start)` + +#### Parameters + +- `string`: An input string +- `substring`: A substring to locate in the input string +- `start`: The start index + +### Examples + +Here are a couple of examples of how you can use the LOCATE function in ES|QL: + +Example 1: + +```esql +ROW a = "hello" +| EVAL a_ll = LOCATE(a, "ll") +``` + +In this example, the LOCATE function is used to find the position of the substring "ll" in the string "hello". The result would be `3` as "ll" starts at the third position in the string "hello". + +Example 2: + +```esql +ROW a = "Elasticsearch Query Language" +| EVAL a_ll = LOCATE(a, "Query", 5) +``` + +In this example, the LOCATE function is used to find the position of the substring "Query" in the string "Elasticsearch Query Language", starting from the fifth position. The result would be `14` as "Query" starts at the fourteenth position in the string "Elasticsearch Query Language". \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-log.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-log.txt index c3e97b9fe5fcf..69a19c5578f14 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-log.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-log.txt @@ -1,17 +1,30 @@ -LOG - -Syntax -Parameters -base -Base of logarithm. If null, the function returns null. If not provided, this function returns the natural logarithm (base e) of a value. -number -Numeric expression. If null, the function returns null. -DescriptionReturns the logarithm of a value to a base. The input can be any numeric value, the return value is always a double. Logs of zero, negative numbers, and base of one return null as well as a warning.Supported types -Examples +## LOG + +The `LOG` function in ES|QL returns the logarithm of a value to a base. The input can be any numeric value, and the return value is always a double. Logs of zero, negative numbers, and base of one return null as well as a warning. + +### Syntax + +`LOG(base, number)` + +#### Parameters + +- `base`: Base of logarithm. If null, the function returns null. If not provided, this function returns the natural logarithm (base e) of a value. +- `number`: Numeric expression. If null, the function returns null. + +### Examples + +Here are a couple of examples of full ES|QL queries using the `LOG` function: + ```esql ROW base = 2.0, value = 8.0 | EVAL s = LOG(base, value) ``` -row value = 100 -| EVAL s = LOG(value); +In this example, the `LOG` function is used to calculate the logarithm of `8.0` to the base `2.0`. + +```esql +ROW value = 100 +| EVAL s = LOG(value) +``` + +In this example, the `LOG` function is used to calculate the natural logarithm (base e) of `100` as no base is provided. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-log10.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-log10.txt index 5fbe4a94cd683..78a0b43a087a8 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-log10.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-log10.txt @@ -1,12 +1,21 @@ -LOG10 - -Syntax -Parameters -number -Numeric expression. If null, the function returns null. -DescriptionReturns the logarithm of a value to base 10. The input can be any numeric value, the return value is always a double. Logs of 0 and negative numbers return null as well as a warning.Supported types -Example +## LOG10 + +The `LOG10` function in ES|QL is used to calculate the logarithm of a value to the base 10. The input can be any numeric value and the return value is always a double. If the input is 0 or a negative number, the function returns null and a warning. + +### Examples + +Here are a couple of examples of how you can use the `LOG10` function in ES|QL queries: + ```esql ROW d = 1000.0 | EVAL s = LOG10(d) ``` + +In this example, the `LOG10` function is used to calculate the base 10 logarithm of the value 1000. The result is stored in the variable `s`. + +```esql +ROW d = 100.0 +| EVAL s = LOG10(d) +``` + +In this example, the `LOG10` function is used to calculate the base 10 logarithm of the value 100. The result is stored in the variable `s`. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-lookup.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-lookup.txt new file mode 100644 index 0000000000000..46dc960ac1332 --- /dev/null +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-lookup.txt @@ -0,0 +1,82 @@ +## LOOKUP + +The `LOOKUP` command in ES|QL is a highly experimental feature that is currently only available in SNAPSHOT versions. This command is used to match values from the input against a table provided in the request, adding the other fields from the table to the output. + +### Use Cases and Limitations + +The `LOOKUP` command is particularly useful when you need to match and compare data from different sources or tables. It allows you to enrich your query results with additional data from a separate table based on matching fields. + +However, it's important to note that this command is still in the experimental stage and may not be fully stable or support all use cases. It's recommended to use this command in testing environments and not in production. + +### Examples + +Here are some examples of how to use the `LOOKUP` command in ES|QL: + +**Example 1:** + +``` +POST /_query?format=txt +{ + "query": """ + FROM library + | SORT page_count DESC + | KEEP name, author + | LOOKUP era ON author + | LIMIT 5 + """ + "tables": { + "era": { + "author:keyword": ["Frank Herbert", "Peter F. Hamilton", "Vernor Vinge", "Alastair Reynolds", "James S.A. Corey"], + "era:keyword" : [ "The New Wave", "Diamond", "Diamond", "Diamond", "Hadron"] + } + } +} +``` + +In this example, the `LOOKUP` command is used to match the `author` field from the `library` index with the `author` field in the `era` table. The matched data is then added to the output. + +**Example 2:** + +``` +POST /_query?format=txt +{ + "query": """ + FROM employees + | SORT salary DESC + | KEEP name, department + | LOOKUP departments ON department + | LIMIT 10 + """ + "tables": { + "departments": { + "department:keyword": ["Sales", "Marketing", "HR", "Engineering"], + "location:keyword" : [ "New York", "San Francisco", "London", "Berlin"] + } + } +} +``` + +In this example, the `LOOKUP` command is used to match the `department` field from the `employees` index with the `department` field in the `departments` table. The matched data is then added to the output. + +**Example 3:** + +``` +POST /_query?format=txt +{ + "query": """ + FROM orders + | SORT order_date DESC + | KEEP order_id, product_id + | LOOKUP products ON product_id + | LIMIT 20 + """ + "tables": { + "products": { + "product_id:keyword": ["P001", "P002", "P003", "P004"], + "product_name:keyword" : [ "Product 1", "Product 2", "Product 3", "Product 4"] + } + } +} +``` + +In this example, the `LOOKUP` command is used to match the `product_id` field from the `orders` index with the `product_id` field in the `products` table. The matched data is then added to the output. diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-ltrim.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-ltrim.txt index e98ccd0ce65d1..9a6b50d702a98 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-ltrim.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-ltrim.txt @@ -1,15 +1,29 @@ -LTRIM - -Syntax -Parameters -string -String expression. If null, the function returns null. -DescriptionRemoves leading whitespaces from a string.Supported types -Example +## LTRIM + +The `LTRIM` function is used to remove leading whitespaces from a string. + +### Syntax + +`LTRIM(string)` + +#### Parameters + +- `string`: String expression. If null, the function returns null. + +### Examples + +Here are a couple of examples of how you can use the `LTRIM` function in ES|QL queries: + +```esql +ROW message = " some text " +| EVAL trimmed_message = LTRIM(message) +``` + +In this example, the `LTRIM` function is used to remove the leading whitespaces from the `message` string. + ```esql -ROW message = " some text ", color = " red " -| EVAL message = LTRIM(message) -| EVAL color = LTRIM(color) -| EVAL message = CONCAT("'", message, "'") -| EVAL color = CONCAT("'", color, "'") +ROW color = " red " +| EVAL trimmed_color = LTRIM(color) ``` + +In this example, the `LTRIM` function is used to remove the leading whitespace from the `color` string. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-max.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-max.txt index fe4522d77d692..32dad967274d8 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-max.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-max.txt @@ -1,20 +1,29 @@ -MAX - -Syntax -MAX(expression) -Parameters -expression -Expression from which to return the maximum value. -DescriptionReturns the maximum value of a numeric expression.Example +## MAX + +The `MAX` function in ES|QL is used to return the maximum value of a numeric expression. + +### Syntax + +`MAX(expression)` + +#### Parameters + +`expression`: The expression from which to return the maximum value. + +### Examples + +Here are a couple of examples of how the `MAX` function can be used in ES|QL queries: + +1. To find the maximum value in the `languages` field from the `employees` index, you can use the following query: + ```esql FROM employees | STATS MAX(languages) ``` -The expression can use inline functions. For example, to calculate the maximum -over an average of a multivalued column, use MV_AVG to first average the -multiple values per row, and use the result with the MAX function: +2. The `MAX` function can also be used with inline functions. For instance, to calculate the maximum over an average of a multivalued column, you can first use the `MV_AVG` function to average the multiple values per row, and then use the result with the `MAX` function: + ```esql FROM employees | STATS max_avg_salary_change = MAX(MV_AVG(salary_change)) -``` +``` \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-median.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-median.txt index 6f365afd34aec..b4a8810047d41 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-median.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-median.txt @@ -1,25 +1,21 @@ -MEDIAN +## MEDIAN + +The `MEDIAN` function in ES|QL returns the value that is greater than half of all values and less than half of all values, also known as the 50% PERCENTILE. Like `PERCENTILE`, `MEDIAN` is usually approximate and is also non-deterministic. This means you can get slightly different results using the same data. + +### Examples + +Here are a couple of examples of how to use the `MEDIAN` function in ES|QL: -Syntax -MEDIAN(expression) -Parameters -expression -Expression from which to return the median value. -DescriptionReturns the value that is greater than half of all values and less than half of -all values, also known as the 50% PERCENTILE. -Like PERCENTILE, MEDIAN is usually approximate. -MEDIAN is also non-deterministic. -This means you can get slightly different results using the same data. -Example ```esql FROM employees | STATS MEDIAN(salary), PERCENTILE(salary, 50) ``` -The expression can use inline functions. For example, to calculate the median of -the maximum values of a multivalued column, first use MV_MAX to get the -maximum value per row, and use the result with the MEDIAN function: +In this example, the `MEDIAN` function is used to calculate the median salary from the `employees` data stream or index. + ```esql FROM employees | STATS median_max_salary_change = MEDIAN(MV_MAX(salary_change)) ``` + +In this example, the `MEDIAN` function is used in conjunction with the `MV_MAX` function to calculate the median of the maximum values of a multivalued column `salary_change`. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-median_absolute_deviation.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-median_absolute_deviation.txt index 0098c9ca8f3eb..1ef1732218e11 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-median_absolute_deviation.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-median_absolute_deviation.txt @@ -1,31 +1,33 @@ -MEDIAN_ABSOLUTE_DEVIATION - -Syntax -MEDIAN_ABSOLUTE_DEVIATION(expression) -Parameters -expression -Expression from which to return the median absolute deviation. -DescriptionReturns the median absolute deviation, a measure of variability. It is a robust -statistic, meaning that it is useful for describing data that may have outliers, -or may not be normally distributed. For such data it can be more descriptive -than standard deviation.It is calculated as the median of each data point’s deviation from the median of -the entire sample. That is, for a random variable X, the median absolute -deviation is median(|median(X) - X|). -Like PERCENTILE, MEDIAN_ABSOLUTE_DEVIATION is - usually approximate. -MEDIAN_ABSOLUTE_DEVIATION is also non-deterministic. -This means you can get slightly different results using the same data. -Example +## MEDIAN_ABSOLUTE_DEVIATION + +The `MEDIAN_ABSOLUTE_DEVIATION` function is a robust statistic that is useful for describing data that may have outliers or may not be normally distributed. It provides a measure of variability by calculating the median of each data point’s deviation from the median of the entire sample. + +This function is usually approximate and non-deterministic, meaning that you can get slightly different results using the same data. + +### Syntax: + +`MEDIAN_ABSOLUTE_DEVIATION(expression)` + +#### Parameters: + +- `expression`: Expression from which to return the median absolute deviation. + +### Examples: + +Here is an example of a complete ES|QL query using the `MEDIAN_ABSOLUTE_DEVIATION` function: + ```esql FROM employees | STATS MEDIAN(salary), MEDIAN_ABSOLUTE_DEVIATION(salary) ``` -The expression can use inline functions. For example, to calculate the the -median absolute deviation of the maximum values of a multivalued column, first -use MV_MAX to get the maximum value per row, and use the result with the -MEDIAN_ABSOLUTE_DEVIATION function: +In this query, the `MEDIAN_ABSOLUTE_DEVIATION` function is used to calculate the median absolute deviation of the `salary` field for the `employees` index. + +The `MEDIAN_ABSOLUTE_DEVIATION` function can also be used with inline functions. Here is an example where it is used with the `MV_MAX` function to calculate the median absolute deviation of the maximum values of a multivalued column: + ```esql FROM employees | STATS m_a_d_max_salary_change = MEDIAN_ABSOLUTE_DEVIATION(MV_MAX(salary_change)) ``` + +In this query, the `MV_MAX` function is first used to get the maximum value per row of the `salary_change` field. The result is then used with the `MEDIAN_ABSOLUTE_DEVIATION` function to calculate the median absolute deviation. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-min.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-min.txt index 7b205f00e0784..737a21bb6cd99 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-min.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-min.txt @@ -1,20 +1,29 @@ -MIN - -Syntax -MIN(expression) -Parameters -expression -Expression from which to return the minimum value. -DescriptionReturns the minimum value of a numeric expression.Example +## MIN + +The `MIN` function in ES|QL is used to return the minimum value of a numeric expression. + +### Syntax: + +`MIN(expression)` + +#### Parameters: + +`expression`: The expression from which to return the minimum value. + +### Examples: + +Here are a couple of examples of how you can use the `MIN` function in ES|QL: + +1. To find the minimum value of a field, you can use the `MIN` function directly. For example, the following query returns the minimum value of the `languages` field from the `employees` index: + ```esql FROM employees | STATS MIN(languages) ``` -The expression can use inline functions. For example, to calculate the minimum -over an average of a multivalued column, use MV_AVG to first average the -multiple values per row, and use the result with the MIN function: +2. You can also use the `MIN` function with other functions like `MV_AVG` to perform more complex calculations. For example, the following query calculates the average of a multivalued column `salary_change` for each row, and then finds the minimum of these averages: + ```esql FROM employees | STATS min_avg_salary_change = MIN(MV_AVG(salary_change)) -``` +``` \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-mv_avg.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-mv_avg.txt index 7959297c1cb23..1dcdf012ef0db 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-mv_avg.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-mv_avg.txt @@ -1,12 +1,29 @@ -MV_AVG - -Syntax -Parameters -number -Multivalue expression. -DescriptionConverts a multivalued field into a single valued field containing the average of all of the values.Supported types -Example +## MV_AVG + +The `MV_AVG` function in ES|QL converts a multivalued field into a single valued field containing the average of all of the values. + +### Syntax + +`MV_AVG(number)` + +#### Parameters + +`number`: Multivalue expression. + +### Examples + +Here are a couple of examples of how you can use the `MV_AVG` function in your ES|QL queries: + ```esql ROW a=[3, 5, 1, 6] | EVAL avg_a = MV_AVG(a) ``` + +In this example, the `MV_AVG` function is used to calculate the average of the values in the multivalued field `a`. + +```esql +ROW b=[10, 20, 30, 40] +| EVAL avg_b = MV_AVG(b) +``` + +In this second example, the `MV_AVG` function is used to calculate the average of the values in the multivalued field `b`. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-mv_concat.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-mv_concat.txt index d8768bc34bdef..f2699a0ac7a87 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-mv_concat.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-mv_concat.txt @@ -1,20 +1,23 @@ -MV_CONCAT - -Syntax -Parameters -string -Multivalue expression. -delim -Delimiter. -DescriptionConverts a multivalued string expression into a single valued column containing the concatenation of all values separated by a delimiter.Supported types -Examples +## MV_CONCAT + +The `MV_CONCAT` function in ES|QL converts a multivalued string expression into a single valued column. It does this by concatenating all values separated by a specified delimiter. + +### Examples + +Here are a couple of examples of how you can use the `MV_CONCAT` function in your ES|QL queries: + ```esql ROW a=["foo", "zoo", "bar"] | EVAL j = MV_CONCAT(a, ", ") ``` -To concat non-string columns, call TO_STRING first: +In this example, the `MV_CONCAT` function is used to concatenate the values in the array `a` with a comma separator. The result is a single string `"foo, zoo, bar"`. + +If you need to concatenate non-string columns, you can use the `TO_STRING` function first: + ```esql ROW a=[10, 9, 8] | EVAL j = MV_CONCAT(TO_STRING(a), ", ") ``` + +In this case, the numeric values in the array `a` are first converted to strings using the `TO_STRING` function. Then, the `MV_CONCAT` function concatenates these string values with a comma separator. The result is a single string `"10, 9, 8"`. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-mv_count.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-mv_count.txt index 2cc68fafc5b4d..1ba65c3d81fbf 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-mv_count.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-mv_count.txt @@ -1,12 +1,29 @@ -MV_COUNT - -Syntax -Parameters -field -Multivalue expression. -DescriptionConverts a multivalued expression into a single valued column containing a count of the number of values.Supported types -Example +## MV_COUNT + +The `MV_COUNT` function in ES|QL is used to convert a multivalued expression into a single valued column containing a count of the number of values. + +### Syntax + +The syntax for using the `MV_COUNT` function is as follows: + +`MV_COUNT(field)` + +Here, `field` is a multivalue expression. + +### Examples + +Here are a couple of examples demonstrating the use of the `MV_COUNT` function: + ```esql ROW a=["foo", "zoo", "bar"] | EVAL count_a = MV_COUNT(a) ``` + +In this example, the `MV_COUNT` function is used to count the number of values in the array `["foo", "zoo", "bar"]`, and the result is stored in the `count_a` column. + +```esql +ROW b=[1, 2, 3, 4, 5] +| EVAL count_b = MV_COUNT(b) +``` + +In this second example, the `MV_COUNT` function is used to count the number of values in the array `[1, 2, 3, 4, 5]`, and the result is stored in the `count_b` column. diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-mv_dedupe.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-mv_dedupe.txt index d9bd25a64e6e1..32726e09767dd 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-mv_dedupe.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-mv_dedupe.txt @@ -1,14 +1,29 @@ -MV_DEDUPE - -Syntax -Parameters -field -Multivalue expression. -DescriptionRemove duplicate values from a multivalued field. -MV_DEDUPE may, but won’t always, sort the values in the column. -Supported types -Example +## MV_DEDUPE + +The `MV_DEDUPE` function is used to remove duplicate values from a multivalued field. It's important to note that while `MV_DEDUPE` may sort the values in the column, it's not guaranteed to always do so. + +### Syntax + +`MV_DEDUPE(field)` + +#### Parameters + +- `field`: Multivalue expression. + +### Examples + +Here are a couple of examples of how you can use the `MV_DEDUPE` function in your ES|QL queries: + ```esql ROW a=["foo", "foo", "bar", "foo"] | EVAL dedupe_a = MV_DEDUPE(a) ``` + +In this example, the `MV_DEDUPE` function is used to remove duplicate values from the multivalued field `a`. The resulting `dedupe_a` field will contain the values `["foo", "bar"]`. + +```esql +ROW b=["apple", "banana", "apple", "orange", "banana"] +| EVAL dedupe_b = MV_DEDUPE(b) +``` + +In this second example, the `MV_DEDUPE` function is used to remove duplicate values from the multivalued field `b`. The resulting `dedupe_b` field will contain the values `["apple", "banana", "orange"]`. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-mv_expand.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-mv_expand.txt index a50b54d5940fa..9a3195a115713 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-mv_expand.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-mv_expand.txt @@ -1,15 +1,41 @@ -MV_EXPAND +## MV_EXPAND +The `MV_EXPAND` command in ES|QL is a processing command that expands multivalued columns into one row per value, duplicating other columns. This command is particularly useful when dealing with data that contains multivalued fields and you want to create a separate row for each value in the multivalued field. -This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. -Syntax -MV_EXPAND column -Parameters -column +This functionality is currently in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. + +### Syntax + +`MV_EXPAND column` + +#### Parameters + +`column` The multivalued column to expand. -DescriptionThe MV_EXPAND processing command expands multivalued columns into one row per -value, duplicating other columns.Example + +### Examples + +Here are some examples of how you can use the `MV_EXPAND` command in ES|QL: + +1. Expanding a multivalued column 'a': + ```esql -ROW a=[1,2,3], b="b", j=["a","b"] +ROW a=[1,2,3], b="b" | MV_EXPAND a ``` + +2. Expanding a multivalued column 'languages': + +```esql +FROM employees +| MV_EXPAND languages +``` + +3. Expanding a multivalued column 'tags': + +```esql +FROM blog_posts +| MV_EXPAND tags +``` + +In each of these examples, the `MV_EXPAND` command creates a new row for each value in the specified multivalued column. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-mv_first.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-mv_first.txt index bcae6e967243c..fc901d41319e8 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-mv_first.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-mv_first.txt @@ -1,12 +1,31 @@ -MV_FIRST - -Syntax -Parameters -field -Multivalue expression. -DescriptionConverts a multivalued expression into a single valued column containing the first value. This is most useful when reading from a function that emits multivalued columns in a known order like SPLIT. The order that multivalued fields are read from underlying storage is not guaranteed. It is frequently ascending, but don’t rely on that. If you need the minimum value use MV_MIN instead of MV_FIRST. MV_MIN has optimizations for sorted values so there isn’t a performance benefit to MV_FIRST.Supported types -Example +## MV_FIRST + +The `MV_FIRST` function in ES|QL is used to convert a multivalued expression into a single valued column containing the first value. This function is most useful when reading from a function that emits multivalued columns in a known order like `SPLIT`. + +It's important to note that the order that multivalued fields are read from underlying storage is not guaranteed. It is frequently ascending, but this should not be relied upon. If you need the minimum value, use `MV_MIN` instead of `MV_FIRST`. `MV_MIN` has optimizations for sorted values so there isn’t a performance benefit to `MV_FIRST`. + +### Syntax: + +`MV_FIRST(field)` + +#### Parameters: + +- `field`: Multivalue expression. + +### Examples: + +Here are a couple of examples of how you can use the `MV_FIRST` function in your ES|QL queries: + ```esql ROW a="foo;bar;baz" | EVAL first_a = MV_FIRST(SPLIT(a, ";")) ``` + +In this example, the `SPLIT` function is used to split the string "foo;bar;baz" into a multivalued field. The `MV_FIRST` function is then used to select the first value from this multivalued field. + +```esql +ROW numbers=[10, 20, 30, 40, 50] +| EVAL first_num = MV_FIRST(numbers) +``` + +In this second example, the `MV_FIRST` function is used to select the first value from the multivalued field "numbers". \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-mv_last.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-mv_last.txt index f75c9c429f802..2abfbb5a65ee1 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-mv_last.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-mv_last.txt @@ -1,12 +1,23 @@ -MV_LAST - -Syntax -Parameters -field -Multivalue expression. -DescriptionConverts a multivalue expression into a single valued column containing the last value. This is most useful when reading from a function that emits multivalued columns in a known order like SPLIT. The order that multivalued fields are read from underlying storage is not guaranteed. It is frequently ascending, but don’t rely on that. If you need the maximum value use MV_MAX instead of MV_LAST. MV_MAX has optimizations for sorted values so there isn’t a performance benefit to MV_LAST.Supported types -Example +## MV_LAST + +The `MV_LAST` function in ES|QL is used to convert a multivalue expression into a single valued column containing the last value. This function is most useful when reading from a function that emits multivalued columns in a known order like `SPLIT`. + +It's important to note that the order that multivalued fields are read from underlying storage is not guaranteed. It is frequently ascending, but this should not be relied upon. If you need the maximum value, it is recommended to use `MV_MAX` instead of `MV_LAST`. `MV_MAX` has optimizations for sorted values so there isn’t a performance benefit to `MV_LAST`. + +### Examples + +Here are a couple of examples of how you can use the `MV_LAST` function in your ES|QL queries: + ```esql ROW a="foo;bar;baz" | EVAL last_a = MV_LAST(SPLIT(a, ";")) ``` + +In this example, the `SPLIT` function is used to split the string "foo;bar;baz" into a multivalue expression. The `MV_LAST` function is then used to select the last value from this multivalue expression. + +```esql +ROW numbers="1;2;3;4;5" +| EVAL last_number = MV_LAST(SPLIT(numbers, ";")) +``` + +In this second example, the `SPLIT` function is used to split the string "1;2;3;4;5" into a multivalue expression. The `MV_LAST` function is then used to select the last value from this multivalue expression. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-mv_max.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-mv_max.txt index cdcf2ee986d3d..709a1e1b747c5 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-mv_max.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-mv_max.txt @@ -1,18 +1,23 @@ -MV_MAX - -Syntax -Parameters -field -Multivalue expression. -DescriptionConverts a multivalued expression into a single valued column containing the maximum value.Supported types -Examples +## MV_MAX + +The `MV_MAX` function in ES|QL is used to convert a multivalued expression into a single valued column containing the maximum value. This function can be used with any column type, including keyword columns. In the case of keyword columns, it picks the last string, comparing their utf-8 representation byte by byte. + +### Examples + +Here are a couple of examples of how you can use the `MV_MAX` function in ES|QL: + +1. To find the maximum value in a multivalued numeric field: + ```esql ROW a=[3, 5, 1] | EVAL max_a = MV_MAX(a) ``` -It can be used by any column type, including keyword columns. In that case it picks the last string, comparing their utf-8 representation byte by byte: +2. To find the last string in a multivalued keyword field: + ```esql ROW a=["foo", "zoo", "bar"] | EVAL max_a = MV_MAX(a) ``` + +In both examples, the `MV_MAX` function is used to find the maximum value in the multivalued field `a`. The result is stored in the new field `max_a`. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-mv_median.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-mv_median.txt index fa4c9ba343753..5b66fa243c009 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-mv_median.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-mv_median.txt @@ -1,18 +1,29 @@ -MV_MEDIAN - -Syntax -Parameters -number -Multivalue expression. -DescriptionConverts a multivalued field into a single valued field containing the median value.Supported types -Examples +## MV_MEDIAN + +The `MV_MEDIAN` function in ES|QL converts a multivalued field into a single valued field containing the median value. If the row has an even number of values for a column, the result will be the average of the middle two entries. If the column is not floating point, the average rounds down. + +### Syntax + +`MV_MEDIAN(number)` + +#### Parameters + +`number`: Multivalue expression. + +### Examples + +Here are a couple of examples of how you can use the `MV_MEDIAN` function in ES|QL queries: + ```esql ROW a=[3, 5, 1] | EVAL median_a = MV_MEDIAN(a) ``` -If the row has an even number of values for a column, the result will be the average of the middle two entries. If the column is not floating point, the average rounds down: +In this example, the `MV_MEDIAN` function calculates the median of the values in the `a` array, which are `[3, 5, 1]`. The median value is `3`. + ```esql ROW a=[3, 7, 1, 6] | EVAL median_a = MV_MEDIAN(a) ``` + +In this example, the `MV_MEDIAN` function calculates the median of the values in the `a` array, which are `[3, 7, 1, 6]`. Since there is an even number of values, the function calculates the average of the middle two entries, which results in `4`. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-mv_min.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-mv_min.txt index c4c18f40fe494..aff39c9ddbba7 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-mv_min.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-mv_min.txt @@ -1,18 +1,21 @@ -MV_MIN +## MV_MIN + +The `MV_MIN` function in ES|QL is used to convert a multivalued expression into a single valued column containing the minimum value. This function can be used with any column type, including keyword columns. In the case of keyword columns, it picks the first string, comparing their utf-8 representation byte by byte. + +### Examples + +Here are a couple of examples of how to use the `MV_MIN` function in ES|QL: -Syntax -Parameters -field -Multivalue expression. -DescriptionConverts a multivalued expression into a single valued column containing the minimum value.Supported types -Examples ```esql ROW a=[2, 1] | EVAL min_a = MV_MIN(a) ``` -It can be used by any column type, including keyword columns. In that case, it picks the first string, comparing their utf-8 representation byte by byte: +In this example, the `MV_MIN` function is used to find the minimum value in the array `[2, 1]`. The result is stored in the `min_a` column. + ```esql ROW a=["foo", "bar"] | EVAL min_a = MV_MIN(a) ``` + +In this example, the `MV_MIN` function is used to find the minimum value in the array `["foo", "bar"]`. Since these are string values, the function compares their utf-8 representation byte by byte. The result is stored in the `min_a` column. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-mv_slice.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-mv_slice.txt index 9443842f6405c..12e98a93550c1 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-mv_slice.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-mv_slice.txt @@ -1,16 +1,31 @@ -MV_SLICE - -Syntax -Parameters -field -Multivalue expression. If null, the function returns null. -start -Start position. If null, the function returns null. The start argument can be negative. An index of -1 is used to specify the last value in the list. -end -End position(included). Optional; if omitted, the position at start is returned. The end argument can be negative. An index of -1 is used to specify the last value in the list. -DescriptionReturns a subset of the multivalued field using the start and end index values.Supported types -Examples +## MV_SLICE + +MV_SLICE is a function in ES|QL that returns a subset of a multivalued field using the start and end index values. + +### Syntax + +`MV_SLICE(field, start, end)` + +#### Parameters + +- `field`: Multivalue expression. If null, the function returns null. +- `start`: Start position. If null, the function returns null. The start argument can be negative. An index of -1 is used to specify the last value in the list. +- `end`: End position(included). Optional; if omitted, the position at start is returned. The end argument can be negative. An index of -1 is used to specify the last value in the list. + +### Examples + +Here are a couple of examples of how to use the MV_SLICE function in ES|QL: + +```esql row a = [1, 2, 2, 3] | eval a1 = mv_slice(a, 1), a2 = mv_slice(a, 2, 3) +``` + +In this example, the MV_SLICE function is used to get subsets of the multivalued field `a`. The subsets are stored in the new fields `a1` and `a2`. + +```esql row a = [1, 2, 2, 3] | eval a1 = mv_slice(a, -2), a2 = mv_slice(a, -3, -1) +``` + +In this example, the MV_SLICE function is used with negative start and end positions to get subsets of the multivalued field `a` from the end of the list. The subsets are stored in the new fields `a1` and `a2`. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-mv_sort.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-mv_sort.txt index a49382a25c9c9..41480eb81afa1 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-mv_sort.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-mv_sort.txt @@ -1,14 +1,30 @@ -MV_SORT - -Syntax -Parameters -field -Multivalue expression. If null, the function returns null. -order -Sort order. The valid options are ASC and DESC, the default is ASC. -DescriptionSorts a multivalued field in lexicographical order.Supported types -Example +## MV_SORT + +The `MV_SORT` function is used to sort a multivalued field in lexicographical order. + +### Syntax + +`MV_SORT(field, order)` + +#### Parameters + +- `field`: A multivalue expression. If null, the function returns null. +- `order`: Sort order. The valid options are `ASC` and `DESC`, the default is `ASC`. + +### Examples + +Here are a couple of examples of how you can use the `MV_SORT` function in ES|QL queries: + ```esql ROW a = [4, 2, -3, 2] -| EVAL sa = mv_sort(a), sd = mv_sort(a, "DESC") +| EVAL sa = MV_SORT(a) ``` + +In this example, the `MV_SORT` function is used to sort the values in the `a` field in ascending order. + +```esql +ROW a = [4, 2, -3, 2] +| EVAL sd = MV_SORT(a, "DESC") +``` + +In this example, the `MV_SORT` function is used to sort the values in the `a` field in descending order. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-mv_sum.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-mv_sum.txt index 92bbcfebd66cd..d5476aedffa4a 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-mv_sum.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-mv_sum.txt @@ -1,12 +1,29 @@ -MV_SUM - -Syntax -Parameters -number -Multivalue expression. -DescriptionConverts a multivalued field into a single valued field containing the sum of all of the values.Supported types -Example +## MV_SUM + +The `MV_SUM` function in ES|QL is used to convert a multivalued field into a single valued field containing the sum of all the values. + +### Syntax + +`MV_SUM(number)` + +#### Parameters + +- `number`: A multivalued expression. + +### Examples + +Here are a couple of examples of how you can use the `MV_SUM` function in ES|QL: + ```esql ROW a=[3, 5, 6] | EVAL sum_a = MV_SUM(a) ``` + +In this example, the `MV_SUM` function is used to calculate the sum of the values in the multivalued field `a`. + +```esql +ROW b=[10, 20, 30, 40] +| EVAL sum_b = MV_SUM(b) +``` + +In this second example, the `MV_SUM` function is used to calculate the sum of the values in the multivalued field `b`. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-mv_zip.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-mv_zip.txt index ea21096428b19..f5028c4207da9 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-mv_zip.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-mv_zip.txt @@ -1,17 +1,33 @@ -MV_ZIP - -Syntax -Parameters -string1 -Multivalue expression. -string2 -Multivalue expression. -delim -Delimiter. Optional; if omitted, , is used as a default delimiter. -DescriptionCombines the values from two multivalued fields with a delimiter that joins them together.Supported types -Example +## MV_ZIP + +The `MV_ZIP` function in ES|QL combines the values from two multivalued fields with a delimiter that joins them together. + +### Syntax + +`MV_ZIP(string1, string2, delim)` + +#### Parameters + +- `string1`: Multivalue expression. +- `string2`: Multivalue expression. +- `delim`: Delimiter. Optional; if omitted, `,` is used as a default delimiter. + +### Examples + +Here are a couple of examples of how you can use the `MV_ZIP` function in your ES|QL queries: + ```esql ROW a = ["x", "y", "z"], b = ["1", "2"] -| EVAL c = mv_zip(a, b, "-") +| EVAL c = MV_ZIP(a, b, "-") | KEEP a, b, c ``` + +In this example, the `MV_ZIP` function is used to combine the values from the `a` and `b` fields with a `-` delimiter. The result is stored in the `c` field. + +```esql +ROW a = ["apple", "banana", "cherry"], b = ["red", "yellow", "red"] +| EVAL fruit_color = MV_ZIP(a, b, " is ") +| KEEP a, b, fruit_color +``` + +In this second example, the `MV_ZIP` function is used to combine the values from the `a` and `b` fields with ` is ` as the delimiter. The result is stored in the `fruit_color` field. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-now.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-now.txt index e6b885f2907f2..632e698e7008a 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-now.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-now.txt @@ -1,14 +1,20 @@ -NOW +## NOW + +The `NOW` function in ES|QL returns the current date and time. + +### Examples + +Here are a couple of examples of how you can use the `NOW` function in ES|QL queries: + +1. To get the current date and time, you can use the `NOW` function in a `ROW` command: -Syntax -NOW() -DescriptionReturns current date and time.Example ```esql ROW current_date = NOW() ``` -To retrieve logs from the last hour: +2. To retrieve logs from the last hour, you can use the `NOW` function in a `WHERE` clause: + ```esql FROM sample_data | WHERE @timestamp > NOW() - 1 hour -``` +``` \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-operators-overview.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-operators-overview.txt deleted file mode 100644 index bfaaac6b16597..0000000000000 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-operators-overview.txt +++ /dev/null @@ -1,12 +0,0 @@ -Operators overview - - -Operators -Binary operators -Unary operators -Logical operators -IS NULL and IS NOT NULL predicates -Cast (::) -IN -LIKE -RLIKE diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-operators.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-operators.txt index a54a212800d4b..e6d88e78993b4 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-operators.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-operators.txt @@ -1,191 +1,170 @@ -CIDR_MATCH -CIDR_MATCH +# ES|QL Operators -Syntax -Parameters -ip -IP address of type ip (both IPv4 and IPv6 are supported). -blockX -CIDR block to test the IP against. -DescriptionReturns true if the provided IP is contained in one of the provided CIDR blocks.Supported types -Example -```esql -FROM hosts -| WHERE CIDR_MATCH(ip1, "127.0.0.2/32", "127.0.0.3/32") -| KEEP card, host, ip0, ip1 -``` +ES|QL supports a variety of operators that can be used in queries. These operators can be categorized into binary operators, unary operators, logical operators, and others. -ENDS_WITH -ENDS_WITH +## Binary Operators -Syntax -Parameters -str -String expression. If null, the function returns null. -suffix -String expression. If null, the function returns null. -DescriptionReturns a boolean that indicates whether a keyword string ends with another string.Supported types -Example -```esql -FROM employees -| KEEP last_name -| EVAL ln_E = ENDS_WITH(last_name, "d") -``` +Binary operators in ES|QL include equality, inequality, less than, less than or equal to, greater than, greater than or equal to, add, subtract, multiply, divide, and modulus. + +### Equality -STARTS_WITH -STARTS_WITH +The equality operator (`==`) checks if two values are equal. -Syntax -Parameters -str -String expression. If null, the function returns null. -prefix -String expression. If null, the function returns null. -DescriptionReturns a boolean that indicates whether a keyword string starts with another string.Supported types -Example ```esql FROM employees -| KEEP last_name -| EVAL ln_S = STARTS_WITH(last_name, "B") +| WHERE first_name == "John" ``` -Binary operators -Binary operators - +### Inequality -Equality -Equality +The inequality operator (`!=`) checks if two values are not equal. +```esql +FROM employees +| WHERE salary != 50000 +``` -Supported types:Supported types +### Less Than -Inequality != -Inequality != +The less than operator (`<`) checks if one value is less than another. +```esql +FROM employees +| WHERE age < 30 +``` -Supported types:Supported types +### Less Than or Equal To -Less than < -Less than < +The less than or equal to operator (`<=`) checks if one value is less than or equal to another. +```esql +FROM employees +| WHERE years_of_experience <= 5 +``` -Supported types +### Greater Than -Less than or equal to <= -Less than or equal to <= +The greater than operator (`>`) checks if one value is greater than another. +```esql +FROM employees +| WHERE salary > 50000 +``` -Supported types +### Greater Than or Equal To -Greater than > -Greater than > +The greater than or equal to operator (`>=`) checks if one value is greater than or equal to another. +```esql +FROM employees +| WHERE age >= 30 +``` -Supported types +### Add -Greater than or equal to >= -Greater than or equal to >= +The add operator (`+`) adds two values together. +```esql +FROM employees +| EVAL total_compensation = salary + bonus +``` -Supported types +### Subtract -Add + -Add + +The subtract operator (`-`) subtracts one value from another. +```esql +FROM employees +| EVAL years_until_retirement = 65 - age +``` -Supported types +### Multiply -Subtract - -Subtract - +The multiply operator (`*`) multiplies two values. +```esql +FROM employees +| EVAL yearly_bonus = monthly_bonus * 12 +``` -Supported types +### Divide -Multiply * -Multiply * +The divide operator (`/`) divides one value by another. +```esql +FROM employees +| EVAL hourly_wage = salary / 2080 +``` -Supported types +### Modulus -Divide / -Divide / +The modulus operator (`%`) returns the remainder of a division operation. +```esql +FROM employees +| EVAL odd_or_even = employee_id % 2 +``` -Supported types +## Unary Operators -Modulus % -Modulus % +ES|QL supports one unary operator, negation (`-`), which negates a value. +```esql +FROM employees +| EVAL negative_salary = -salary +``` -Supported types +## Logical Operators -Unary operators -Unary operators +ES|QL supports the logical operators `AND`, `OR`, and `NOT`. -The only unary operators is negation (-): -Supported types:Supported types +```esql +FROM employees +| WHERE salary > 50000 AND years_of_experience <= 5 +``` -Logical operators -Logical operators +## Other Operators -The following logical operators are supported: -AND -OR -NOT +### IS NULL and IS NOT NULL -IS NULL and IS NOT NULL predicates -IS NULL and IS NOT NULL predicates +The `IS NULL` and `IS NOT NULL` predicates check if a value is null or not null, respectively. -For NULL comparison, use the IS NULL and IS NOT NULL predicates: ```esql FROM employees | WHERE birth_date IS NULL -| KEEP first_name, last_name -| SORT first_name -| LIMIT 3 ``` +### Cast (::) + +The `::` operator provides a convenient alternative syntax to the `TO_` conversion functions. + ```esql -FROM employees -| WHERE is_rehired IS NOT NULL -| STATS COUNT(emp_no) +ROW ver = CONCAT(("0"::INT + 1)::STRING, ".2.3")::VERSION ``` -IN -IN +### IN + +The `IN` operator checks if a field or expression equals an element in a list of literals, fields, or expressions. -The IN operator allows testing whether a field or expression equals -an element in a list of literals, fields or expressions: ```esql ROW a = 1, b = 4, c = 3 | WHERE c-a IN (3, b / 2, a) ``` -LIKE -LIKE +### LIKE + +The `LIKE` operator filters data based on string patterns using wildcards. -Use LIKE to filter data based on string patterns using wildcards. LIKE -usually acts on a field placed on the left-hand side of the operator, but it can -also act on a constant (literal) expression. The right-hand side of the operator -represents the pattern.The following wildcard characters are supported: -* matches zero or more characters. -? matches one character. -Supported types ```esql FROM employees | WHERE first_name LIKE "?b*" -| KEEP first_name, last_name ``` -RLIKE -RLIKE +### RLIKE + +The `RLIKE` operator filters data based on string patterns using regular expressions. -Use RLIKE to filter data based on string patterns using using -regular expressions. RLIKE usually acts on a field placed on -the left-hand side of the operator, but it can also act on a constant (literal) -expression. The right-hand side of the operator represents the pattern.Supported types ```esql FROM employees | WHERE first_name RLIKE ".leja.*" -| KEEP first_name, last_name -``` +``` \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-overview.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-overview.txt index f72514ae5ea81..36036e92ea093 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-overview.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-overview.txt @@ -1,44 +1,52 @@ +# Elasticsearch Query Language (ES|QL) -ES|QLedit -The Elasticsearch Query Language (ES|QL) provides a powerful way to filter, transform, -and analyze data stored in Elasticsearch, and in the future in other runtimes. It is -designed to be easy to learn and use, by end users, SRE teams, application -developers, and administrators. -Users can author ES|QL queries to find specific events, perform statistical -analysis, and generate visualizations. It supports a wide range of commands and -functions that enable users to perform various data operations, such as -filtering, aggregation, time-series analysis, and more. -The Elasticsearch Query Language (ES|QL) makes use of "pipes" (|) to manipulate and -transform data in a step-by-step fashion. This approach allows users to compose -a series of operations, where the output of one operation becomes the input for -the next, enabling complex data transformations and analysis. -The ES|QL Compute Engineedit -ES|QL is more than a language: it represents a significant investment in new -compute capabilities within Elasticsearch. To achieve both the functional and performance -requirements for ES|QL, it was necessary to build an entirely new compute -architecture. ES|QL search, aggregation, and transformation functions are -directly executed within Elasticsearch itself. Query expressions are not -transpiled to Query DSL for execution. This approach allows ES|QL to be -extremely performant and versatile. -The new ES|QL execution engine was designed with performance in mind — it -operates on blocks at a time instead of per row, targets vectorization and cache -locality, and embraces specialization and multi-threading. It is a separate -component from the existing Elasticsearch aggregation framework with different -performance characteristics. -The ES|QL documentation is organized in these sections: -Getting started -A tutorial to help you get started with ES|QL. -ES|QL reference -Reference documentation for the ES|QL syntax, -commands, and functions and -operators. Information about working with metadata -fields and multivalued fields. And guidance for -data processing with DISSECT and -GROK and data enrichment with ENRICH. -Using ES|QL -An overview of using the REST API, Using ES|QL in Kibana, -Using ES|QL in Elastic Security, Using ES|QL across clusters, and Task management. -Limitations -The current limitations of ES|QL. -Examples -A few examples of what you can do with ES|QL. +The Elasticsearch Query Language (ES|QL) is a powerful language designed to filter, transform, and analyze data stored in Elasticsearch. It is designed to be user-friendly and can be used by end users, SRE teams, application developers, and administrators. + +Users can author ES|QL queries to find specific events, perform statistical analysis, and generate visualizations. It supports a wide range of commands and functions that enable users to perform various data operations, such as filtering, aggregation, time-series analysis, and more. + +ES|QL uses "pipes" (|) to manipulate and transform data in a step-by-step fashion. This approach allows users to compose a series of operations, where the output of one operation becomes the input for the next, enabling complex data transformations and analysis. + +## ES|QL Compute Engine + +ES|QL is more than just a language. It represents a significant investment in new compute capabilities within Elasticsearch. To achieve both the functional and performance requirements for ES|QL, a new compute architecture was built. ES|QL search, aggregation, and transformation functions are directly executed within Elasticsearch itself. Query expressions are not transpiled to Query DSL for execution. This approach allows ES|QL to be extremely performant and versatile. + +The new ES|QL execution engine was designed with performance in mind. It operates on blocks at a time instead of per row, targets vectorization and cache locality, and embraces specialization and multi-threading. It is a separate component from the existing Elasticsearch aggregation framework with different performance characteristics. + +## Limitations + +There are some known limitations to ES|QL: + +- ES|QL only supports the UTC timezone. +- Full-text search is not yet supported. +- ES|QL does not support querying time series data streams (TSDS). +- Date math expressions work well when the leftmost expression is a datetime, but using parentheses or putting the datetime to the right is not always supported yet. +- ES|QL does not support configurations where the _source field is disabled. + +## Using ES|QL + +ES|QL can be used through the REST API, in Kibana, in Elastic Security, and across clusters. + +### REST API + +You can use the REST API to execute ES|QL queries. Here's an example of how to use the REST API: + +``` +POST /_query +{ + "query": """ + FROM library + | EVAL year = DATE_TRUNC(1 YEARS, release_date) + | STATS MAX(page_count) BY year + | SORT year + | LIMIT 5 + """ +} +``` + +### Kibana + +In Kibana, ES|QL can be used to query and aggregate your data, create visualizations, and set up alerts. However, there are some limitations when using ES|QL in Kibana. For example, the user interface to filter data is not enabled when Discover is in ES|QL mode. To filter data, you need to write a query that uses the `WHERE` command instead. + +### Cross Cluster + +ES|QL also supports executing a single query across multiple clusters. This can be useful for querying data from different geographical locations or separate Elasticsearch clusters. diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-percentile.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-percentile.txt index cc2b5e01297a0..0057bd045ffac 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-percentile.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-percentile.txt @@ -1,50 +1,34 @@ -PERCENTILE - -Syntax -PERCENTILE(expression, percentile) -Parameters -expression -Expression from which to return a percentile. -percentile -A constant numeric expression. -DescriptionReturns the value at which a certain percentage of observed values occur. For -example, the 95th percentile is the value which is greater than 95% of the -observed values and the 50th percentile is the MEDIAN.Example +## PERCENTILE + +The `PERCENTILE` function in ES|QL returns the value at which a certain percentage of observed values occur. For example, the 95th percentile is the value which is greater than 95% of the observed values and the 50th percentile is the median. + +### Syntax + +`PERCENTILE(expression, percentile)` + +#### Parameters + +- `expression`: Expression from which to return a percentile. +- `percentile`: A constant numeric expression. + +### Examples + +Here are a couple of examples of how to use the `PERCENTILE` function in ES|QL: + ```esql FROM employees -| STATS p0 = PERCENTILE(salary, 0) - , p50 = PERCENTILE(salary, 50) - , p99 = PERCENTILE(salary, 99) +| STATS p0 = PERCENTILE(salary, 0), p50 = PERCENTILE(salary, 50), p99 = PERCENTILE(salary, 99) ``` -The expression can use inline functions. For example, to calculate a percentile -of the maximum values of a multivalued column, first use MV_MAX to get the -maximum value per row, and use the result with the PERCENTILE function: +In this example, the `PERCENTILE` function is used to calculate the 0th, 50th, and 99th percentiles of the `salary` field in the `employees` index. + ```esql FROM employees | STATS p80_max_salary_change = PERCENTILE(MV_MAX(salary_change), 80) ``` -PERCENTILE is (usually) approximateeditThere are many different algorithms to calculate percentiles. The naive -implementation simply stores all the values in a sorted array. To find the 50th -percentile, you simply find the value that is at my_array[count(my_array) * 0.5].Clearly, the naive implementation does not scale — the sorted array grows -linearly with the number of values in your dataset. To calculate percentiles -across potentially billions of values in an Elasticsearch cluster, approximate -percentiles are calculated.The algorithm used by the percentile metric is called TDigest (introduced by -Ted Dunning in -Computing Accurate Quantiles using T-Digests).When using this metric, there are a few guidelines to keep in mind: -Accuracy is proportional to q(1-q). This means that extreme percentiles (e.g. 99%) -are more accurate than less extreme percentiles, such as the median -For small sets of values, percentiles are highly accurate (and potentially -100% accurate if the data is small enough). -As the quantity of values in a bucket grows, the algorithm begins to approximate -the percentiles. It is effectively trading accuracy for memory savings. The -exact level of inaccuracy is difficult to generalize, since it depends on your -data distribution and volume of data being aggregated -The following chart shows the relative error on a uniform distribution depending -on the number of collected values and the requested percentile:It shows how precision is better for extreme percentiles. The reason why error diminishes -for large number of values is that the law of large numbers makes the distribution of -values more and more uniform and the t-digest tree can do a better job at summarizing -it. It would not be the case on more skewed distributions. -PERCENTILE is also non-deterministic. -This means you can get slightly different results using the same data. +In this example, the `PERCENTILE` function is used in conjunction with the `MV_MAX` function to calculate the 80th percentile of the maximum values of the `salary_change` field in the `employees` index. + +### Note + +The `PERCENTILE` function is usually approximate. There are many different algorithms to calculate percentiles and the naive implementation does not scale. To calculate percentiles across potentially billions of values in an Elasticsearch cluster, approximate percentiles are calculated using the TDigest algorithm. This means you can get slightly different results using the same data. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-pi.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-pi.txt index ce7d06fa069ae..b62f6e50831c0 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-pi.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-pi.txt @@ -1,8 +1,20 @@ -PI +## PI + +The `PI` function in ES|QL returns the mathematical constant Pi, which is the ratio of a circle's circumference to its diameter. + +### Examples + +Here are a couple of examples of how you can use the `PI` function in ES|QL queries: -Syntax -ParametersDescriptionReturns Pi, the ratio of a circle’s circumference to its diameter.Supported types -Example ```esql ROW PI() ``` + +In this example, the `PI` function is used to simply return the value of Pi. + +```esql +FROM employees +| EVAL circle_area = PI() * POW(radius, 2) +``` + +In this second example, the `PI` function is used in a calculation to determine the area of a circle, given the radius stored in the `radius` field of the `employees` index. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-pow.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-pow.txt index add982840c5ec..7107b2f715aa3 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-pow.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-pow.txt @@ -1,23 +1,21 @@ -POW +## POW + +The `POW` function in ES|QL returns the value of a base raised to the power of an exponent. It takes two numeric expressions as parameters: the base and the exponent. If either of these parameters is null, the function will return null. It's important to note that it is still possible to overflow a double result here; in that case, null will be returned. + +### Examples + +Here are a couple of examples of full ES|QL queries using the `POW` function: + +1. This query calculates the result of 2.0 raised to the power of 2: -Syntax -Parameters -base -Numeric expression for the base. If null, the function returns null. -exponent -Numeric expression for the exponent. If null, the function returns null. -DescriptionReturns the value of base raised to the power of exponent. -It is still possible to overflow a double result here; in that case, null will be returned. -Supported types -Examples ```esql ROW base = 2.0, exponent = 2 | EVAL result = POW(base, exponent) ``` -The exponent can be a fraction, which is similar to performing a root. -For example, the exponent of 0.5 will give the square root of the base: +2. This query calculates the square root of 4 by raising 4 to the power of 0.5: + ```esql ROW base = 4, exponent = 0.5 | EVAL s = POW(base, exponent) -``` +``` \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-processing-commands.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-processing-commands.txt deleted file mode 100644 index c55ef6a7f29ed..0000000000000 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-processing-commands.txt +++ /dev/null @@ -1,19 +0,0 @@ -Processing commands - -ES|QL processing commands change an input table by adding, removing, or changing -rows and columns. -ES|QL supports these processing commands: -DISSECT -DROP -ENRICH -EVAL -GROK -KEEP -LIMIT -[preview] -This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. -MV_EXPAND -RENAME -SORT -STATS ... BY -WHERE diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-rename.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-rename.txt index 496db07019b7c..5275d2f2c846c 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-rename.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-rename.txt @@ -1,23 +1,46 @@ -RENAME +## RENAME -Syntax +The `RENAME` command in ES|QL is used to rename one or more columns in a table. If a column with the new name already exists, it will be replaced by the new column. This command can be useful in scenarios where you want to make column names more descriptive or to conform to a certain naming convention. + +However, it's important to note that if a column with the new name already exists, it will be replaced by the new column. Therefore, caution should be exercised to avoid unintentionally overwriting existing columns. + +### Syntax + +``` RENAME old_name1 AS new_name1[, ..., old_nameN AS new_nameN] -Parameters -old_nameX -The name of a column you want to rename. -new_nameX -The new name of the column. -DescriptionThe RENAME processing command renames one or more columns. If a column with -the new name already exists, it will be replaced by the new column.Examples -```esql +``` + +#### Parameters + +- `old_nameX`: The name of a column you want to rename. +- `new_nameX`: The new name of the column. + +### Examples + +Here are some examples of how the `RENAME` command can be used in ES|QL queries: + +1. Renaming a single column: + + ```esql FROM employees | KEEP first_name, last_name, still_hired -| RENAME still_hired AS employed +| RENAME still_hired AS employed ``` -Multiple columns can be renamed with a single RENAME command: -```esql +2. Renaming multiple columns with a single `RENAME` command: + + ```esql FROM employees | KEEP first_name, last_name | RENAME first_name AS fn, last_name AS ln ``` + +3. Renaming a column and using the new name in a subsequent command: + + ```esql +FROM employees +| RENAME salary AS annual_income +| WHERE annual_income > 50000 +``` + +In the third example, after renaming the `salary` column to `annual_income`, we can use the new column name in subsequent commands in the query. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-repeat.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-repeat.txt new file mode 100644 index 0000000000000..8face87f51dff --- /dev/null +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-repeat.txt @@ -0,0 +1,30 @@ +## REPEAT + +The `REPEAT` function in ES|QL is used to construct a string by concatenating a given string with itself a specified number of times. + +### Syntax + +`REPEAT(string, number)` + +#### Parameters + +- `string`: The string expression that you want to repeat. +- `number`: The number of times you want to repeat the string. + +### Examples + +Here are a couple of examples of how you can use the `REPEAT` function in ES|QL: + +```esql +ROW a = "Hello!" +| EVAL triple_a = REPEAT(a, 3) +``` + +In this example, the string "Hello!" is repeated 3 times, resulting in "Hello!Hello!Hello!". + +```esql +ROW b = "ES|QL " +| EVAL five_b = REPEAT(b, 5) +``` + +In this example, the string "ES|QL " is repeated 5 times, resulting in "ES|QL ES|QL ES|QL ES|QL ES|QL ". diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-replace.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-replace.txt index fc1ef7656ed75..b2abc79c2d76b 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-replace.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-replace.txt @@ -1,17 +1,33 @@ -REPLACE - -Syntax -Parameters -string -String expression. -regex -Regular expression. -newString -Replacement string. -DescriptionThe function substitutes in the string str any match of the regular expression regex with the replacement string newStr.Supported types -ExampleThis example replaces any occurrence of the word "World" with the word "Universe": +## REPLACE + +The `REPLACE` function substitutes any match of a regular expression within a string with a replacement string. + +### Syntax + +`REPLACE(string, regex, newString)` + +#### Parameters + +- `string`: String expression. +- `regex`: Regular expression. +- `newString`: Replacement string. + +### Examples + +Here are a couple of examples of how to use the `REPLACE` function in ES|QL queries: + ```esql ROW str = "Hello World" | EVAL str = REPLACE(str, "World", "Universe") | KEEP str ``` + +In this example, the `REPLACE` function is used to replace any occurrence of the word "World" with the word "Universe" in the string "Hello World". + +```esql +ROW str = "Elasticsearch is awesome" +| EVAL str = REPLACE(str, "awesome", "fantastic") +| KEEP str +``` + +In this example, the `REPLACE` function is used to replace the word "awesome" with "fantastic" in the string "Elasticsearch is awesome". \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-right.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-right.txt index f7e7e7f0c0c60..c3e2fd9303e68 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-right.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-right.txt @@ -1,13 +1,20 @@ -RIGHT - -Syntax -Parameters -string -The string from which to returns a substring. -length -The number of characters to return. -DescriptionReturn the substring that extracts length chars from str starting from the right.Supported types -Example +## RIGHT + +The `RIGHT` function in ES|QL is used to extract a substring from a string, starting from the right. The number of characters to return is specified by the `length` parameter. + +### Syntax + +`RIGHT(string, length)` + +#### Parameters + +- `string`: The string from which to return a substring. +- `length`: The number of characters to return. + +### Examples + +Here are a couple of examples of how to use the `RIGHT` function in ES|QL: + ```esql FROM employees | KEEP last_name @@ -15,3 +22,12 @@ FROM employees | SORT last_name ASC | LIMIT 5 ``` + +In this example, the `RIGHT` function is used to extract the last three characters from the `last_name` field of each record in the `employees` index. The resulting substring is then stored in a new field called `right`. The query then sorts the results in ascending order by `last_name` and limits the output to the first 5 records. + +```esql +FROM logs-* +| EVAL file_extension = RIGHT(file_name, 3) +``` + +In this second example, the `RIGHT` function is used to extract the file extension from a `file_name` field in a `logs-*` index. The resulting substring is stored in a new field called `file_extension`. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-round.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-round.txt index 5f0e72b8cdfd2..aaef24b83a673 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-round.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-round.txt @@ -1,15 +1,31 @@ -ROUND - -Syntax -Parameters -number -The numeric value to round. If null, the function returns null. -decimals -The number of decimal places to round to. Defaults to 0. If null, the function returns null. -DescriptionRounds a number to the specified number of decimal places. Defaults to 0, which returns the nearest integer. If the precision is a negative number, rounds to the number of digits left of the decimal point.Supported types -Example +## ROUND + +The `ROUND` function in ES|QL is used to round a number to a specified number of decimal places. By default, it rounds to 0 decimal places, returning the nearest integer. If the precision is a negative number, it rounds to the number of digits left of the decimal point. + +### Syntax: + +`ROUND(number, decimals)` + +#### Parameters: + +- `number`: The numeric value to round. If null, the function returns null. +- `decimals`: The number of decimal places to round to. Defaults to 0. If null, the function returns null. + +### Examples: + +Here are a couple of examples of how to use the `ROUND` function in ES|QL queries: + ```esql FROM employees | KEEP first_name, last_name, height | EVAL height_ft = ROUND(height * 3.281, 1) ``` + +In this example, the `ROUND` function is used to round the result of the multiplication of the `height` field and `3.281` to `1` decimal place. The result is stored in the `height_ft` field. + +```esql +FROM sales_data +| EVAL rounded_sales = ROUND(sales * 1.2) +``` + +In this second example, the `ROUND` function is used to round the result of the multiplication of the `sales` field and `1.2` to the nearest integer (since no decimal places are specified). The result is stored in the `rounded_sales` field. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-row.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-row.txt index 8f60bd96b6bea..48aaa65963786 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-row.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-row.txt @@ -1,35 +1,42 @@ -ROW +## ROW -Syntax -```esql +The `ROW` command in ES|QL is used to produce a row with one or more columns with specified values. This can be particularly useful for testing purposes. + +### Syntax + +The syntax for the `ROW` command is as follows: + +``` ROW column1 = value1[, ..., columnN = valueN] ``` -Parameters -columnX -The column name. -valueX -The value for the column. Can be a literal, an expression, or a -function. -DescriptionThe -```esql -ROW source command produces a row with one or more columns with values -``` +#### Parameters + +- `columnX`: The name of the column. +- `valueX`: The value for the column. This can be a literal, an expression, or a function. + +### Examples -that you specify. This can be useful for testing.Examples -```esql +Here are some examples of how the `ROW` command can be used in ES|QL: + +1. Creating a row with specified values: + + ```esql ROW a = 1, b = "two", c = null ``` -Use square brackets to create multi-value columns: -```esql +2. Using square brackets to create multi-value columns: + + ```esql ROW a = [2, 1] ``` -```esql -ROW supports the use of functions: -``` +3. Using functions within the `ROW` command: -```esql + ```esql ROW a = ROUND(1.23, 0) ``` + +### Limitations + +There are no known limitations for the `ROW` command in ES|QL. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-rtrim.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-rtrim.txt index 0e1650ba21092..9e92e45629f70 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-rtrim.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-rtrim.txt @@ -1,15 +1,23 @@ -RTRIM - -Syntax -Parameters -string -String expression. If null, the function returns null. -DescriptionRemoves trailing whitespaces from a string.Supported types -Example +## RTRIM + +The `RTRIM` function in ES|QL is used to remove trailing whitespaces from a string. If the string expression is null, the function will return null. + +### Examples + +Here are a couple of examples of how you can use the `RTRIM` function in ES|QL queries: + ```esql -ROW message = " some text ", color = " red " +ROW message = " some text " | EVAL message = RTRIM(message) -| EVAL color = RTRIM(color) | EVAL message = CONCAT("'", message, "'") +``` + +In this example, the `RTRIM` function is used to remove trailing whitespaces from the `message` string. The `CONCAT` function is then used to concatenate the modified `message` string with single quotes. + +```esql +ROW color = " red " +| EVAL color = RTRIM(color) | EVAL color = CONCAT("'", color, "'") ``` + +In this second example, the `RTRIM` function is used to remove trailing whitespaces from the `color` string. The `CONCAT` function is then used to concatenate the modified `color` string with single quotes. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-show.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-show.txt index 4941c1364a95b..80f92061f141f 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-show.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-show.txt @@ -1,25 +1,19 @@ -SHOW +## SHOW -Syntax -```esql -SHOW item -``` +The `SHOW` command in ES|QL is used to return information about the deployment and its capabilities. Currently, the only supported item for this command is `INFO`, which returns the deployment’s version, build date, and hash. -Parameters -item -Can only be INFO. -DescriptionThe -```esql -SHOW source command returns information about the deployment and -``` +### Examples -its capabilities: -Use -```esql -SHOW INFO to return the deployment’s version, build date and hash. -``` +Here are some examples of how to use the `SHOW` command in ES|QL: + +1. To get the deployment's version, build date, and hash: -Examples ```esql SHOW INFO ``` + +Please note that the `SHOW` command can only be used with `INFO` as its parameter. Any other parameters will not be recognized by the command. + +### Limitations + +Currently, the `SHOW` command only supports `INFO` as its parameter. It does not support any other parameters or options. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-signum.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-signum.txt index 5cc3dd25c95c8..bab747ef9b185 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-signum.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-signum.txt @@ -1,12 +1,29 @@ -SIGNUM - -Syntax -Parameters -number -Numeric expression. If null, the function returns null. -DescriptionReturns the sign of the given number. It returns -1 for negative numbers, 0 for 0 and 1 for positive numbers.Supported types -Example +## SIGNUM + +The `SIGNUM` function in ES|QL returns the sign of a given number. It returns `-1` for negative numbers, `0` for `0`, and `1` for positive numbers. + +### Syntax + +The syntax for the `SIGNUM` function is as follows: + +`SIGNUM(number)` + +Here, `number` is a numeric expression. If `null`, the function returns `null`. + +### Examples + +Here are a couple of examples of how you can use the `SIGNUM` function in ES|QL: + ```esql ROW d = 100.0 | EVAL s = SIGNUM(d) ``` + +In this example, the `SIGNUM` function is used to determine the sign of the number `100.0`. Since `100.0` is a positive number, the function returns `1`. + +```esql +ROW d = -50.0 +| EVAL s = SIGNUM(d) +``` + +In this example, the `SIGNUM` function is used to determine the sign of the number `-50.0`. Since `-50.0` is a negative number, the function returns `-1`. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-sin.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-sin.txt index 97f21c4066cde..730df58969234 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-sin.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-sin.txt @@ -1,12 +1,21 @@ -SIN - -Syntax -Parameters -angle -An angle, in radians. If null, the function returns null. -DescriptionReturns ths Sine trigonometric function of an angle.Supported types -Example +## SIN + +The `SIN` function in ES|QL is used to calculate the sine of an angle. The angle should be provided in radians. If the provided angle is null, the function will return null. + +### Examples + +Here are a couple of examples of how you can use the `SIN` function in ES|QL: + ```esql ROW a=1.8 -| EVAL sin=SIN(a) +| EVAL sin = SIN(a) ``` + +In this example, the `SIN` function is used to calculate the sine of the angle `1.8` radians. The result is stored in the `sin` variable. + +```esql +ROW a=3.14 +| EVAL sin_value = SIN(a) +``` + +In this second example, the `SIN` function is used to calculate the sine of the angle `3.14` radians (approximately equal to π, the angle for a half circle in the unit circle). The result is stored in the `sin_value` variable. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-sinh.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-sinh.txt index 71f1e7224ec98..62a1d8e089b06 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-sinh.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-sinh.txt @@ -1,12 +1,21 @@ -SINH - -Syntax -Parameters -angle -An angle, in radians. If null, the function returns null. -DescriptionReturns the hyperbolic sine of an angle.Supported types -Example +## SINH + +The `SINH` function in ES|QL returns the hyperbolic sine of an angle. The angle should be provided in radians. If the provided angle is null, the function will return null. + +### Examples + +Here are a couple of examples of how you can use the `SINH` function in ES|QL: + ```esql ROW a=1.8 -| EVAL sinh=SINH(a) +| EVAL sinh = SINH(a) ``` + +In this example, the `SINH` function is used to calculate the hyperbolic sine of the angle `1.8` radians. + +```esql +ROW a=3.14 +| EVAL sinh_value = SINH(a) +``` + +In this second example, the `SINH` function is used to calculate the hyperbolic sine of the angle `3.14` radians. The result is stored in the `sinh_value` variable. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-sort.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-sort.txt index 1f9d4c2527cd8..68bc7790a033c 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-sort.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-sort.txt @@ -1,40 +1,45 @@ -SORT - -Syntax -SORT column1 [ASC/DESC][NULLS FIRST/NULLS LAST][, ..., columnN [ASC/DESC][NULLS FIRST/NULLS LAST]] -Parameters -columnX -The column to sort on. -DescriptionThe SORT processing command sorts a table on one or more columns.The default sort order is ascending. Use ASC or DESC to specify an explicit -sort order.Two rows with the same sort key are considered equal. You can provide additional -sort expressions to act as tie breakers.Sorting on multivalued columns uses the lowest value when sorting ascending and -the highest value when sorting descending.By default, null values are treated as being larger than any other value. With -an ascending sort order, null values are sorted last, and with a descending -sort order, null values are sorted first. You can change that by providing -NULLS FIRST or NULLS LAST.Examples -```esql +## SORT + +The `SORT` command in ES|QL is a processing command that sorts a table based on one or more columns. The default sort order is ascending, but you can specify an explicit sort order using `ASC` or `DESC`. + +In cases where two rows have the same sort key, they are considered equal. However, you can provide additional sort expressions to act as tie breakers. When sorting on multivalued columns, the lowest value is used when sorting in ascending order and the highest value when sorting in descending order. + +By default, null values are treated as being larger than any other value. This means that with an ascending sort order, null values are sorted last, and with a descending sort order, null values are sorted first. You can change this by providing `NULLS FIRST` or `NULLS LAST`. + +### Examples + +Here are some examples of how to use the `SORT` command in ES|QL: + +1. Sorting by height in ascending order (default): + + ```esql FROM employees | KEEP first_name, last_name, height | SORT height ``` -Explicitly sorting in ascending order with ASC: -```esql +2. Explicitly sorting in descending order with `DESC`: + + ```esql FROM employees | KEEP first_name, last_name, height | SORT height DESC ``` -Providing additional sort expressions to act as tie breakers: -```esql +3. Providing additional sort expressions to act as tie breakers: + + ```esql FROM employees | KEEP first_name, last_name, height | SORT height DESC, first_name ASC ``` -Sorting null values first using NULLS FIRST: -```esql +4. Sorting null values first using `NULLS FIRST`: + + ```esql FROM employees | KEEP first_name, last_name, height | SORT first_name ASC NULLS FIRST ``` + +Please note that the `SORT` command does not support sorting on spatial types (`geo_point`, `geo_shape`, `cartesian_point`, `cartesian_shape`). \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-source-commands.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-source-commands.txt deleted file mode 100644 index 8065c0e0bbfb0..0000000000000 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-source-commands.txt +++ /dev/null @@ -1,7 +0,0 @@ -Source commands - -An ES|QL source command produces a table, typically with data from Elasticsearch. An ES|QL query must start with a source command. -ES|QL supports these source commands: -FROM -ROW -SHOW diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-split.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-split.txt index 2b65db150c4ff..658c161292b64 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-split.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-split.txt @@ -1,14 +1,30 @@ -SPLIT - -Syntax -Parameters -string -String expression. If null, the function returns null. -delim -Delimiter. Only single byte delimiters are currently supported. -DescriptionSplit a single valued string into multiple strings.Supported types -Example +## SPLIT + +The `SPLIT` function in ES|QL is used to split a single valued string into multiple strings based on a specified delimiter. + +### Syntax + +`SPLIT(string, delim)` + +#### Parameters + +- `string`: This is the string expression that you want to split. If null, the function returns null. +- `delim`: This is the delimiter that will be used to split the string. Only single byte delimiters are currently supported. + +### Examples + +Here are a couple of examples of how you can use the `SPLIT` function in ES|QL: + ```esql ROW words="foo;bar;baz;qux;quux;corge" | EVAL word = SPLIT(words, ";") ``` + +In this example, the string "foo;bar;baz;qux;quux;corge" is split into multiple strings using the semicolon (;) as the delimiter. + +```esql +ROW data="John,Doe,30" +| EVAL details = SPLIT(data, ",") +``` + +In this second example, the string "John,Doe,30" is split into multiple strings using the comma (,) as the delimiter. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-sqrt.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-sqrt.txt index 9b2fc2ccbab80..6e1820242b468 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-sqrt.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-sqrt.txt @@ -1,12 +1,29 @@ -SQRT - -Syntax -Parameters -number -Numeric expression. If null, the function returns null. -DescriptionReturns the square root of a number. The input can be any numeric value, the return value is always a double. Square roots of negative numbers and infinites are null.Supported types -Example +## SQRT + +The `SQRT` function in ES|QL is used to calculate the square root of a number. The input can be any numeric value and the return value is always a double. If the input is a negative number or infinity, the function returns null. + +### Syntax + +`SQRT(number)` + +#### Parameters + +`number`: Numeric expression. If null, the function returns null. + +### Examples + +Here are a couple of examples of how to use the `SQRT` function in ES|QL: + ```esql ROW d = 100.0 | EVAL s = SQRT(d) ``` + +In this example, the `SQRT` function is used to calculate the square root of 100. The result is stored in the variable `s`. + +```esql +ROW d = 16.0 +| EVAL s = SQRT(d) +``` + +In this example, the `SQRT` function is used to calculate the square root of 16. The result is stored in the variable `s`. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-st_centroid_agg.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-st_centroid_agg.txt index 3cba219549177..f76bbdbf54e8f 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-st_centroid_agg.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-st_centroid_agg.txt @@ -1,11 +1,21 @@ -ST_CENTROID_AGG +## ST_CENTROID_AGG +ST_CENTROID_AGG is a function that calculates the spatial centroid over a field with spatial point geometry type. This functionality is currently in technical preview and may be changed or removed in a future release. + +### Examples + +Here are a couple of examples of full ES|QL queries using the ST_CENTROID_AGG function: -This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. -Calculate the spatial centroid over a field with spatial point geometry type. ```esql FROM airports -| STATS centroid=ST_CENTROID_AGG(location) +| STATS centroid = ST_CENTROID_AGG(location) +``` + +In this example, the ST_CENTROID_AGG function is used to calculate the spatial centroid over the 'location' field from the 'airports' index. + +```esql +FROM geo_data +| STATS geo_centroid = ST_CENTROID_AGG(geo_point) ``` -Supported types: +In this second example, the ST_CENTROID_AGG function is used to calculate the spatial centroid over the 'geo_point' field from the 'geo_data' index. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-st_contains.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-st_contains.txt index 5c271d6d40de0..da7c244d57d76 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-st_contains.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-st_contains.txt @@ -1,19 +1,34 @@ -ST_CONTAINS - - -This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. -Syntax -Parameters -geomA -Expression of type geo_point, cartesian_point, geo_shape or cartesian_shape. If null, the function returns null. -geomB -Expression of type geo_point, cartesian_point, geo_shape or cartesian_shape. If null, the function returns null. -The second parameter must also have the same coordinate system as the first. -This means it is not possible to combine geo_* and cartesian_* parameters. -DescriptionReturns whether the first geometry contains the second geometry.This is the inverse of the ST_WITHIN function.Supported types -Example +## ST_CONTAINS + +ST_CONTAINS is a function in ES|QL that checks whether the first geometry contains the second geometry. This function is the inverse of the ST_WITHIN function. + +### Syntax + +The syntax for the ST_CONTAINS function is as follows: + +`ST_CONTAINS(geomA, geomB)` + +#### Parameters + +- `geomA`: An expression of type geo_point, cartesian_point, geo_shape or cartesian_shape. If null, the function returns null. +- `geomB`: An expression of type geo_point, cartesian_point, geo_shape or cartesian_shape. If null, the function returns null. The second parameter must also have the same coordinate system as the first. This means it is not possible to combine geo_* and cartesian_* parameters. + +### Examples + +Here are a couple of examples of how to use the ST_CONTAINS function in ES|QL queries: + ```esql FROM airport_city_boundaries | WHERE ST_CONTAINS(city_boundary, TO_GEOSHAPE("POLYGON((109.35 18.3, 109.45 18.3, 109.45 18.4, 109.35 18.4, 109.35 18.3))")) | KEEP abbrev, airport, region, city, city_location ``` + +In this example, the ST_CONTAINS function is used to check if the `city_boundary` contains the specified polygon. The query then keeps the `abbrev`, `airport`, `region`, `city`, and `city_location` fields. + +```esql +FROM geo_shapes +| WHERE ST_CONTAINS(shape_field, TO_GEOSHAPE("POINT(10 20)")) +| KEEP id, name, shape_field +``` + +In this second example, the ST_CONTAINS function is used to check if the `shape_field` contains the specified point. The query then keeps the `id`, `name`, and `shape_field` fields. diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-st_disjoint.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-st_disjoint.txt index 401f94c2bf861..c1b8cc165ac7d 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-st_disjoint.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-st_disjoint.txt @@ -1,20 +1,31 @@ -ST_DISJOINT - - -This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. -Syntax -Parameters -geomA -Expression of type geo_point, cartesian_point, geo_shape or cartesian_shape. If null, the function returns null. -geomB -Expression of type geo_point, cartesian_point, geo_shape or cartesian_shape. If null, the function returns null. -The second parameter must also have the same coordinate system as the first. -This means it is not possible to combine geo_* and cartesian_* parameters. -DescriptionReturns whether the two geometries or geometry columns are disjoint.This is the inverse of the ST_INTERSECTS function. -In mathematical terms: ST_Disjoint(A, B) ⇔ A ⋂ B = ∅Supported types -Example +## ST_DISJOINT + +ST_DISJOINT is a function in ES|QL that checks whether two geometries or geometry columns are disjoint. In other words, it verifies if the two geometries do not intersect at any point. This function is the inverse of the ST_INTERSECTS function. In mathematical terms, if A and B are two geometries, they are disjoint if their intersection is an empty set (A ⋂ B = ∅). + +### Syntax + +`ST_DISJOINT(geomA, geomB)` + +#### Parameters + +- `geomA`: An expression of type geo_point, cartesian_point, geo_shape, or cartesian_shape. If null, the function returns null. +- `geomB`: An expression of type geo_point, cartesian_point, geo_shape, or cartesian_shape. If null, the function returns null. The second parameter must also have the same coordinate system as the first. This means it is not possible to combine geo_* and cartesian_* parameters. + +### Examples + +Here are a couple of examples of how to use the ST_DISJOINT function in ES|QL queries: + ```esql FROM airport_city_boundaries | WHERE ST_DISJOINT(city_boundary, TO_GEOSHAPE("POLYGON((-10 -60, 120 -60, 120 60, -10 60, -10 -60))")) | KEEP abbrev, airport, region, city, city_location ``` + +In this example, the query checks if the city_boundary is disjoint from the specified polygon. If they are disjoint, the query returns the abbrev, airport, region, city, and city_location fields. + +```esql +FROM geo_shapes +| WHERE ST_DISJOINT(shape1, shape2) +``` + +In this example, the query checks if shape1 and shape2 are disjoint. If they are, the query returns all the fields of the matching documents. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-st_intersects.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-st_intersects.txt index 1dbb4a50122d6..1682fcaccc014 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-st_intersects.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-st_intersects.txt @@ -1,22 +1,30 @@ -ST_INTERSECTS - - -This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. -Syntax -Parameters -geomA -Expression of type geo_point, cartesian_point, geo_shape or cartesian_shape. If null, the function returns null. -geomB -Expression of type geo_point, cartesian_point, geo_shape or cartesian_shape. If null, the function returns null. -The second parameter must also have the same coordinate system as the first. -This means it is not possible to combine geo_* and cartesian_* parameters. -DescriptionReturns true if two geometries intersect. -They intersect if they have any point in common, including their interior points -(points along lines or within polygons). -This is the inverse of the ST_DISJOINT function. -In mathematical terms: ST_Intersects(A, B) ⇔ A ⋂ B ≠ ∅Supported types -Example +## ST_INTERSECTS + +The `ST_INTERSECTS` function returns `true` if two geometries intersect. They intersect if they have any point in common, including their interior points (points along lines or within polygons). This is the inverse of the `ST_DISJOINT` function. In mathematical terms: `ST_Intersects(A, B) ⇔ A ⋂ B ≠ ∅`. + +### Syntax + +`ST_INTERSECTS(geomA, geomB)` + +#### Parameters + +- `geomA`: Expression of type `geo_point`, `cartesian_point`, `geo_shape` or `cartesian_shape`. If `null`, the function returns `null`. +- `geomB`: Expression of type `geo_point`, `cartesian_point`, `geo_shape` or `cartesian_shape`. If `null`, the function returns `null`. The second parameter must also have the same coordinate system as the first. This means it is not possible to combine `geo_*` and `cartesian_*` parameters. + +### Examples + +Here are a couple of examples of how to use the `ST_INTERSECTS` function in ES|QL queries: + ```esql FROM airports | WHERE ST_INTERSECTS(location, TO_GEOSHAPE("POLYGON((42 14, 43 14, 43 15, 42 15, 42 14))")) ``` + +In this example, the `ST_INTERSECTS` function is used to find airports that are located within a specific polygon. + +```esql +FROM geo_shapes +| WHERE ST_INTERSECTS(shape_field, TO_GEOSHAPE("POINT(42 14)")) +``` + +In this second example, the `ST_INTERSECTS` function is used to find geo shapes that intersect with a specific point. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-st_within.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-st_within.txt index 0224b921d274c..027f5b1eae393 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-st_within.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-st_within.txt @@ -1,19 +1,34 @@ -ST_WITHIN - - -This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. -Syntax -Parameters -geomA -Expression of type geo_point, cartesian_point, geo_shape or cartesian_shape. If null, the function returns null. -geomB -Expression of type geo_point, cartesian_point, geo_shape or cartesian_shape. If null, the function returns null. -The second parameter must also have the same coordinate system as the first. -This means it is not possible to combine geo_* and cartesian_* parameters. -DescriptionReturns whether the first geometry is within the second geometry.This is the inverse of the ST_CONTAINS function.Supported types -Example +## ST_WITHIN + +ST_WITHIN is a function in ES|QL that checks whether the first geometry is within the second geometry. This function is the inverse of the ST_CONTAINS function. + +### Syntax + +The syntax for the ST_WITHIN function is as follows: + +`ST_WITHIN(geomA, geomB)` + +#### Parameters + +- `geomA`: This is an expression of type geo_point, cartesian_point, geo_shape, or cartesian_shape. If null, the function returns null. +- `geomB`: This is an expression of type geo_point, cartesian_point, geo_shape, or cartesian_shape. If null, the function returns null. The second parameter must also have the same coordinate system as the first. This means it is not possible to combine geo_* and cartesian_* parameters. + +### Examples + +Here are a couple of examples of how to use the ST_WITHIN function in ES|QL: + ```esql FROM airport_city_boundaries | WHERE ST_WITHIN(city_boundary, TO_GEOSHAPE("POLYGON((109.1 18.15, 109.6 18.15, 109.6 18.65, 109.1 18.65, 109.1 18.15))")) | KEEP abbrev, airport, region, city, city_location ``` + +In this example, the ST_WITHIN function is used to check if the `city_boundary` is within the specified polygon. The query then keeps the `abbrev`, `airport`, `region`, `city`, and `city_location` fields from the `airport_city_boundaries` index. + +```esql +FROM my_index +| WHERE ST_WITHIN(my_geo_point, TO_GEOSHAPE("POLYGON((10 10, 20 20, 30 30, 10 10))")) +| KEEP field1, field2 +``` + +In this second example, the ST_WITHIN function is used to check if the `my_geo_point` field is within the specified polygon. The query then keeps the `field1` and `field2` fields from the `my_index` index. diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-st_x.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-st_x.txt index 286c9471b71d8..820ec0176ad9d 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-st_x.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-st_x.txt @@ -1,15 +1,21 @@ -ST_X +## ST_X +The `ST_X` function is used to extract the x coordinate from a provided point. If the point is of type `geo_point`, this is equivalent to extracting the longitude value. + +### Examples + +Here are a couple of examples of how you can use the `ST_X` function in ES|QL queries: -This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. -Syntax -Parameters -point -Expression of type geo_point or cartesian_point. If null, the function returns null. -DescriptionExtracts the x coordinate from the supplied point. -If the points is of type geo_point this is equivalent to extracting the longitude value.Supported types -Example ```esql ROW point = TO_GEOPOINT("POINT(42.97109629958868 14.7552534006536)") -| EVAL x = ST_X(point), y = ST_Y(point) +| EVAL x = ST_X(point) ``` + +In this example, the `ST_X` function is used to extract the x coordinate (or longitude) from a `geo_point` that is created using the `TO_GEOPOINT` function. + +```esql +ROW point = TO_GEOPOINT("POINT(50.8503 4.3517)") +| EVAL x = ST_X(point) +``` + +In this second example, the `ST_X` function is used to extract the x coordinate (or longitude) from a different `geo_point`. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-st_y.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-st_y.txt index dd0262318d862..4e7daf35db08d 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-st_y.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-st_y.txt @@ -1,15 +1,26 @@ -ST_Y +## ST_Y +The `ST_Y` function extracts the y coordinate from the supplied point. If the points is of type `geo_point` this is equivalent to extracting the latitude value. + +### Syntax + +`ST_Y(point)` + +### Parameters + +- `point`: Expression of type `geo_point` or `cartesian_point`. If null, the function returns null. + +### Examples + +Here are a couple of examples of how you can use the `ST_Y` function in ES|QL queries: -This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. -Syntax -Parameters -point -Expression of type geo_point or cartesian_point. If null, the function returns null. -DescriptionExtracts the y coordinate from the supplied point. -If the points is of type geo_point this is equivalent to extracting the latitude value.Supported types -Example ```esql ROW point = TO_GEOPOINT("POINT(42.97109629958868 14.7552534006536)") -| EVAL x = ST_X(point), y = ST_Y(point) +| EVAL y = ST_Y(point) ``` + +```esql +FROM geo_data +| EVAL latitude = ST_Y(location) +| WHERE latitude > 50 +``` \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-starts_with.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-starts_with.txt new file mode 100644 index 0000000000000..bee2a57300a25 --- /dev/null +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-starts_with.txt @@ -0,0 +1,33 @@ +## STARTS_WITH + +The `STARTS_WITH` function in ES|QL is used to check if a keyword string starts with another string. It returns a boolean value indicating the result of this comparison. + +### Syntax + +The syntax for using the `STARTS_WITH` function is as follows: + +`STARTS_WITH(str, prefix)` + +#### Parameters + +- `str`: This is a string expression. If null, the function returns null. +- `prefix`: This is another string expression. If null, the function returns null. + +### Examples + +Here are a couple of examples showing how to use the `STARTS_WITH` function in ES|QL queries: + +```esql +FROM employees +| KEEP last_name +| EVAL ln_S = STARTS_WITH(last_name, "B") +``` + +In this example, the `STARTS_WITH` function is used to check if the `last_name` of employees starts with the letter "B". The result is stored in the `ln_S` field. + +```esql +FROM logs-* +| WHERE STARTS_WITH(log_message, "ERROR") +``` + +In this second example, the `STARTS_WITH` function is used in a `WHERE` clause to filter out log messages that start with the word "ERROR". \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-stats.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-stats.txt index ed6dbbd283b6b..4369353daa3cb 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-stats.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-stats.txt @@ -1,64 +1,52 @@ -STATS ... BY - -Syntax -STATS [column1 =] expression1[, ..., [columnN =] expressionN] -[BY grouping_expression1[, ..., grouping_expressionN]] -Parameters -columnX -The name by which the aggregated value is returned. If omitted, the name is -equal to the corresponding expression (expressionX). -expressionX -An expression that computes an aggregated value. -grouping_expressionX -An expression that outputs the values to group by. -Individual null values are skipped when computing aggregations. -DescriptionThe STATS ... BY processing command groups rows according to a common value -and calculate one or more aggregated values over the grouped rows. If BY is -omitted, the output table contains exactly one row with the aggregations applied -over the entire dataset.The following aggregation functions are supported: -AVG -COUNT -COUNT_DISTINCT -MAX -MEDIAN -MEDIAN_ABSOLUTE_DEVIATION -MIN -PERCENTILE -[preview] -This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. -ST_CENTROID_AGG -SUM -VALUES -STATS without any groups is much much faster than adding a group. -Grouping on a single expression is currently much more optimized than grouping - on many expressions. In some tests we have seen grouping on a single keyword - column to be five times faster than grouping on two keyword columns. Do - not try to work around this by combining the two columns together with - something like CONCAT and then grouping - that is not going to be - faster. -ExamplesCalculating a statistic and grouping by the values of another column: -```esql +# STATS + +The `STATS` command in ES|QL is a processing command that groups rows according to a common value and calculates one or more aggregated values over the grouped rows. If `BY` is omitted, the output table contains exactly one row with the aggregations applied over the entire dataset. + +The following aggregation functions are supported: + +- `AVG` +- `COUNT` +- `COUNT_DISTINCT` +- `MAX` +- `MEDIAN` +- `MEDIAN_ABSOLUTE_DEVIATION` +- `MIN` +- `PERCENTILE` +- `ST_CENTROID_AGG` (This functionality is in technical preview and may be changed or removed in a future release) +- `SUM` +- `VALUES` + +It's important to note that `STATS` without any groups is much faster than adding a group. Grouping on a single expression is currently much more optimized than grouping on many expressions. + +## Examples + +Here are some examples of how you can use the `STATS` command in ES|QL: + +1. Calculating a statistic and grouping by the values of another column: + + ```esql FROM employees | STATS count = COUNT(emp_no) BY languages | SORT languages ``` -Omitting BY returns one row with the aggregations applied over the entire -dataset: -```esql +2. Omitting `BY` returns one row with the aggregations applied over the entire dataset: + + ```esql FROM employees | STATS avg_lang = AVG(languages) ``` -It’s possible to calculate multiple values: -```esql +3. It’s possible to calculate multiple values: + + ```esql FROM employees | STATS avg_lang = AVG(languages), max_lang = MAX(languages) ``` -It’s also possible to group by multiple values (only supported for long and -keyword family fields): -```esql +4. It’s also possible to group by multiple values (only supported for long and keyword family fields): + + ```esql FROM employees | EVAL hired = DATE_FORMAT("YYYY", hire_date) | STATS avg_salary = AVG(salary) BY hired, languages.long @@ -66,36 +54,39 @@ FROM employees | SORT hired, languages.long ``` -Both the aggregating functions and the grouping expressions accept other -functions. This is useful for using STATS...BY on multivalue columns. -For example, to calculate the average salary change, you can use MV_AVG to -first average the multiple values per employee, and use the result with the -AVG function: -```esql +5. Both the aggregating functions and the grouping expressions accept other functions. This is useful for using `STATS...BY` on multivalue columns. For example, to calculate the average salary change, you can use `MV_AVG` to first average the multiple values per employee, and use the result with the `AVG` function: + + ```esql FROM employees | STATS avg_salary_change = ROUND(AVG(MV_AVG(salary_change)), 10) ``` -An example of grouping by an expression is grouping employees on the first -letter of their last name: -```esql +6. An example of grouping by an expression is grouping employees on the first letter of their last name: + + ```esql FROM employees | STATS my_count = COUNT() BY LEFT(last_name, 1) | SORT `LEFT(last_name, 1)` ``` -Specifying the output column name is optional. If not specified, the new column -name is equal to the expression. The following query returns a column named -AVG(salary): -```esql -FROM employees -| STATS AVG(salary) -``` +7. Specifying the output column name is optional. If not specified, the new column name is equal to the expression. The following query returns a column named `AVG(salary)`: -Because this name contains special characters, it needs to be -quoted with backticks (`) when using it in subsequent commands: -```esql + ```esql FROM employees | STATS AVG(salary) | EVAL avg_salary_rounded = ROUND(`AVG(salary)`) ``` + +## Limitations + +- `STATS` does not support configurations where the `_source` field is disabled. +- Full-text search is not supported. +- `text` fields behave like `keyword` fields. +- Time series data streams are not supported. +- Date math expressions work well when the leftmost expression is a datetime. +- Enrich limitations: The ES|QL `ENRICH` command only supports enrich policies of type `match`. Furthermore, `ENRICH` only supports enriching on a column of type `keyword`. +- Dissect limitations: The `DISSECT` command does not support reference keys. +- Grok limitations: The `GROK` command does not support configuring custom patterns, or multiple patterns. The `GROK` command is not subject to Grok watchdog settings. +- Multivalue limitations: ES|QL supports multivalued fields, but functions return `null` when applied to a multivalued field, unless documented otherwise. +- Timezone support: ES|QL only supports the UTC timezone. +- Kibana limitations: The user interface to filter data is not enabled when Discover is in ES|QL mode. To filter data, write a query that uses the `WHERE` command instead. Discover shows no more than 10,000 rows. This limit only applies to the number of rows that are retrieved by the query and displayed in Discover. Queries and aggregations run on the full data set. Discover shows no more than 50 columns. If a query returns more than 50 columns, Discover only shows the first 50. CSV export from Discover shows no more than 10,000 rows. This limit only applies to the number of rows that are retrieved by the query and displayed in Discover. Queries and aggregations run on the full data set. Querying many indices at once without any filters can cause an error in kibana which looks like `[esql] > Unexpected error from Elasticsearch: The content length (536885793) is bigger than the maximum allowed string (536870888)`. The response from ES|QL is too long. Use `DROP` or `KEEP` to limit the number of fields returned. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-substring.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-substring.txt index d49f1ca92f2ac..53aedd96c3466 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-substring.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-substring.txt @@ -1,33 +1,41 @@ -SUBSTRING - -Syntax -Parameters -string -String expression. If null, the function returns null. -start -Start position. -length -Length of the substring from the start position. Optional; if omitted, all positions after start are returned. -DescriptionReturns a substring of a string, specified by a start position and an optional lengthSupported types -ExamplesThis example returns the first three characters of every last name: -```esql +## SUBSTRING + +The `SUBSTRING` function in ES|QL is used to extract a specific portion of a string. It is specified by a start position and an optional length. If the length is not provided, the function returns all positions after the start. + +### Syntax: + +`SUBSTRING(string, start, [length])` + +#### Parameters: + +- `string`: The string expression from which to extract the substring. If null, the function returns null. +- `start`: The starting position for the substring. +- `length`: The length of the substring from the start position. This is optional; if omitted, all positions after start are returned. + +### Examples: + +Here are a couple of examples of how to use the `SUBSTRING` function in ES|QL: + +1. Extracting the first three characters of every last name: + + ```esql FROM employees | KEEP last_name | EVAL ln_sub = SUBSTRING(last_name, 1, 3) ``` -A negative start position is interpreted as being relative to the end of the string. -This example returns the last three characters of of every last name: -```esql +2. Extracting the last three characters of every last name: + + ```esql FROM employees | KEEP last_name | EVAL ln_sub = SUBSTRING(last_name, -3, 3) ``` -If length is omitted, substring returns the remainder of the string. -This example returns all characters except for the first: -```esql +3. Extracting all characters except for the first: + + ```esql FROM employees | KEEP last_name | EVAL ln_sub = SUBSTRING(last_name, 2) -``` +``` \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-sum.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-sum.txt index c2cdff2787d54..2e555961c553f 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-sum.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-sum.txt @@ -1,19 +1,21 @@ -SUM +## SUM + +The `SUM` function in ES|QL is used to calculate the sum of a numeric expression. + +### Examples + +Here are a couple of examples of how you can use the `SUM` function in ES|QL: + +1. To calculate the sum of a field named `languages` in an index named `employees`, you can use the following query: -Syntax -SUM(expression) -expression -Numeric expression. -DescriptionReturns the sum of a numeric expression.Example ```esql FROM employees | STATS SUM(languages) ``` -The expression can use inline functions. For example, to calculate -the sum of each employee’s maximum salary changes, apply the -MV_MAX function to each row and then sum the results: +2. You can also use the `SUM` function with other functions like `MV_MAX`. In the following example, the `MV_MAX` function is applied to each row of the `salary_change` field to get the maximum salary change for each employee. The `SUM` function then calculates the total of these maximum salary changes: + ```esql FROM employees | STATS total_salary_changes = SUM(MV_MAX(salary_change)) -``` +``` \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-syntax.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-syntax.txt index 04b7ed975e8d9..e76b78c7e1cb4 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-syntax.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-syntax.txt @@ -1,108 +1,121 @@ +# ES|QL Syntax + +ES|QL (Elasticsearch Query Language) uses a simple yet powerful syntax that allows you to filter, transform, and analyze data stored in Elasticsearch. The syntax is composed of a source command followed by an optional series of processing commands, separated by a pipe character (`|`). + +## Basic Syntax + +An ES|QL query typically looks like this: + +source-command +| processing-command1 +| processing-command2 + +The result of a query is the table produced by the final processing command. For an overview of all supported commands, functions, and operators, refer to Commands and Functions and operators. + +You can also write an ES|QL query as a single line. For example: -ES|QL syntax referenceedit -Basic syntaxedit -An ES|QL query is composed of a source command followed -by an optional series of processing commands, -separated by a pipe character: `|`. For example: source-command | processing-command1 | processing-command2 -The result of a query is the table produced by the final processing command. -For an overview of all supported commands, functions, and operators, refer to Commands and Functions and operators. -For readability, this documentation puts each processing command on a new -line. However, you can write an ES|QL query as a single line. The following -query is identical to the previous one: -source-command | processing-command1 | processing-command2 -Identifiersedit -Identifiers need to be quoted with backticks (```) if: -they don’t start with a letter, `_` or `@` -any of the other characters is not a letter, number, or `_` -For example: + +## Identifiers + +Identifiers in ES|QL need to be quoted with backticks (```) if they don’t start with a letter, `_` or `@` or if any of the other characters is not a letter, number, or `_`. For example: + ```esql FROM index | KEEP `1.field` ``` -When referencing a function alias that itself uses a quoted identifier, the -backticks of the quoted identifier need to be escaped with another backtick. For -example: +When referencing a function alias that itself uses a quoted identifier, the backticks of the quoted identifier need to be escaped with another backtick. For example: + ```esql FROM index | STATS COUNT(`1.field`) | EVAL my_count = `COUNT(``1.field``)` ``` -Literalsedit +## Literals + ES|QL currently supports numeric and string literals. -String literalsedit -A string literal is a sequence of unicode characters delimited by double -quotes (`"`). -// Filter by a string value + +### String Literals + +A string literal is a sequence of unicode characters delimited by double quotes (`"`). If the literal string itself contains quotes, these need to be escaped (`\\"`). ES|QL also supports the triple-quotes (`"""`) delimiter, for convenience. Special characters CR, LF and TAB can be provided with the usual escaping: `\r`, `\n`, `\t`, respectively. + ```esql FROM index | WHERE first_name == "Georgi" ``` -If the literal string itself contains quotes, these need to be escaped (`\\"`). -ES|QL also supports the triple-quotes (`"""`) delimiter, for convenience: -```esql -ROW name = """Indiana "Indy" Jones""" -``` +### Numerical Literals + +The numeric literals are accepted in decimal and in the scientific notation with the exponent marker (`e` or `E`), starting either with a digit, decimal point `.` or the negative sign `-`. The integer numeric literals are implicitly converted to the `integer`, `long` or the `double` type, whichever can first accommodate the literal’s value. The floating point literals are implicitly converted the `double` type. -The special characters CR, LF and TAB can be provided with the usual escaping: -`\r`, `\n`, `\t`, respectively. -Numerical literalsedit -The numeric literals are accepted in decimal and in the scientific notation -with the exponent marker (`e` or `E`), starting either with a digit, decimal -point `.` or the negative sign `-`: 1969 -- integer notation 3.14 -- decimal notation .1234 -- decimal notation starting with decimal point 4E5 -- scientific notation (with exponent marker) 1.2e-3 -- scientific notation with decimal point -.1e2 -- scientific notation starting with the negative sign -The integer numeric literals are implicitly converted to the `integer`, `long` -or the `double` type, whichever can first accommodate the literal’s value. -The floating point literals are implicitly converted the `double` type. -To obtain constant values of different types, use one of the numeric -conversion functions. -Commentsedit -ES|QL uses C++ style comments: -double slash `//` for single line comments -`/*` and `*/` for block comments -// Query the employees index + +## Comments + +ES|QL uses C++ style comments: double slash `//` for single line comments and `/*` and `*/` for block comments. + ```esql +// Query the employees index FROM employees | WHERE height > 2 ``` +## Timespan Literals + +Datetime intervals and timespans can be expressed using timespan literals. Timespan literals are a combination of a number and a qualifier. These qualifiers are supported: `millisecond`/`milliseconds`/`ms`, `second`/`seconds`/`sec`/`s`, `minute`/`minutes`/`min`, `hour`/`hours`/`h`, `day`/`days`/`d`, `week`/`weeks`/`w`, `month`/`months`/`mo`, `quarter`/`quarters`/`q`, `year`/`years`/`yr`/`y`. Timespan literals are not whitespace sensitive. + +1day +1 day +1 day + +## Example Queries with Timespan Literals + +Here are some example queries using timespan literals: + +1. Querying data from the last 7 days: + ```esql -FROM /* Query the employees index */ employees -| WHERE height > 2 +FROM logs +| WHERE @timestamp >= NOW() - 7d ``` +2. Aggregating data on an hourly basis for the past 24 hours: + ```esql -FROM employees +FROM logs +| STATS COUNT(*) BY timestamp = DATE_TRUNC(1h, @timestamp) +| WHERE timestamp >= NOW() - 24h ``` -/* Query the - * employees - * index */ -| WHERE height > 2 -Timespan literalsedit -Datetime intervals and timespans can be expressed using timespan literals. -Timespan literals are a combination of a number and a qualifier. These -qualifiers are supported: -`millisecond`/`milliseconds`/`ms` -`second`/`seconds`/`sec`/`s` -`minute`/`minutes`/`min` -`hour`/`hours`/`h` -`day`/`days`/`d` -`week`/`weeks`/`w` -`month`/`months`/`mo` -`quarter`/`quarters`/`q` -`year`/`years`/`yr`/`y` -Timespan literals are not whitespace sensitive. These expressions are all valid: -`1day` -`1 day` -`1 day` +3. Finding the average response time per minute for the last hour: + +```esql +FROM logs +| STATS AVG(response_time) BY minute = DATE_TRUNC(1m, @timestamp) +| WHERE @timestamp >= NOW() - 1h +``` + +4. Aggregating data on a weekly basis for the past year: + +```esql +FROM logs +| STATS COUNT(*) BY week = DATE_TRUNC(1w, @timestamp) +| WHERE @timestamp >= NOW() - 1y +``` + +5. Finding the maximum response time per second for the last minute: + +```esql +FROM logs +| STATS MAX(response_time) BY second = DATE_TRUNC(1s, @timestamp) +| WHERE @timestamp >= NOW() - 1m +``` diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-tan.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-tan.txt index 4d939401e3035..7f1280c10f536 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-tan.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-tan.txt @@ -1,12 +1,29 @@ -TAN - -Syntax -Parameters -angle -An angle, in radians. If null, the function returns null. -DescriptionReturns the Tangent trigonometric function of an angle.Supported types -Example +## TAN + +The `TAN` function in ES|QL is used to calculate the Tangent of an angle. The angle should be provided in radians. + +### Syntax + +The syntax for using the `TAN` function is as follows: + +`TAN(angle)` + +Here, `angle` is the angle in radians for which you want to calculate the Tangent. If `angle` is null, the function will return null. + +### Examples + +Here are a couple of examples showing how to use the `TAN` function in ES|QL: + ```esql ROW a=1.8 -| EVAL tan=TAN(a) +| EVAL tan = TAN(a) +``` + +In this example, the `TAN` function is used to calculate the Tangent of the angle `1.8` radians. + +```esql +ROW a=3.14 +| EVAL tan = TAN(a) ``` + +In this example, the `TAN` function is used to calculate the Tangent of the angle `3.14` radians. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-tanh.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-tanh.txt index ffafd176e8c49..d1412a7016bd6 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-tanh.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-tanh.txt @@ -1,12 +1,29 @@ -TANH - -Syntax -Parameters -angle -An angle, in radians. If null, the function returns null. -DescriptionReturns the Tangent hyperbolic function of an angle.Supported types -Example +## TANH + +The `TANH` function in ES|QL returns the Tangent hyperbolic function of an angle. The angle should be provided in radians. If the angle is null, the function will return null. + +### Syntax + +`TANH(angle)` + +#### Parameters + +- `angle`: An angle, in radians. If null, the function returns null. + +### Examples + +Here are a couple of examples of how to use the `TANH` function in ES|QL: + ```esql ROW a=1.8 -| EVAL tanh=TANH(a) +| EVAL tanh = TANH(a) +``` + +In this example, the `TANH` function is used to calculate the Tangent hyperbolic function of the angle `1.8` radians. + +```esql +ROW a=3.14 +| EVAL tanh_result = TANH(a) ``` + +In this second example, the `TANH` function is used to calculate the Tangent hyperbolic function of the angle `3.14` radians. The result is stored in the `tanh_result` variable. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-tau.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-tau.txt index e5a9a5813d89c..c7e0a5211d48f 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-tau.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-tau.txt @@ -1,8 +1,20 @@ -TAU +## TAU + +TAU function in ES|QL returns the ratio of a circle’s circumference to its radius. + +### Examples + +Here are a couple of examples of how to use the TAU function in ES|QL: -Syntax -ParametersDescriptionReturns the ratio of a circle’s circumference to its radius.Supported types -Example ```esql ROW TAU() ``` + +In this example, the TAU function is used to return the ratio of a circle’s circumference to its radius. + +```esql +FROM my-index +| EVAL tau_ratio = TAU() +``` + +In this example, the TAU function is used within an EVAL function to create a new column `tau_ratio` in the result set, which contains the ratio of a circle’s circumference to its radius. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_base64.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_base64.txt index 86d60d94a70b9..4069711b9524f 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_base64.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_base64.txt @@ -1,10 +1,29 @@ -TO_BASE64 - -Syntax -Parameters -string -A string. -DescriptionEncode a string to a base64 string.Supported types -Example -row a = "elastic" -| eval e = to_base64(a) +## TO_BASE64 + +The `TO_BASE64` function in ES|QL is used to encode a string to a base64 string. + +### Syntax + +`TO_BASE64(string)` + +#### Parameters + +- `string`: The string you want to encode. + +### Examples + +Here are a couple of examples of how you can use the `TO_BASE64` function in ES|QL: + +```esql +ROW a = "elastic" +| EVAL e = TO_BASE64(a) +``` + +In this example, the string "elastic" is encoded to a base64 string. + +```esql +ROW b = "Elasticsearch Query Language" +| EVAL encoded = TO_BASE64(b) +``` + +In this example, the string "Elasticsearch Query Language" is encoded to a base64 string. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_boolean.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_boolean.txt index e32191d2e2d02..34868efa9ccab 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_boolean.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_boolean.txt @@ -1,12 +1,29 @@ -TO_BOOLEAN - -Syntax -Parameters -field -Input value. The input can be a single- or multi-valued column or an expression. -DescriptionConverts an input value to a boolean value. A string value of true will be case-insensitive converted to the Boolean true. For anything else, including the empty string, the function will return false. The numerical value of 0 will be converted to false, anything else will be converted to true.Supported types -Example +## TO_BOOLEAN + +The `TO_BOOLEAN` function converts an input value to a boolean value. A string value of true will be case-insensitive converted to the Boolean true. For anything else, including the empty string, the function will return false. The numerical value of 0 will be converted to false, anything else will be converted to true. + +### Syntax + +`TO_BOOLEAN(field)` + +#### Parameters + +- `field`: Input value. The input can be a single- or multi-valued column or an expression. + +### Examples + +Here are a couple of examples of full ES|QL queries using the `TO_BOOLEAN` function: + ```esql ROW str = ["true", "TRuE", "false", "", "yes", "1"] | EVAL bool = TO_BOOLEAN(str) ``` + +In this example, the `TO_BOOLEAN` function is used to convert a list of string values to boolean. The resulting `bool` column will contain boolean values corresponding to the input strings. + +```esql +ROW str = ["0", "1", "2", "-1", "0.5"] +| EVAL bool = TO_BOOLEAN(str) +``` + +In this second example, the `TO_BOOLEAN` function is used to convert a list of numeric strings to boolean. The resulting `bool` column will contain boolean values corresponding to the input strings. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_cartesianpoint.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_cartesianpoint.txt index 4141d9c43bb9e..35310b547f32d 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_cartesianpoint.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_cartesianpoint.txt @@ -1,13 +1,22 @@ -TO_CARTESIANPOINT - -Syntax -Parameters -field -Input value. The input can be a single- or multi-valued column or an expression. -DescriptionConverts an input value to a cartesian_point value. A string will only be successfully converted if it respects the WKT Point format.Supported types -Example +## TO_CARTESIANPOINT + +The `TO_CARTESIANPOINT` function converts an input value to a `cartesian_point` value. This conversion will only be successful if the input string respects the WKT Point format. + +### Examples + +Here are a couple of examples of how you can use the `TO_CARTESIANPOINT` function in ES|QL queries: + ```esql ROW wkt = ["POINT(4297.11 -1475.53)", "POINT(7580.93 2272.77)"] | MV_EXPAND wkt | EVAL pt = TO_CARTESIANPOINT(wkt) ``` + +In this example, the `TO_CARTESIANPOINT` function is used to convert the values in the `wkt` field (which are in WKT Point format) to `cartesian_point` values. The `MV_EXPAND` function is used to expand the multi-valued `wkt` field into individual rows, and then the `TO_CARTESIANPOINT` function is applied to each row. + +```esql +ROW wkt = "POINT(4297.11 -1475.53)" +| EVAL pt = TO_CARTESIANPOINT(wkt) +``` + +In this second example, the `TO_CARTESIANPOINT` function is used to convert a single WKT Point string to a `cartesian_point` value. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_cartesianshape.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_cartesianshape.txt index d7d7e3ebe94bd..8e16ba92a8e7b 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_cartesianshape.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_cartesianshape.txt @@ -1,13 +1,18 @@ -TO_CARTESIANSHAPE - -Syntax -Parameters -field -Input value. The input can be a single- or multi-valued column or an expression. -DescriptionConverts an input value to a cartesian_shape value. A string will only be successfully converted if it respects the WKT format.Supported types -Example +## TO_CARTESIANSHAPE + +The `TO_CARTESIANSHAPE` function converts an input value to a `cartesian_shape` value. A string will only be successfully converted if it respects the WKT format. + +### Examples + +Here are a couple of examples of full ES|QL queries using the `TO_CARTESIANSHAPE` function: + +```esql +ROW wkt = "POINT(4297.11 -1475.53)" +| EVAL geom = TO_CARTESIANSHAPE(wkt) +``` + ```esql ROW wkt = ["POINT(4297.11 -1475.53)", "POLYGON ((3339584.72 1118889.97, 4452779.63 4865942.27, 2226389.81 4865942.27, 1113194.90 2273030.92, 3339584.72 1118889.97))"] | MV_EXPAND wkt | EVAL geom = TO_CARTESIANSHAPE(wkt) -``` +``` \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_datetime.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_datetime.txt index 89e6d80b0186b..b23b9cb6934bd 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_datetime.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_datetime.txt @@ -1,23 +1,21 @@ -TO_DATETIME +## TO_DATETIME + +The `TO_DATETIME` function converts an input value to a date value. A string will only be successfully converted if it’s respecting the format `yyyy-MM-dd'T'HH:mm:ss.SSS'Z'`. To convert dates in other formats, use `DATE_PARSE`. + +### Examples + +Here are a couple of examples of how to use the `TO_DATETIME` function in ES|QL queries: -Syntax -Parameters -field -Input value. The input can be a single- or multi-valued column or an expression. -DescriptionConverts an input value to a date value. A string will only be successfully converted if it’s respecting the format yyyy-MM-dd'T'HH:mm:ss.SSS'Z'. To convert dates in other formats, use DATE_PARSE.Supported types -Examples ```esql ROW string = ["1953-09-02T00:00:00.000Z", "1964-06-02T00:00:00.000Z", "1964-06-02 00:00:00"] | EVAL datetime = TO_DATETIME(string) ``` -Note that in this example, the last value in the source multi-valued field has not been converted. -The reason being that if the date format is not respected, the conversion will result in a null value. -When this happens a Warning header is added to the response. -The header will provide information on the source of the failure:"Line 1:112: evaluation of [TO_DATETIME(string)] failed, treating result as null. "Only first 20 failures recorded."A following header will contain the failure reason and the offending value:"java.lang.IllegalArgumentException: failed to parse date field [1964-06-02 00:00:00] -with format [yyyy-MM-dd'T'HH:mm:ss.SSS'Z']"If the input parameter is of a numeric type, -its value will be interpreted as milliseconds since the Unix epoch. For example: +In this example, the last value in the source multi-valued field has not been converted. This is because if the date format is not respected, the conversion will result in a null value. When this happens a Warning header is added to the response. The header will provide information on the source of the failure. + ```esql ROW int = [0, 1] | EVAL dt = TO_DATETIME(int) ``` + +In this example, if the input parameter is of a numeric type, its value will be interpreted as milliseconds since the Unix epoch. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_degrees.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_degrees.txt index 31e60bc68ac1a..d82a65148947f 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_degrees.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_degrees.txt @@ -1,12 +1,29 @@ -TO_DEGREES - -Syntax -Parameters -number -Input value. The input can be a single- or multi-valued column or an expression. -DescriptionConverts a number in radians to degrees.Supported types -Example +## TO_DEGREES + +The `TO_DEGREES` function in ES|QL is used to convert a number in radians to degrees. + +### Syntax + +`TO_DEGREES(number)` + +#### Parameters + +- `number`: This is the input value. It can be a single or multi-valued column or an expression. + +### Examples + +Here are a couple of examples of how you can use the `TO_DEGREES` function in ES|QL: + ```esql ROW rad = [1.57, 3.14, 4.71] | EVAL deg = TO_DEGREES(rad) ``` + +In this example, the `TO_DEGREES` function is used to convert the values in the `rad` array from radians to degrees. + +```esql +FROM my_index +| EVAL angle_deg = TO_DEGREES(angle_rad) +``` + +In this example, the `TO_DEGREES` function is used to convert the values in the `angle_rad` field from radians to degrees and the result is stored in the `angle_deg` field. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_double.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_double.txt index 5e942690efd08..22567ab279190 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_double.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_double.txt @@ -1,17 +1,21 @@ -TO_DOUBLE +## TO_DOUBLE + +TO_DOUBLE function converts an input value to a double value. If the input parameter is of a date type, its value will be interpreted as milliseconds since the Unix epoch, converted to double. Boolean true will be converted to double 1.0, false to 0.0. + +### Examples + +Here are a couple of examples of how to use the `TO_DOUBLE` function in ES|QL: + +```esql +ROW str1 = "5.20128E11" +| EVAL dbl = TO_DOUBLE("520128000000"), dbl1 = TO_DOUBLE(str1) +``` + +In this example, the string "5.20128E11" is converted to a double value. -Syntax -Parameters -field -Input value. The input can be a single- or multi-valued column or an expression. -DescriptionConverts an input value to a double value. If the input parameter is of a date type, its value will be interpreted as milliseconds since the Unix epoch, converted to double. Boolean true will be converted to double 1.0, false to 0.0.Supported types -Example ```esql -ROW str1 = "5.20128E11", str2 = "foo" -| EVAL dbl = TO_DOUBLE("520128000000"), dbl1 = TO_DOUBLE(str1), dbl2 = TO_DOUBLE(str2) +ROW str2 = "foo" +| EVAL dbl2 = TO_DOUBLE(str2) ``` -Note that in this example, the last conversion of the string isn’t possible. -When this happens, the result is a null value. In this case a Warning header is added to the response. -The header will provide information on the source of the failure:"Line 1:115: evaluation of [TO_DOUBLE(str2)] failed, treating result as null. Only first 20 failures recorded."A following header will contain the failure reason and the offending value: -"java.lang.NumberFormatException: For input string: "foo"" \ No newline at end of file +In this example, the string "foo" cannot be converted to a double value, resulting in a null value. A warning header is added to the response indicating the source of the failure. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_geopoint.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_geopoint.txt index 9880e88c27dd2..e3db60a8fcf5d 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_geopoint.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_geopoint.txt @@ -1,12 +1,21 @@ -TO_GEOPOINT - -Syntax -Parameters -field -Input value. The input can be a single- or multi-valued column or an expression. -DescriptionConverts an input value to a geo_point value. A string will only be successfully converted if it respects the WKT Point format.Supported types -Example +## TO_GEOPOINT + +The `TO_GEOPOINT` function in ES|QL is used to convert an input value to a `geo_point` value. This function is successful in conversion only if the input string respects the WKT (Well-Known Text) Point format. + +### Examples + +Here are a couple of examples of how you can use the `TO_GEOPOINT` function in your ES|QL queries: + ```esql ROW wkt = "POINT(42.97109630194 14.7552534413725)" | EVAL pt = TO_GEOPOINT(wkt) ``` + +In this example, the `TO_GEOPOINT` function is used to convert the WKT representation of a point to a `geo_point` value. + +```esql +ROW wkt = "POINT(34.052235 -118.243683)" +| EVAL location = TO_GEOPOINT(wkt) +``` + +In this second example, the `TO_GEOPOINT` function is used to convert the WKT representation of a different point to a `geo_point` value. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_geoshape.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_geoshape.txt index e75a292fa2767..d3b6bb198040f 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_geoshape.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_geoshape.txt @@ -1,12 +1,21 @@ -TO_GEOSHAPE - -Syntax -Parameters -field -Input value. The input can be a single- or multi-valued column or an expression. -DescriptionConverts an input value to a geo_shape value. A string will only be successfully converted if it respects the WKT format.Supported types -Example +## TO_GEOSHAPE + +The `TO_GEOSHAPE` function in ES|QL is used to convert an input value to a `geo_shape` value. The conversion will be successful only if the input string respects the Well-Known Text (WKT) format. + +### Examples + +Here are a couple of examples of how you can use the `TO_GEOSHAPE` function in your ES|QL queries: + ```esql ROW wkt = "POLYGON ((30 10, 40 40, 20 40, 10 20, 30 10))" | EVAL geom = TO_GEOSHAPE(wkt) ``` + +In this example, the `TO_GEOSHAPE` function is used to convert a WKT representation of a polygon into a `geo_shape` value. + +```esql +ROW wkt = "POINT (30 10)" +| EVAL geom = TO_GEOSHAPE(wkt) +``` + +In this second example, the `TO_GEOSHAPE` function is used to convert a WKT representation of a point into a `geo_shape` value. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_integer.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_integer.txt index ff8ba3c52d410..f0881133c7d8a 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_integer.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_integer.txt @@ -1,16 +1,24 @@ -TO_INTEGER - -Syntax -Parameters -field -Input value. The input can be a single- or multi-valued column or an expression. -DescriptionConverts an input value to an integer value. If the input parameter is of a date type, its value will be interpreted as milliseconds since the Unix epoch, converted to integer. Boolean true will be converted to integer 1, false to 0.Supported types -Example +## TO_INTEGER + +The `TO_INTEGER` function converts an input value to an integer value. If the input parameter is of a date type, its value will be interpreted as milliseconds since the Unix epoch, converted to integer. Boolean `true` will be converted to integer `1`, `false` to `0`. + +### Examples + +Here are a couple of examples of full ES|QL queries using the `TO_INTEGER` function: + ```esql ROW long = [5013792, 2147483647, 501379200000] | EVAL int = TO_INTEGER(long) ``` -Note that in this example, the last value of the multi-valued field cannot be converted as an integer. -When this happens, the result is a null value. In this case a Warning header is added to the response. -The header will provide information on the source of the failure:"Line 1:61: evaluation of [TO_INTEGER(long)] failed, treating result as null. Only first 20 failures recorded."A following header will contain the failure reason and the offending value:"org.elasticsearch.xpack.ql.InvalidArgumentException: [501379200000] out of [integer] range" \ No newline at end of file +In this example, the last value of the multi-valued field cannot be converted as an integer. When this happens, the result is a null value. A Warning header is added to the response providing information on the source of the failure: + +```esql +"Line 1:61: evaluation of [TO_INTEGER(long)] failed, treating result as null. Only first 20 failures recorded." +``` + +A following header will contain the failure reason and the offending value: + +``` +"org.elasticsearch.xpack.esql.core.InvalidArgumentException: [501379200000] out of [integer] range" +``` diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_ip.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_ip.txt index 3ec377bea6598..ddd8e0eeaee39 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_ip.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_ip.txt @@ -1,17 +1,22 @@ -TO_IP +## TO_IP + +The `TO_IP` function in ES|QL is used to convert an input string to an IP value. + +### Examples + +Here are a couple of examples of how you can use the `TO_IP` function in your ES|QL queries: -Syntax -Parameters -field -Input value. The input can be a single- or multi-valued column or an expression. -DescriptionConverts an input string to an IP value.Supported types -Example ```esql -ROW str1 = "1.1.1.1", str2 = "foo" -| EVAL ip1 = TO_IP(str1), ip2 = TO_IP(str2) +ROW str1 = "1.1.1.1" +| EVAL ip1 = TO_IP(str1) | WHERE CIDR_MATCH(ip1, "1.0.0.0/8") ``` -Note that in this example, the last conversion of the string isn’t possible. -When this happens, the result is a null value. In this case a Warning header is added to the response. -The header will provide information on the source of the failure:"Line 1:68: evaluation of [TO_IP(str2)] failed, treating result as null. Only first 20 failures recorded."A following header will contain the failure reason and the offending value:"java.lang.IllegalArgumentException: 'foo' is not an IP string literal." \ No newline at end of file +In this example, the `TO_IP` function is used to convert the string "1.1.1.1" to an IP value. The `WHERE` clause then uses the `CIDR_MATCH` function to check if the IP value falls within the specified CIDR range. + +```esql +ROW str2 = "foo" +| EVAL ip2 = TO_IP(str2) +``` + +In this second example, the `TO_IP` function attempts to convert the string "foo" to an IP value. However, since "foo" is not a valid IP string literal, the function returns a null value and a warning is added to the response header. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_long.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_long.txt index dd6eebc129e02..4e23ae659f17a 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_long.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_long.txt @@ -1,16 +1,21 @@ -TO_LONG +## TO_LONG + +The `TO_LONG` function converts an input value to a long value. If the input parameter is of a date type, its value will be interpreted as milliseconds since the Unix epoch, converted to long. Boolean true will be converted to long 1, false to 0. + +### Examples + +Here are a couple of examples of how you can use the `TO_LONG` function in ES|QL queries: + +```esql +ROW str1 = "2147483648" +| EVAL long1 = TO_LONG(str1) +``` + +In this example, the string "2147483648" is converted to a long value. -Syntax -Parameters -field -Input value. The input can be a single- or multi-valued column or an expression. -DescriptionConverts an input value to a long value. If the input parameter is of a date type, its value will be interpreted as milliseconds since the Unix epoch, converted to long. Boolean true will be converted to long 1, false to 0.Supported types -Example ```esql -ROW str1 = "2147483648", str2 = "2147483648.2", str3 = "foo" -| EVAL long1 = TO_LONG(str1), long2 = TO_LONG(str2), long3 = TO_LONG(str3) +ROW str2 = "2147483648.2", str3 = "foo" +| EVAL long2 = TO_LONG(str2), long3 = TO_LONG(str3) ``` -Note that in this example, the last conversion of the string isn’t possible. -When this happens, the result is a null value. In this case a Warning header is added to the response. -The header will provide information on the source of the failure:"Line 1:113: evaluation of [TO_LONG(str3)] failed, treating result as null. Only first 20 failures recorded."A following header will contain the failure reason and the offending value:"java.lang.NumberFormatException: For input string: "foo"" \ No newline at end of file +In this example, the string "2147483648.2" is converted to a long value. However, the string "foo" cannot be converted to a long value, resulting in a null value and a warning header added to the response. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_lower.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_lower.txt index 34c99788884b3..ccfdf623a83bf 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_lower.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_lower.txt @@ -1,12 +1,29 @@ -TO_LOWER - -Syntax -Parameters -str -String expression. If null, the function returns null. -DescriptionReturns a new string representing the input string converted to lower case.Supported types -Example +## TO_LOWER + +The `TO_LOWER` function in ES|QL is used to convert an input string to lower case. + +### Syntax + +`TO_LOWER(str)` + +#### Parameters + +- `str`: String expression. If null, the function returns null. + +### Examples + +Here are a couple of examples of how you can use the `TO_LOWER` function in ES|QL queries: + +```esql +ROW message = "HELLO WORLD" +| EVAL lower_message = TO_LOWER(message) +``` + +In this example, the `TO_LOWER` function is used to convert the string "HELLO WORLD" to lower case. The result would be "hello world". + ```esql -ROW message = "Some Text" -| EVAL message_lower = TO_LOWER(message) +ROW name = "John Doe" +| EVAL lower_name = TO_LOWER(name) ``` + +In this example, the `TO_LOWER` function is used to convert the string "John Doe" to lower case. The result would be "john doe". \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_radians.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_radians.txt index 3fec9e2079191..dbf3ef1e2aa62 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_radians.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_radians.txt @@ -1,12 +1,29 @@ -TO_RADIANS - -Syntax -Parameters -number -Input value. The input can be a single- or multi-valued column or an expression. -DescriptionConverts a number in degrees to radians.Supported types -Example +## TO_RADIANS + +The `TO_RADIANS` function in ES|QL is used to convert a number in degrees to radians. + +### Syntax + +`TO_RADIANS(number)` + +#### Parameters + +- `number`: This is the input value. It can be a single or multi-valued column or an expression. + +### Examples + +Here are a couple of examples of how you can use the `TO_RADIANS` function in ES|QL: + ```esql ROW deg = [90.0, 180.0, 270.0] | EVAL rad = TO_RADIANS(deg) ``` + +In this example, the `TO_RADIANS` function is used to convert an array of degree values into radians. + +```esql +ROW deg = 45 +| EVAL rad = TO_RADIANS(deg) +``` + +In this example, the `TO_RADIANS` function is used to convert a single degree value into radians. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_string.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_string.txt index 2d3435e026df4..ed7aad31edd8b 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_string.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_string.txt @@ -1,18 +1,21 @@ -TO_STRING +## TO_STRING + +The `TO_STRING` function in ES|QL is used to convert an input value into a string. The input can be a single or multi-valued column or an expression. + +### Examples + +Here are a couple of examples of how you can use the `TO_STRING` function in your ES|QL queries: -Syntax -Parameters -field -Input value. The input can be a single- or multi-valued column or an expression. -DescriptionConverts an input value into a string.Supported types -Examples ```esql ROW a=10 | EVAL j = TO_STRING(a) ``` -It also works fine on multivalued fields: +In this example, the function is used to convert the numeric value `10` into a string. + ```esql ROW a=[10, 9, 8] | EVAL j = TO_STRING(a) ``` + +In this example, the function is used to convert the values in a multi-valued field into strings. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_unsigned_long.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_unsigned_long.txt index 8e0fa649d427e..afba5be08f5cd 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_unsigned_long.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_unsigned_long.txt @@ -1,17 +1,21 @@ -TO_UNSIGNED_LONG +## TO_UNSIGNED_LONG + +The `TO_UNSIGNED_LONG` function converts an input value to an unsigned long value. If the input parameter is of a date type, its value will be interpreted as milliseconds since the Unix epoch, converted to unsigned long. Boolean true will be converted to unsigned long 1, false to 0. + +### Examples + +Here are a couple of examples of full ES|QL queries using the `TO_UNSIGNED_LONG` function: -Syntax -Parameters -field -Input value. The input can be a single- or multi-valued column or an expression. -DescriptionConverts an input value to an unsigned long value. If the input parameter is of a date type, its value will be interpreted as milliseconds since the Unix epoch, converted to unsigned long. Boolean true will be converted to unsigned long 1, false to 0.Supported types -Example ```esql ROW str1 = "2147483648", str2 = "2147483648.2", str3 = "foo" | EVAL long1 = TO_UNSIGNED_LONG(str1), long2 = TO_ULONG(str2), long3 = TO_UL(str3) ``` -Note that in this example, the last conversion of the string isn’t possible. -When this happens, the result is a null value. In this case a Warning header is added to the response. -The header will provide information on the source of the failure:"Line 1:133: evaluation of [TO_UL(str3)] failed, treating result as null. Only first 20 failures recorded."A following header will contain the failure reason and the offending value:"java.lang.NumberFormatException: Character f is neither a decimal digit number, decimal point, -+ "nor "e" notation exponential mark." \ No newline at end of file +In this example, the `TO_UNSIGNED_LONG` function is used to convert string values to unsigned long. Note that the last conversion of the string isn’t possible. When this happens, the result is a null value. + +```esql +ROW date = "2022-01-01T00:00:00Z" +| EVAL timestamp = TO_UNSIGNED_LONG(date) +``` + +In this example, the `TO_UNSIGNED_LONG` function is used to convert a date string to an unsigned long value, representing the milliseconds since the Unix epoch. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_upper.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_upper.txt index c1ad388758dae..9f703c69c167e 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_upper.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_upper.txt @@ -1,12 +1,34 @@ -TO_UPPER - -Syntax -Parameters -str -String expression. If null, the function returns null. -DescriptionReturns a new string representing the input string converted to upper case.Supported types -Example +## TO_UPPER + +The `TO_UPPER` function in ES|QL is used to convert an input string to upper case. + +### Syntax + +`TO_UPPER(str)` + +#### Parameters + +- `str`: This is a string expression. If null, the function returns null. + +### Description + +The function returns a new string representing the input string converted to upper case. + +### Examples + +Here are a couple of examples of full ES|QL queries using the `TO_UPPER` function: + ```esql -ROW message = "Some Text" -| EVAL message_upper = TO_UPPER(message) +ROW message = "Hello World" +| EVAL upper_message = TO_UPPER(message) ``` + +In this example, the `TO_UPPER` function is used to convert the string "Hello World" to upper case. + +```esql +FROM employees +| EVAL upper_last_name = TO_UPPER(last_name) +| KEEP emp_no, upper_last_name +``` + +In this example, the `TO_UPPER` function is used to convert the `last_name` field of each record in the `employees` index to upper case. The query then keeps the `emp_no` and the upper case `last_name` for each record. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_version.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_version.txt index 07d6c6f9d510b..b560d15edc942 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_version.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-to_version.txt @@ -1,11 +1,19 @@ -TO_VERSION - -Syntax -Parameters -field -Input value. The input can be a single- or multi-valued column or an expression. -DescriptionConverts an input string to a version value.Supported types -Example +## TO_VERSION + +TO_VERSION function converts an input string to a version value. + +### Examples + +Here are a couple of examples of how you can use the TO_VERSION function in ES|QL queries: + ```esql ROW v = TO_VERSION("1.2.3") ``` + +In this example, the TO_VERSION function is used to convert the string "1.2.3" to a version value. + +```esql +ROW v = TO_VERSION("2.3.4") +``` + +In this example, the TO_VERSION function is used to convert the string "2.3.4" to a version value. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-trim.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-trim.txt index bed7bebc2dd60..faaad56be6f8b 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-trim.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-trim.txt @@ -1,13 +1,30 @@ -TRIM - -Syntax -Parameters -string -String expression. If null, the function returns null. -DescriptionRemoves leading and trailing whitespaces from a string.Supported types -Example +## TRIM + +The `TRIM` function in ES|QL is used to remove leading and trailing whitespaces from a string. If the string expression is null, the function will return null. + +### Syntax + +`TRIM(string)` + +#### Parameters + +`string`: A string expression. If null, the function returns null. + +### Examples + +Here are a couple of examples of how you can use the `TRIM` function in ES|QL: + ```esql ROW message = " some text ", color = " red " | EVAL message = TRIM(message) | EVAL color = TRIM(color) ``` + +In this example, the `TRIM` function is used to remove the leading and trailing whitespaces from the `message` and `color` strings. + +```esql +ROW name = " John Doe " +| EVAL trimmed_name = TRIM(name) +``` + +In this second example, the `TRIM` function is used to remove the leading and trailing whitespaces from the `name` string. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-values.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-values.txt index 0b3a1ec5db2a9..edc92663a03b8 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-values.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-values.txt @@ -1,22 +1,24 @@ -VALUES - - -Do not use VALUES on production environments. This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. -Syntax -VALUES(expression) -expression -Expression of any type except geo_point, cartesian_point, geo_shape, or cartesian_shape. -DescriptionReturns all values in a group as a multivalued field. The order of the returned values isn’t guaranteed. -If you need the values returned in order use MV_SORT. -This can use a significant amount of memory and ES|QL doesn’t yet - grow aggregations beyond memory. So this aggregation will work until - it is used to collect more values than can fit into memory. Once it - collects too many values it will fail the query with - a Circuit Breaker Error. -Example +## VALUES + +The `VALUES` function in ES|QL is used to return all values in a group as a multivalued field. The order of the returned values isn’t guaranteed. If you need the values returned in order, you can use `MV_SORT`. This function can use a significant amount of memory and ES|QL doesn’t yet grow aggregations beyond memory. So this aggregation will work until it is used to collect more values than can fit into memory. Once it collects too many values it will fail the query with a Circuit Breaker Error. + +### Syntax + +`VALUES(expression)` + +Where `expression` is an expression of any type except `geo_point`, `cartesian_point`, `geo_shape`, or `cartesian_shape`. + +### Examples + +Here are a couple of examples of how you can use the `VALUES` function in ES|QL queries: + ```esql FROM employees | EVAL first_letter = SUBSTRING(first_name, 0, 1) -| STATS first_name=MV_SORT(VALUES(first_name)) BY first_letter +| STATS first_name = MV_SORT(VALUES(first_name)) BY first_letter | SORT first_letter ``` + +In this example, the `VALUES` function is used to return all values of the `first_name` field in a group as a multivalued field. The `MV_SORT` function is then used to sort these values. + +Please note that this function is in technical preview and may be changed or removed in a future release. It is not recommended to use `VALUES` on production environments. \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-where.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-where.txt index ef9816b81c3fd..3c8e9ab1bd14b 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-where.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-where.txt @@ -1,83 +1,65 @@ -WHERE - -Syntax -WHERE expression -Parameters -expression -A boolean expression. -DescriptionThe WHERE processing command produces a table that contains all the rows from -the input table for which the provided condition evaluates to true.Examples -```esql +## WHERE + +The `WHERE` command in ES|QL is a processing command that produces a table containing all the rows from the input table for which the provided condition evaluates to true. This command is particularly useful in filtering data based on specific conditions. + +The `WHERE` command supports various functions and operators, including date math for retrieving data from a specific time range, `LIKE` and `RLIKE` for filtering data based on string patterns, and the `IN` operator for testing whether a field or expression equals an element in a list of literals, fields, or expressions. + +However, it's important to note that the `WHERE` command has certain limitations. For instance, it does not support configurations where the `_source` field is disabled. Also, full-text search is not yet supported because of the way ES|QL treats `text` values. + +### Syntax: + +`WHERE expression` + +#### Parameters: + +- `expression`: A boolean expression. + +### Examples: + +Here are some examples of how the `WHERE` command can be used in different scenarios: + +1. Filtering employees who are still hired: + + ```esql FROM employees | KEEP first_name, last_name, still_hired | WHERE still_hired == true ``` -Which, if still_hired is a boolean field, can be simplified to: -```esql -FROM employees -| KEEP first_name, last_name, still_hired -| WHERE still_hired -``` +2. Retrieving the last hour of logs: -Use date math to retrieve data from a specific time range. For example, to -retrieve the last hour of logs: -```esql + ```esql FROM sample_data | WHERE @timestamp > NOW() - 1 hour ``` -WHERE supports various functions. For example the -LENGTH function: -```esql +3. Filtering employees based on the length of their first name: + + ```esql FROM employees | KEEP first_name, last_name, height | WHERE LENGTH(first_name) < 4 ``` -For a complete list of all functions, refer to Functions overview.For NULL comparison, use the IS NULL and IS NOT NULL predicates: -```esql -FROM employees -| WHERE birth_date IS NULL -| KEEP first_name, last_name -| SORT first_name -| LIMIT 3 -``` - -```esql -FROM employees -| WHERE is_rehired IS NOT NULL -| STATS COUNT(emp_no) -``` +4. Filtering data based on string patterns using `LIKE`: -Use LIKE to filter data based on string patterns using wildcards. LIKE -usually acts on a field placed on the left-hand side of the operator, but it can -also act on a constant (literal) expression. The right-hand side of the operator -represents the pattern.The following wildcard characters are supported: -* matches zero or more characters. -? matches one character. -Supported types -```esql + ```esql FROM employees | WHERE first_name LIKE "?b*" | KEEP first_name, last_name ``` -Use RLIKE to filter data based on string patterns using using -regular expressions. RLIKE usually acts on a field placed on -the left-hand side of the operator, but it can also act on a constant (literal) -expression. The right-hand side of the operator represents the pattern.Supported types -```esql +5. Filtering data based on string patterns using `RLIKE`: + + ```esql FROM employees | WHERE first_name RLIKE ".leja.*" | KEEP first_name, last_name ``` -The IN operator allows testing whether a field or expression equals -an element in a list of literals, fields or expressions: -```esql +6. Using the `IN` operator to test whether a field or expression equals an element in a list: + + ```esql ROW a = 1, b = 4, c = 3 | WHERE c-a IN (3, b / 2, a) -``` - -For a complete list of all operators, refer to Operators. \ No newline at end of file +``` \ No newline at end of file diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/index.ts b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/index.ts index a049279f7c4e4..fe76d4710d245 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/index.ts +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/index.ts @@ -26,6 +26,7 @@ import { ESQLSearchReponse } from '@kbn/es-types'; import type { FunctionRegistrationParameters } from '..'; import { correctCommonEsqlMistakes } from './correct_common_esql_mistakes'; import { validateEsqlQuery } from './validate_esql_query'; +import { INLINE_ESQL_QUERY_REGEX } from './constants'; const readFile = promisify(Fs.readFile); const readdir = promisify(Fs.readdir); @@ -228,14 +229,6 @@ export function registerQueryFunction({ functions, resources }: FunctionRegistra parameters: { type: 'object', properties: { - guides: { - type: 'array', - items: { - type: 'string', - enum: ['API', 'KIBANA', 'CROSS_CLUSTER'], - }, - description: 'A list of guides', - }, commands: { type: 'array', items: { @@ -271,7 +264,6 @@ export function registerQueryFunction({ functions, resources }: FunctionRegistra } const args = JSON.parse(response.message.function_call.arguments) as { - guides?: string[]; commands?: string[]; functions?: string[]; intention: VisualizeESQLUserIntention; @@ -280,9 +272,9 @@ export function registerQueryFunction({ functions, resources }: FunctionRegistra const keywords = [ ...(args.commands ?? []), ...(args.functions ?? []), - ...(args.guides ?? []), 'SYNTAX', 'OVERVIEW', + 'OPERATORS', ].map((keyword) => keyword.toUpperCase()); const messagesToInclude = mapValues(pick(esqlDocs, keywords), ({ data }) => data); @@ -385,12 +377,26 @@ export function registerQueryFunction({ functions, resources }: FunctionRegistra return esqlResponse$.pipe( emitWithConcatenatedMessage(async (msg) => { + msg.message.content = msg.message.content.replaceAll( + INLINE_ESQL_QUERY_REGEX, + (_match, query) => { + const correction = correctCommonEsqlMistakes(query); + if (correction.isCorrection) { + resources.logger.debug( + `Corrected query, from: \n${correction.input}\nto:\n${correction.output}` + ); + } + return '```esql\n' + correction.output + '\n```'; + } + ); + if (msg.message.function_call.name) { return msg; } - const esqlQuery = correctCommonEsqlMistakes(msg.message.content, resources.logger) - .match(/```esql([\s\S]*?)```/)?.[1] - ?.trim(); + + const esqlQuery = msg.message.content.match( + new RegExp(INLINE_ESQL_QUERY_REGEX, 'ms') + )?.[1]; let functionCall: ConcatenatedMessage['message']['function_call'] | undefined; @@ -418,7 +424,6 @@ export function registerQueryFunction({ functions, resources }: FunctionRegistra ...msg, message: { ...msg.message, - content: correctCommonEsqlMistakes(msg.message.content, resources.logger), ...(functionCall ? { function_call: functionCall, diff --git a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/system_message.txt b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/system_message.txt index 0b85e491cdcca..8fc2243480218 100644 --- a/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/system_message.txt +++ b/x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/system_message.txt @@ -1,3 +1,5 @@ +# System instructions + You are a helpful assistant for generating and executing ES|QL queries. Your goal is to help the user construct and possibly execute an ES|QL query for the Observability use cases, which often involve metrics, logs