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

Package org.apache.lucene.document

# Class XYPointField

java.lang.Object
org.apache.lucene.document.Field
org.apache.lucene.document.XYPointField

All Implemented Interfaces:
  `IndexableField`

public class XYPointField extends Field
An indexed XY position field.

Finding all documents within a range at search time is efficient. Multiple values for the same field in one document is allowed.

This field defines static factory methods for common operations:

- `newBoxQuery()` for matching points within a bounding box.
- `newDistanceQuery()` for matching points within a specified distance.
- `newPolygonQuery()` for matching points within an arbitrary polygon.
- `newGeometryQuery()` for matching points within an arbitrary geometry collection.

If you also need per-document operations such as sort by distance, add a separate `XYDocValuesField` instance. If you also need to store the value, you should add a separate `StoredField` instance.

See Also:
  - `PointValues`
  - `XYDocValuesField`

- ## Nested Class Summary

  ## Nested classes/interfaces inherited from class org.apache.lucene.document.Field

  `Field.Store`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `BYTES`
  XYPoint is encoded as integer values so number of bytes is 4
  `static final FieldType`
  `TYPE`
  Type for an indexed XYPoint

  ### Fields inherited from class org.apache.lucene.document.Field

  `fieldsData, name, type`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `XYPointField(String name, float x, float y)`
  Creates a new XYPoint with the specified x and y

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static Query`
  `newBoxQuery(String field, float minX, float maxX, float minY, float maxY)`
  Create a query for matching a bounding box.
  `static Query`
  `newDistanceQuery(String field, float x, float y, float radius)`
  Create a query for matching points within the specified distance of the supplied location.
  `static Query`
  `newGeometryQuery(String field, XYGeometry... xyGeometries)`
  create a query to find all indexed shapes that intersect a provided geometry collection.
  `static Query`
  `newPolygonQuery(String field, XYPolygon... polygons)`
  Create a query for matching one or more polygons.
  `void`
  `setLocationValue(float x, float y)`
  Change the values of this field
  `String`
  `toString()`
  Prints a Field for human consumption.

  ### Methods inherited from class org.apache.lucene.document.Field

  `binaryValue, fieldType, getCharSequenceValue, invertableType, name, numericValue, readerValue, setBytesValue, setBytesValue, setByteValue, setDoubleValue, setFloatValue, setIntValue, setLongValue, setReaderValue, setShortValue, setStringValue, setTokenStream, storedValue, stringValue, tokenStream, tokenStreamValue`

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

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

- ## Field Details

  - ### BYTES

    public static final int BYTES
    XYPoint is encoded as integer values so number of bytes is 4
    See Also:
      - Constant Field Values

  - ### TYPE

    public static final FieldType TYPE
    Type for an indexed XYPoint

    Each point stores two dimensions with 4 bytes per dimension.

- ## Constructor Details

  - ### XYPointField

    public XYPointField(String name, float x, float y)
    Creates a new XYPoint with the specified x and y
    Parameters:
      `name` - field name
      `x` - x value.
      `y` - y value.

- ## Method Details

  - ### setLocationValue

    public void setLocationValue(float x, float y)
    Change the values of this field
    Parameters:
      `x` - x value.
      `y` - y value.

  - ### toString

    public String toString()
    Description copied from class: `Field`
    Prints a Field for human consumption.
    Overrides:
      `toString` in class `Field`

  - ### newBoxQuery

    public static Query newBoxQuery(String field, float minX, float maxX, float minY, float maxY)
    Create a query for matching a bounding box.
    Parameters:
      `field` - field name. must not be null.
      `minX` - x lower bound.
      `maxX` - x upper bound.
      `minY` - y lower bound.
      `maxY` - y upper bound.
    Returns:
      query matching points within this box
    Throws:
      `IllegalArgumentException` - if `field` is null, or the box has invalid coordinates.

  - ### newDistanceQuery

    public static Query newDistanceQuery(String field, float x, float y, float radius)
    Create a query for matching points within the specified distance of the supplied location.
    Parameters:
      `field` - field name. must not be null.
      `x` - x at the center.
      `y` - y at the center.
      `radius` - maximum distance from the center in cartesian units: must be non-negative and finite.
    Returns:
      query matching points within this distance
    Throws:
      `IllegalArgumentException` - if `field` is null, location has invalid coordinates, or radius is invalid.

  - ### newPolygonQuery

    public static Query newPolygonQuery(String field, XYPolygon... polygons)
    Create a query for matching one or more polygons.
    Parameters:
      `field` - field name. must not be null.
      `polygons` - array of polygons. must not be null or empty
    Returns:
      query matching points within this polygon
    Throws:
      `IllegalArgumentException` - if `field` is null, `polygons` is null or empty
    See Also:
      - `Polygon`

  - ### newGeometryQuery

    public static Query newGeometryQuery(String field, XYGeometry... xyGeometries)
    create a query to find all indexed shapes that intersect a provided geometry collection. XYLine geometries are not supported.
    Parameters:
      `field` - field name. must not be null.
      `xyGeometries` - array of geometries. must not be null or empty.
    Returns:
      query matching points within this geometry collection.
    Throws:
      `IllegalArgumentException` - if `field` is null, `polygons` is null, empty or contains a null or XYLine geometry.
    See Also:
      - `XYGeometry`