* [DOCS] Update ESQL metadata fields page
**esql-metadata-fields.md:**
- restructured from bullet list to table format for metadata fields
- added `_index_mode` and `_source` fields to available metadata
- improved field descriptions (more detailed)
- added "usage and limitations" section
- reorganized examples into subsections with headers
- added `_score` sorting example
- added tip box linking to search documentation
* 🚙Drive by updates to search functions ref page
moved tutorial link into tip box at top
added cross-reference to search overview documentation
minor text flow improvements and punctuation fixes
* Fix id typo
* Apply suggestions from review
Co-authored-by: Bogdan Pintea <sig11@mailbox.org>
* Declare LU JOIN GA in 9.1
* Align applies_to tags for sample, change_point
Co-authored-by: Liam Thompson <32779855+leemthompo@users.noreply.github.com>
This adds `counter_long` and `counter_double` to the signatures of
supported fields for `IS NULL` and `IS NOT NULL`. We hadn't been
generating those signatures since the docs v3 migration, so this had to
plug those in. In addition, it changes the wording on a few things and
adds a note that if a field is only in some documents then the ones
missing the field will have `NULL` - which is important information for
`IS NULL` and `IS NOT NULL`.
* [DOCS][ESQL] Flip preview booleans, to GA search functions
* render docs, tweak some applies_to metadata in docs gen code
- **rendered docs (md):**
- kql: removed serverless preview, added ga 9.1.0
- match: removed serverless preview, added ga 9.1.0
- match_phrase: changed from preview 9.1.0 to unavailable 9.0 + ga 9.1.0
- qstr: removed serverless preview, added ga 9.1.0
- search functions list: removed bullet point before term function
- **docs generation code (java):**
- match_phrase: updated function info annotations to unavailable 9.0 + ga 9.1.0
- query_string: uncommented ga 9.1.0 annotation
- Add PREVIEW annotations to all preview functions
- Update docs generation logic to use annotations instead of preview boolean
* Changed stack: ga 9.1 to stack: coming in multiple places
- Match.java: Updated the options parameter description
- MultiMatch.java: Updated the options parameter description
- ToLower.java: Reformatted parameter description and updated version annotation
- ToUpper.java: Removed the appliesTo annotation entirely and reformatted parameter description
- updated applies_to annotations to specify both preview 9.0.0 and ga 9.1.0 lifecycle stages
- added version-specific documentation examples with applies_to markers for ga 9.1.0 features
- enhanced to_lower and to_upper functions to indicate support for multi-valued expressions in ga 9.1.0
- added version guards around function parameters and descriptions using applies_to syntax
- updated function parameter descriptions to indicate ga 9.1.0 availability for named parameters
- use detailedDescription + and fix match_phrase applies_to syntax
- strip inline applies_to from kibana docs
- update roundto, matchphrase lifecycles
- fix match named params info
- various spatial functions are preview
- unsigned long is preview
- update qstr
- Update TO_LOWER/TO_UPPER parameter descriptions for clarity
- hide spatial functions per https://github.com/elastic/elasticsearch/pull/129839
- added `stack: ga 9.1.0` blocks to match_phrase.md and qstr.md examples
- simplified term.md version from `preview 9.0.0` to just `preview`
- added `applies_to = "stack: ga 9.1.0"` to matchphrase and querystring java annotations
- removed version `9.0.0` from term function annotation
- deleted unused `makeCallout()` and `appendLifeCycleAndVersion()` methods
Co-authored-by: elasticsearchmachine <infra-root+elasticsearchmachine@elastic.co>
Co-authored-by: Liam Thompson <leemthompo@gmail.com>
Co-authored-by: Liam Thompson <32779855+leemthompo@users.noreply.github.com>
Co-authored-by: Nik Everett <nik9000@gmail.com>
#125143 added 9 spatial grid functions and released them into Serverless. We think this is not the best long-term approach and the functions in #129581 are likely better.
As a first step, rmove the spatial grid functions added in #125143 from release builds so they don't get released into 8.19/9.1.
---------
Co-authored-by: Craig Taverner <craig@amanzi.com>
Adds support for LIKE function alternative syntax with a list of patterns.
Examples:
FROM foo
| WHERE bar LIKE ("A*","B*", "C?")
The new syntax is documented as part of the existing LIKE function documentation. We will use the existing WildcardLike java implementation for existing cases using the old syntax and one list argument case to improve mixed cluster compatibility.
This extends RENAME's grammar to allow a new syntax: `| RENAME new_name
= old_name` This is supported along the existing `... old_name AS
new_name` syntax.
Closes#129208
* Take match_phrase out of snapshot and make tech preview
* Update docs/changelog/128925.yaml
* PR feedback
* Adding regenerated test data
* Update docs/changelog/128925.yaml
Co-authored-by: Carlos Delgado <6339205+carlosdelest@users.noreply.github.com>
* [CI] Auto commit changes from spotless
* Checkstyle
* Correct docs
* Hopefully fix docs build
* Found one more bad docs link - here's hoping this now fixes the doc build
* OMG bitten by - vs _
---------
Co-authored-by: Carlos Delgado <6339205+carlosdelest@users.noreply.github.com>
Co-authored-by: elasticsearchmachine <infra-root+elasticsearchmachine@elastic.co>
Co-authored-by: Aurélien FOUCRET <aurelien.foucret@gmail.com>
* Initial commit of match_phrase
* Add MatchPhraseQueryTests
* First pass at CSV specs
* Update docs/changelog/127661.yaml
* Refactor so MatchPhrase doesn't use all fulltext test cases, just text only
* Fix tests
* Add some CSV test cases
* Fix test
* Update changelog
* Update tests
* Comment out MATCH_PHRASE in search-functions Markdown
* Minor PR feedback
* PR feedback - refactor/consolidate code
* Add some more tests
* Fix some tests
* [CI] Auto commit changes from spotless
* Fix tests
* PR feedback - add tests, support boost and numeric data
* Revert "PR feedback - add tests, support boost and numeric data"
This reverts commit 4e7a699e3e.
* Apply testing/PR feedback outside numeric support only
* Regenerate docs
* Add negative test
* Update x-pack/plugin/esql/qa/testFixtures/src/main/resources/match-phrase-function.csv-spec
Co-authored-by: Carlos Delgado <6339205+carlosdelest@users.noreply.github.com>
* Update x-pack/plugin/esql/qa/testFixtures/src/main/resources/match-phrase-function.csv-spec
Co-authored-by: Carlos Delgado <6339205+carlosdelest@users.noreply.github.com>
* Update x-pack/plugin/esql/qa/testFixtures/src/main/resources/match-phrase-function.csv-spec
Co-authored-by: Carlos Delgado <6339205+carlosdelest@users.noreply.github.com>
* PR feedback
* Fix auto-commit error
* Regenerate docs
* Update x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/fulltext/MatchPhrase.java
Co-authored-by: Liam Thompson <32779855+leemthompo@users.noreply.github.com>
* Remove non text field types
* Fake test data
* Remove tests that no longer should pass without ip/date/version support
* Put real data in score tests now that I was able to engineer a failure
* Realized the scoring test might be flakey because how it was written, updated
* PR feedback
* PR feedback
* [CI] Auto commit changes from spotless
* Add check to MatchPhrase tests
* Fix merge errors
* [CI] Auto commit changes from spotless
* Test generated docs
* Add additional verifier tests
---------
Co-authored-by: elasticsearchmachine <infra-root+elasticsearchmachine@elastic.co>
Co-authored-by: Carlos Delgado <6339205+carlosdelest@users.noreply.github.com>
Co-authored-by: Liam Thompson <32779855+leemthompo@users.noreply.github.com>
Added support for the three primary scalar grid functions:
* `ST_GEOHASH(geom, precision)`
* `ST_GEOTILE(geom, precision)`
* `ST_GEOHEX(geom, precision)`
As well as versions of these three that take an optional `geo_shape` boundary (must be a `BBOX` ie. `Rectangle`).
And also supporting conversion functions that convert the grid-id from long to string and back to long.
This work represents the core of the feature to support geo-grid aggregations in ES|QL.
Begins adding support for running "tagged queries" to the compute
engine. Here, it's just the `LuceneSourceOperator` because that's
useful and contained.
Example time! Say you are running:
```
FROM foo
| STATS MAX(v) BY ROUND_TO(g, 0, 100, 1000, 100000)
```
It's *often* faster to run this as four queries:
* The docs that round to `0`
* The docs that round to `100`
* The docs that round to `1000`
* The docs that round to `100000`
This creates an ESQL operator that can run these queries, one after the
other and attach those tags.
Aggs uses this trick and it's *way* faster when it can push down count
queries, but it's still faster when it pushes doc loading things. This
implementation in `LuceneSourceOperator` is quite similar to the doc
loading version in _search.
I don't have performance measurements yet because I haven't plugged this
into the language. In _search we call this `filter-by-filter` and enable
it when each group averages to more than 5000 documents and when there
isn't an `_doc_count` field. It's faster in those cases not to push. I
expect we'll be pretty similar.
Creates a `ROUND_TO` function that rounds it's input to one of the
provided values. Like so:
```
ROUND_TO(v, 0, 5000, 10000, 20000, 40000, 100000)
v | ROUND_TO
0 | 0
100 | 0
6000 | 5000
45001 | 40000
999999 | 100000
```
For some sequences of numbers you could do this with the `/` operator -
but for arbitrary sequences of numbers you needed `CASE` which is quite
slow. And hard to read!
Rewriting the example above would look like:
```
CASE (
v < 5000, 0,
v < 10000, 5000,
v < 20000, 10000,
v < 40000, 20000,
v < 100000, 40000,
100000
)
```
Even better, this is *fast*:
```
(operation) Mode Cnt Score Error Units
round_to_4_via_case avgt 7 138.124 ± 0.738 ns/op
round_to_4 avgt 7 0.805 ± 0.011 ns/op
round_to_3 avgt 7 0.739 ± 0.011 ns/op
round_to_2 avgt 7 0.651 ± 0.009 ns/op
date_trunc avgt 7 2.425 ± 0.018 ns/op
```
I've included a comparison to `DATE_TRUNC` above because we should be
able to rewrite `DATE_TRUNC` into `ROUND_TO` when we know the date range
of the index. This doesn't do it now, but it should be possible.
Documents that the VALUES aggregate function returns unique documents
and points folks to the TOP aggregate function if they want to keep
dupes.
Closes#128091
---------
Co-authored-by: Liam Thompson <32779855+leemthompo@users.noreply.github.com>
Initial Kibana definition files for commands, currently only providing License information. We leave the license field out if it works with BASIC, so the only two files that actually have a license line are:
* CHANGE_POINT: PLATINUM
* RRF: ENTERPRISE
Output function signature license requirements to Kibana definition files, and also test that this matches the actual licensing behaviour of the functions.
ES|QL functions that enforce license checks do so with the `LicenseAware` interface. This does not expose what that functions license level is, but only whether the current active license will be sufficient for that function and its current signature (data types passed in as fields). Rather than add to this interface, we've made the license level information test-only information. This means if a function implements LicenseAware, it also needs to add a method to its test class to specify the license level for the signature being called. All functions will be tested for compliance, so failing to add this will result in test failure. Also if the test license level does not match the enforced license, that will also cause a failure.
* [DOCS][9.0] Improve ESQL reference docs IA
- reorganized es|ql reference documentation from flat list to logical hierarchy
- created three main sections: syntax reference , special fields, advanced operations
- renamed pages with more consistent and task-oriented titles
- aligned navigation titles with page content
- improved introductory text for each section
- used parallel phrasing for similar concepts
- clarified the relationship between reference docs and conceptual docs
Co-authored-by: Alexander Spies <alexander.spies@elastic.co>
- I trimmed the KEEP query in my final iteration in https://github.com/elastic/elasticsearch/pull/127215 but neglected to update the query itself, only the response. This fixes that so the query matches the response.
- 🚘 I also updated the table response to match other ESQL response tables
* [DOCS][ESQL] Cleanup and cross-reference LOOKUP JOIN reference and landing pages
**lookup-join.md (syntax reference)**:
- removed tip formatting for simpler direct link to landing page
- improved parameter formatting and descriptions
- fixed template variable from `{esql}` to `{{esql}}`
**esql-lookup-join.md (landing page)**:
- added "compare with enrich" section header
- simplified "how the command works" with clearer parameter explanation
- added code example in how it works section
- improved image alt text for accessibility
- organized example section with better context and SQL comparison
- added dropdown for sample tables to reduce visual clutter
- added "query" subheading for clearer organization
- included reference to additional examples in command reference
- removed excessive whitespace
* Improve example, add setup code
replaced abstract employee/language example with security monitoring use case
added setup instructions for creating test indices
included sample data loading via bulk api
new practical query example joining firewall logs with threat data
simplified results output showing threat detection scenario
added note about left-join behavior
improved code comments and structure
added required index.mode: lookup setting info
