root
/
elasticsearch
mirror of https://github.com/elastic/elasticsearch.git
1
0
Fork 0
Code Issues Actions 1 Packages Projects Releases Wiki Activity
elasticsearch/docs/reference/esql/functions/spatial-functions.asciidoc

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

27 lines
721 B
Plaintext
Raw Normal View History

Add two new OGC functions ST_X and ST_Y (#105768) * Add two new OGC functions ST_X and ST_Y Recently Nik did work that involved extracting the X and Y coordinates from geo_point data using `to_string(field)` followed by a DISSECT command to re-parse the string to get the X and Y coordinates. This is much more efficiently achieved using existing known OGC functions `ST_X` and `ST_Y`. * Update docs/changelog/105768.yaml * Fixed invalid changelog yaml * Fixed mixed cluster tests * Fixed tests and added docs * Removed false impression that these functions were different for geo/cartesian With the use of WKB as the core type in the compute engine, many spatial functions are actually the same between these two types, so we should not give the impression they are different. * Code review comments and reduced object creation. * Revert temporary StringUtils hack, and fix bug in x/y extraction from WKB * Revert object creation reduction * Fixed mistakes in documentation
2024-03-06 18:19:54 +08:00
[[esql-spatial-functions]]
==== {esql} spatial functions
++++
<titleabbrev>Spatial functions</titleabbrev>
++++
{esql} supports these spatial functions:
// tag::spatial_list[]
ESQL: Support ST_CONTAINS and ST_WITHIN (#106503) * WIP Started adding ST_CONTAINS * Add generated evaluators * Reduced warnings and use correct evaluators * Refactored tests to remove duplicate code, and fixed Contains/multi-components * Gradle build disallows using getDeclaredField * Fixed cases where rectangles cross the dateline * Fixed meta function tests * Added ST_WITHIN to support inverting ST_CONTAINS If the ST_CONTAINS is called with the constant on the left, we either have to create a lot more Evaluators to cover that case, or we have to invert it to ST_WITHIN. This inversion was a much easier option. * Simplify inversion logic * Add comment on choice of surrogate approach * Add unit tests and missing fold() function * Simple code cleanup * Add integration tests for literals * Add more integration tests based on actual data * Generated documentation files * Add documentation * Fixed failing function count test * Add tests that push-to-source works for ST_CONTAINS and ST_WITHIN * Test more combinations of WITH/CONTAINS and literal on right and left This also verifies that the re-writing of CONTAINS to WITHIN or vice versa occurs when the literal is on the left. * test that physical planning also handles doc-values from STATS * Added more tests for WITHIN/CONTAINS together with CENTROID This should test the doc-values for points. * Add cartesian_point tests * Add cartesian_shape tests * Disable Lucene-push-down for CARTESIAN data This is a limitation in Lucene, which we could address as a performance optimization in a future PR, but since it probably requires Lucene changes, it cannot be done in this work. * Fix doc links * Added test data and tests for cartesian multi-polygons Testing INTERSECTS, CONTAINS and WITHIN with multi-polydon fields * Use required features for spatial points, shapes and centroid * 8.13.0 is not yet historical version This needs to be reverted as soon as 8.13.0 is released * Added st_intersects and st_contains_within 'features' * Code review updates * Re-enable lucene push-down * Added more required_features * Fix point contains non-point * Fix point contains point * Re-enable lucene push-down in tests too Forgot to change the physical planner unit tests after re-enabling lucene push-down * Generate automatic docs * Use generated examples docs * Generated examples use '-result' prefix (singular) * Mark spatial functions as preview/experimental
2024-04-02 16:31:00 +08:00
* experimental:[] <<esql-st_intersects>>
ESQL: Support ST_DISJOINT (#107007) * WIP Started developing ST_DISJOINT Initially based on ST_INTERSECTS * Fix functions list and add spatial point integration tests * Update docs/changelog/107007.yaml * More tests for shapes and cartesian-multigeoms * Some more tests to highlight issues with DISJOINT on cartesian point indices * Disable Lucene push-down for DISJOINT on cartesian point indices * Added docs for ST_DISJOINT * Support DISJOINT in the lucene-pushdown code for cartesian point indexes * Re-enable push-to-source for DISJOINT on cartesian_point indices * Fix docs example * Try fix internal docs links which are not being rendered * Fixed disjoint on empty geometry * Added tests on empty linestring, and changed lucene push-down to exception In lucene code only LineString can be empty, but in Elasticsearch even that is not allowed, resulting in parsing errors. So we cannot get to this code in the lucene push-down and now throw an error instead. The tests now assert on the warnings. Note that for any predicate DISJOINT and INTERSECTS alike, the predicate fails, because the parsing error results in null, the function returns null, the predicate interprets this as false, and no documents match. This null-in-null-out rule means that DISJOINT and INTERSECTS give the same answer on invalid geometries.
2024-04-08 18:26:26 +08:00
* experimental:[] <<esql-st_disjoint>>
ESQL: Support ST_CONTAINS and ST_WITHIN (#106503) * WIP Started adding ST_CONTAINS * Add generated evaluators * Reduced warnings and use correct evaluators * Refactored tests to remove duplicate code, and fixed Contains/multi-components * Gradle build disallows using getDeclaredField * Fixed cases where rectangles cross the dateline * Fixed meta function tests * Added ST_WITHIN to support inverting ST_CONTAINS If the ST_CONTAINS is called with the constant on the left, we either have to create a lot more Evaluators to cover that case, or we have to invert it to ST_WITHIN. This inversion was a much easier option. * Simplify inversion logic * Add comment on choice of surrogate approach * Add unit tests and missing fold() function * Simple code cleanup * Add integration tests for literals * Add more integration tests based on actual data * Generated documentation files * Add documentation * Fixed failing function count test * Add tests that push-to-source works for ST_CONTAINS and ST_WITHIN * Test more combinations of WITH/CONTAINS and literal on right and left This also verifies that the re-writing of CONTAINS to WITHIN or vice versa occurs when the literal is on the left. * test that physical planning also handles doc-values from STATS * Added more tests for WITHIN/CONTAINS together with CENTROID This should test the doc-values for points. * Add cartesian_point tests * Add cartesian_shape tests * Disable Lucene-push-down for CARTESIAN data This is a limitation in Lucene, which we could address as a performance optimization in a future PR, but since it probably requires Lucene changes, it cannot be done in this work. * Fix doc links * Added test data and tests for cartesian multi-polygons Testing INTERSECTS, CONTAINS and WITHIN with multi-polydon fields * Use required features for spatial points, shapes and centroid * 8.13.0 is not yet historical version This needs to be reverted as soon as 8.13.0 is released * Added st_intersects and st_contains_within 'features' * Code review updates * Re-enable lucene push-down * Added more required_features * Fix point contains non-point * Fix point contains point * Re-enable lucene push-down in tests too Forgot to change the physical planner unit tests after re-enabling lucene push-down * Generate automatic docs * Use generated examples docs * Generated examples use '-result' prefix (singular) * Mark spatial functions as preview/experimental
2024-04-02 16:31:00 +08:00
* experimental:[] <<esql-st_contains>>
* experimental:[] <<esql-st_within>>
* experimental:[] <<esql-st_x>>
* experimental:[] <<esql-st_y>>
ES|QL ST_DISTANCE Function (#108764) * WIP Started refactoring in preparation for ST_DISTANCE * Initial evaluators for ST_DISTANCE * Update docs/changelog/108764.yaml * Fix invalid changelog generated by CI * Register function and get unit tests working * Fixed failing meta function description tests, and refined descriptions * Added initial CsvTests and calculate Geo differently to Cartesian * Added more csv-spec tests and changed to arcDistance for accuracy * Added generated docs files * Link to generated docs * Fix examples tag for linking from generated docs * Skip wrapper function And note that we might want to include instead some of the related intelligence from Circle2D::HaversineDistance class * Added ST_DWITHIN and more tests for ST_DISTANCE and ST_DWITHIN * Code style * Added more tests, this time for sorting on distance * Fixes after rebase on main * The ST_DWITHIN cannot use BinarySpatialFunction because it is ternary So we moved the common code to a separate SpatialTypeResolver, and made a simpler TernarySpatialFunction based on a simple TernaryScalarFunction. This had additional consequences, simplifying the points-only cases. The main reason for this change was to support StDWithinTests which need to test a lot of things that involve varying all three input types, generating expected error strings, etc. The original hack of just adding to BinarySpatialFunction worked for the actual integration tests, but clearly did not satisfy all the use cases tested by the unit tests. We also restricted ST_DWITHIN to take only a double as the third argument, because otherwise the number of evaluators would explode, since we need a separate evaluator for each Block type, and Integer and Double use different block types. * Fixed function count after rebasing on main * Update docs/changelog/108764.yaml * Added generated docs for ST_DWITHIN * Connect docs for ST_DWITHIN * Add back issue link * Remove support for ST_DWITHIN * Update docs/changelog/108764.yaml * Bring back link to issue in changelog * Update x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/spatial/StDistance.java Co-authored-by: Ignacio Vera <iverase@gmail.com> * Revert reformatting of function descriptions We should put this into a separate PR * Github merged commit with incorrectly formatted whitespace --------- Co-authored-by: Ignacio Vera <iverase@gmail.com>
2024-06-21 17:59:44 +08:00
* experimental:[] <<esql-st_distance>>
Add two new OGC functions ST_X and ST_Y (#105768) * Add two new OGC functions ST_X and ST_Y Recently Nik did work that involved extracting the X and Y coordinates from geo_point data using `to_string(field)` followed by a DISSECT command to re-parse the string to get the X and Y coordinates. This is much more efficiently achieved using existing known OGC functions `ST_X` and `ST_Y`. * Update docs/changelog/105768.yaml * Fixed invalid changelog yaml * Fixed mixed cluster tests * Fixed tests and added docs * Removed false impression that these functions were different for geo/cartesian With the use of WKB as the core type in the compute engine, many spatial functions are actually the same between these two types, so we should not give the impression they are different. * Code review comments and reduced object creation. * Revert temporary StringUtils hack, and fix bug in x/y extraction from WKB * Revert object creation reduction * Fixed mistakes in documentation
2024-03-06 18:19:54 +08:00
// end::spatial_list[]
[ES|QL] Add/Modify annotations for spatial and conditional functions for better doc generation (#107722) * annotation for spatial functions and conditional functions
2024-05-11 02:49:25 +08:00
include::layout/st_intersects.asciidoc[]
include::layout/st_disjoint.asciidoc[]
include::layout/st_contains.asciidoc[]
include::layout/st_within.asciidoc[]
include::layout/st_x.asciidoc[]
include::layout/st_y.asciidoc[]
ES|QL ST_DISTANCE Function (#108764) * WIP Started refactoring in preparation for ST_DISTANCE * Initial evaluators for ST_DISTANCE * Update docs/changelog/108764.yaml * Fix invalid changelog generated by CI * Register function and get unit tests working * Fixed failing meta function description tests, and refined descriptions * Added initial CsvTests and calculate Geo differently to Cartesian * Added more csv-spec tests and changed to arcDistance for accuracy * Added generated docs files * Link to generated docs * Fix examples tag for linking from generated docs * Skip wrapper function And note that we might want to include instead some of the related intelligence from Circle2D::HaversineDistance class * Added ST_DWITHIN and more tests for ST_DISTANCE and ST_DWITHIN * Code style * Added more tests, this time for sorting on distance * Fixes after rebase on main * The ST_DWITHIN cannot use BinarySpatialFunction because it is ternary So we moved the common code to a separate SpatialTypeResolver, and made a simpler TernarySpatialFunction based on a simple TernaryScalarFunction. This had additional consequences, simplifying the points-only cases. The main reason for this change was to support StDWithinTests which need to test a lot of things that involve varying all three input types, generating expected error strings, etc. The original hack of just adding to BinarySpatialFunction worked for the actual integration tests, but clearly did not satisfy all the use cases tested by the unit tests. We also restricted ST_DWITHIN to take only a double as the third argument, because otherwise the number of evaluators would explode, since we need a separate evaluator for each Block type, and Integer and Double use different block types. * Fixed function count after rebasing on main * Update docs/changelog/108764.yaml * Added generated docs for ST_DWITHIN * Connect docs for ST_DWITHIN * Add back issue link * Remove support for ST_DWITHIN * Update docs/changelog/108764.yaml * Bring back link to issue in changelog * Update x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/spatial/StDistance.java Co-authored-by: Ignacio Vera <iverase@gmail.com> * Revert reformatting of function descriptions We should put this into a separate PR * Github merged commit with incorrectly formatted whitespace --------- Co-authored-by: Ignacio Vera <iverase@gmail.com>
2024-06-21 17:59:44 +08:00
include::layout/st_distance.asciidoc[]