Attempts to make KQL syntax errors more sensical to the average user. I initially tried to use a similar solution to the one we used for detecting usage of old lucene syntax. In other words, I tried to create rules in the grammar that would match strings containing common mistakes the user might make and throw custom error messages for each situation. This proved to be more difficult for detecting errors in the regular language. While the Lucene rules could be completely separated from the main grammar, the KQL error rules had to be mixed into the main grammar which made it much more complex and had a lot of unintended side effects. So instead I decided to lean more heavily on PEG's built in error reporting. Giving certain rules human readable names allows the parser to use those names in the error reporting instead of auto generating a long list of possible characters that might be expected based on the matching rules. Since the PEG errors contain location information I was also able to add ascii art that points the user to exactly where the error occurred in their query string. While this approach is not quite as nice as bespoke error messages that tell the user exactly what is wrong in plain English, it's much more maintainable and I think it still results in much better error messages compared to what we have today. I've also removed the old original kuery grammar (for queries like is(response, 200)). We were only using it to display an error if I user was still using the old syntax. This version of kuery hasn't existed since 6.3 and we've had error messages telling users this since then. I think it's safe to remove the legacy parser at this point, which greatly reduces the complexity of our error reporting. |
||
---|---|---|
.. | ||
scripts | ||
src | ||
tasks | ||
babel.config.js | ||
index.d.ts | ||
package.json | ||
README.md | ||
tsconfig.browser.json | ||
tsconfig.json |
kbn-es-query
This module is responsible for generating Elasticsearch queries for Kibana. See explanations below for each of the subdirectories.
es_query
This folder contains the code that combines Lucene/KQL queries and filters into an Elasticsearch query.
buildEsQuery(indexPattern, queries, filters, config)
Generates the Elasticsearch query DSL from combining the queries and filters provided.
buildQueryFromFilters(filters, indexPattern)
Generates the Elasticsearch query DSL from the given filters.
luceneStringToDsl(query)
Generates the Elasticsearch query DSL from the given Lucene query.
migrateFilter(filter, indexPattern)
Migrates a filter from a previous version of Elasticsearch to the current version.
decorateQuery(query, queryStringOptions)
Decorates an Elasticsearch query_string query with the given options.
filters
This folder contains the code related to Kibana Filter objects, including their definitions, and helper functions to create them. Filters in Kibana always contain a meta
property which describes which index
the filter corresponds to, as well as additional data about the specific filter.
The object that is created by each of the following functions corresponds to a Filter object in the lib
directory (e.g. PhraseFilter
, RangeFilter
, etc.)
buildExistsFilter(field, indexPattern)
Creates a filter (ExistsFilter
) where the given field exists.
buildPhraseFilter(field, value, indexPattern)
Creates an filter (PhraseFilter
) where the given field matches the given value.
buildPhrasesFilter(field, params, indexPattern)
Creates a filter (PhrasesFilter
) where the given field matches one or more of the given values. params
should be an array of values.
buildQueryFilter(query, index)
Creates a filter (CustomFilter
) corresponding to a raw Elasticsearch query DSL object.
buildRangeFilter(field, params, indexPattern)
Creates a filter (RangeFilter
) where the value for the given field is in the given range. params
should contain lt
, lte
, gt
, and/or gte
.
kuery
This folder contains the code corresponding to generating Elasticsearch queries using the Kibana query language.
In general, you will only need to worry about the following functions from the ast
folder:
fromExpression(expression)
Generates an abstract syntax tree corresponding to the raw Kibana query expression
.
toElasticsearchQuery(node, indexPattern)
Takes an abstract syntax tree (generated from the previous method) and generates the Elasticsearch query DSL using the given indexPattern
. Note that if no indexPattern
is provided, then an Elasticsearch query DSL will still be generated, ignoring things like the index pattern scripted fields, field types, etc.