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 and Description
    --- | ---
    `static int` | `BYTES` XYPoint is encoded as integer values so number of bytes is 4
    `static FieldType` | `TYPE` Type for an indexed XYPoint

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

      `fieldsData, name, tokenStream, type`

  - ### Constructor Summary

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

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and 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, name, numericValue, readerValue, setBytesValue, setBytesValue, setByteValue, setDoubleValue, setFloatValue, setIntValue, setLongValue, setReaderValue, setShortValue, setStringValue, setTokenStream, stringValue, tokenStream, tokenStreamValue`

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

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

- - ### Field Detail

    - #### 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 Detail

    - #### 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 Detail

    - #### 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`

Copyright © 2000-2024 Apache Software Foundation. All Rights Reserved.