XYShape (Lucene 10.5.1 core API)
Description: declaration: package: org.apache.lucene.document, class: XYShape

Package org.apache.lucene.document

# Class XYShape

java.lang.Object
org.apache.lucene.document.XYShape

public class XYShape extends Object
A cartesian shape utility class for indexing and searching geometries whose vertices are unitless x, y values.

This class defines seven static factory methods for common indexing and search operations:

- `createIndexableFields(String, XYPolygon)` for indexing a cartesian polygon.
- `createDocValueField(String, XYPolygon)` for indexing a cartesian polygon doc value field.
- `createIndexableFields(String, XYPolygon, boolean)` for indexing a cartesian polygon with the possibility of checking for self-intersections.
- `createIndexableFields(String, XYPolygon, boolean)` for indexing a cartesian polygon doc value field with the possibility of checking for self-intersections.
- `createIndexableFields(String, XYLine)` for indexing a cartesian linestring.
- `createDocValueField(String, XYLine)` for indexing a cartesian linestring doc value.
- `createIndexableFields(String, float, float)` for indexing a x, y cartesian point.
- `createDocValueField(String, float, float)` for indexing a x, y cartesian point doc value.
- `createDocValueField(String, BytesRef)` for indexing a cartesian doc value from existing encoding.
- `newBoxQuery()` for matching cartesian shapes that have some `ShapeField.QueryRelation` with a bounding box.
- `newLineQuery()` for matching cartesian shapes that have some `ShapeField.QueryRelation` with a linestring.
- `newPolygonQuery()` for matching cartesian shapes that have some `ShapeField.QueryRelation` with a polygon.
- `newGeometryQuery()` for matching cartesian shapes that have some `ShapeField.QueryRelation` with one or more `XYGeometry`.
- `createXYShapeDocValues(BytesRef)` for creating the `XYShapeDocValues`

WARNING: Like `LatLonPoint`, vertex values are indexed with some loss of precision from the original `double` values.

See Also:
  - `PointValues`
  - `XYDocValuesField`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static XYShapeDocValuesField`
  `createDocValueField(String fieldName, float x, float y)`
  create a `XYShapeDocValuesField` for cartesian points without creating indexable fields.
  `static XYShapeDocValuesField`
  `createDocValueField(String fieldName, List<ShapeField.DecodedTriangle> tessellation)`
  create a `XYShapeDocValuesField` from a precomputed tessellation
  `static XYShapeDocValuesField`
  `createDocValueField(String fieldName, XYLine line)`
  create doc value field for x, y line geometry without creating indexable fields.
  `static XYShapeDocValuesField`
  `createDocValueField(String fieldName, XYPolygon polygon)`
  create doc value field for X,Y polygon geometry without creating indexable fields
  `static XYShapeDocValuesField`
  `createDocValueField(String fieldName, XYPolygon polygon, boolean checkSelfIntersections)`
  create doc value field for lat lon polygon geometry without creating indexable fields.
  `static XYShapeDocValuesField`
  `createDocValueField(String fieldName, BytesRef binaryValue)`
  create a `XYShapeDocValuesField` from an existing encoded representation
  `static Field[]`
  `createIndexableFields(String fieldName, float x, float y)`
  create indexable fields for cartesian point geometry
  `static Field[]`
  `createIndexableFields(String fieldName, XYLine line)`
  create indexable fields for cartesian line geometry
  `static Field[]`
  `createIndexableFields(String fieldName, XYPolygon polygon)`
  create indexable fields for cartesian polygon geometry
  `static Field[]`
  `createIndexableFields(String fieldName, XYPolygon polygon, boolean checkSelfIntersections)`
  create indexable fields for cartesian polygon geometry.
  `static XYShapeDocValues`
  `createXYShapeDocValues(BytesRef bytesRef)`
  Factory method for creating the `XYShapeDocValues`
  `static Query`
  `newBoxQuery(String field, ShapeField.QueryRelation queryRelation, float minX, float maxX, float minY, float maxY)`
  create a query to find all cartesian shapes that intersect a defined bounding box *
  `static Query`
  `newDistanceQuery(String field, ShapeField.QueryRelation queryRelation, XYCircle... circle)`
  create a query to find all cartesian shapes that intersect a provided circle (or arrays of circles) *
  `static Query`
  `newGeometryQuery(String field, ShapeField.QueryRelation queryRelation, XYGeometry... xyGeometries)`
  create a query to find all indexed geo shapes that intersect a provided geometry collection note: Components do not support dateline crossing
  `static Query`
  `newLineQuery(String field, ShapeField.QueryRelation queryRelation, XYLine... lines)`
  create a query to find all cartesian shapes that intersect a provided linestring (or array of linestrings) *
  `static Query`
  `newPointQuery(String field, ShapeField.QueryRelation queryRelation, float[]... points)`
  create a query to find all indexed shapes that comply the `ShapeField.QueryRelation` with the provided point
  `static Query`
  `newPolygonQuery(String field, ShapeField.QueryRelation queryRelation, XYPolygon... polygons)`
  create a query to find all cartesian shapes that intersect a provided polygon (or array of polygons) *
  `static Query`
  `newSlowDocValuesBoxQuery(String field, ShapeField.QueryRelation queryRelation, float minX, float maxX, float minY, float maxY)`
  create a docvalue query to find all cartesian shapes that intersect a defined bounding box *

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Method Details

  - ### createIndexableFields

    public static Field[] createIndexableFields(String fieldName, XYPolygon polygon)
    create indexable fields for cartesian polygon geometry

  - ### createDocValueField

    public static XYShapeDocValuesField createDocValueField(String fieldName, XYPolygon polygon)
    create doc value field for X,Y polygon geometry without creating indexable fields

  - ### createIndexableFields

    public static Field[] createIndexableFields(String fieldName, XYPolygon polygon, boolean checkSelfIntersections)
    create indexable fields for cartesian polygon geometry. If `checkSelfIntersections` is set to true, the validity of the provided polygon is checked with a small performance penalty.

  - ### createDocValueField

    public static XYShapeDocValuesField createDocValueField(String fieldName, XYPolygon polygon, boolean checkSelfIntersections)
    create doc value field for lat lon polygon geometry without creating indexable fields.

  - ### createIndexableFields

    public static Field[] createIndexableFields(String fieldName, XYLine line)
    create indexable fields for cartesian line geometry

  - ### createDocValueField

    public static XYShapeDocValuesField createDocValueField(String fieldName, XYLine line)
    create doc value field for x, y line geometry without creating indexable fields.

  - ### createIndexableFields

    public static Field[] createIndexableFields(String fieldName, float x, float y)
    create indexable fields for cartesian point geometry

  - ### createDocValueField

    public static XYShapeDocValuesField createDocValueField(String fieldName, float x, float y)
    create a `XYShapeDocValuesField` for cartesian points without creating indexable fields.

  - ### createDocValueField

    public static XYShapeDocValuesField createDocValueField(String fieldName, BytesRef binaryValue)
    create a `XYShapeDocValuesField` from an existing encoded representation

  - ### createDocValueField

    public static XYShapeDocValuesField createDocValueField(String fieldName, List<ShapeField.DecodedTriangle> tessellation)
    create a `XYShapeDocValuesField` from a precomputed tessellation

  - ### newBoxQuery

    public static Query newBoxQuery(String field, ShapeField.QueryRelation queryRelation, float minX, float maxX, float minY, float maxY)
    create a query to find all cartesian shapes that intersect a defined bounding box *

  - ### newSlowDocValuesBoxQuery

    public static Query newSlowDocValuesBoxQuery(String field, ShapeField.QueryRelation queryRelation, float minX, float maxX, float minY, float maxY)
    create a docvalue query to find all cartesian shapes that intersect a defined bounding box *

  - ### newLineQuery

    public static Query newLineQuery(String field, ShapeField.QueryRelation queryRelation, XYLine... lines)
    create a query to find all cartesian shapes that intersect a provided linestring (or array of linestrings) *

  - ### newPolygonQuery

    public static Query newPolygonQuery(String field, ShapeField.QueryRelation queryRelation, XYPolygon... polygons)
    create a query to find all cartesian shapes that intersect a provided polygon (or array of polygons) *

  - ### newPointQuery

    public static Query newPointQuery(String field, ShapeField.QueryRelation queryRelation, float[]... points)
    create a query to find all indexed shapes that comply the `ShapeField.QueryRelation` with the provided point

  - ### newDistanceQuery

    public static Query newDistanceQuery(String field, ShapeField.QueryRelation queryRelation, XYCircle... circle)
    create a query to find all cartesian shapes that intersect a provided circle (or arrays of circles) *

  - ### newGeometryQuery

    public static Query newGeometryQuery(String field, ShapeField.QueryRelation queryRelation, XYGeometry... xyGeometries)
    create a query to find all indexed geo shapes that intersect a provided geometry collection note: Components do not support dateline crossing

  - ### createXYShapeDocValues

    public static XYShapeDocValues createXYShapeDocValues(BytesRef bytesRef)
    Factory method for creating the `XYShapeDocValues`
    Parameters:
      `bytesRef` - `BytesRef`
    Returns:
      `XYShapeDocValues`