org.apache.lucene.document

## Class XYDocValuesField

- java.lang.Object
- - org.apache.lucene.document.Field
  - - org.apache.lucene.document.XYDocValuesField

- All Implemented Interfaces:
    IndexableField

      public class XYDocValuesField
      extends Field

  An per-document location field.

  Sorting by distance is efficient. Multiple values for the same field in one document is allowed.

  This field defines static factory methods for common operations:

  - `newSlowBoxQuery()` for matching points within a bounding box.
  - `newSlowDistanceQuery()` for matching points within a specified distance.
  - `newSlowPolygonQuery()` for matching points within an arbitrary polygon.
  - `newSlowGeometryQuery()` for matching points within an arbitrary geometry.
  - `newDistanceSort()` for ordering documents by distance from a specified location.

  If you also need query operations, you should add a separate `XYPointField` instance. If you also need to store the value, you should add a separate `StoredField` instance.

  See Also:
    `XYPointField`

- - ### 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 FieldType` | `TYPE` Type for a XYDocValuesField

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

      `fieldsData, name, tokenStream, type`

  - ### Constructor Summary

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

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static SortField` | `newDistanceSort(String field, float x, float y)` Creates a SortField for sorting by distance from a location.
    `static Query` | `newSlowBoxQuery(String field, float minX, float maxX, float minY, float maxY)` Create a query for matching a bounding box using doc values.
    `static Query` | `newSlowDistanceQuery(String field, float x, float y, float radius)` Create a query for matching points within the specified distance of the supplied location.
    `static Query` | `newSlowGeometryQuery(String field, XYGeometry... geometries)` Create a query for matching points within the supplied geometries.
    `static Query` | `newSlowPolygonQuery(String field, XYPolygon... polygons)` Create a query for matching points within the supplied 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

    - #### TYPE

          public static final FieldType TYPE

      Type for a XYDocValuesField

      Each value stores a 64-bit long where the upper 32 bits are the encoded x value, and the lower 32 bits are the encoded y value.

      See Also:
        `XYEncodingUtils.decode(int)`

  - ### Constructor Detail

    - #### XYDocValuesField

          public XYDocValuesField(String name,
                                  float x,
                                  float y)

      Creates a new XYDocValuesField with the specified x and y
      Parameters:
        `name` - field name
        `x` - x value.
        `y` - y values.
      Throws:
        `IllegalArgumentException` - if the field name is null or x or y are infinite or NaN.

  - ### Method Detail

    - #### setLocationValue

          public void setLocationValue(float x,
                                       float y)

      Change the values of this field
      Parameters:
        `x` - x value.
        `y` - y value.
      Throws:
        `IllegalArgumentException` - if x or y are infinite or NaN.

    - #### toString

          public String toString()

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

    - #### newDistanceSort

          public static SortField newDistanceSort(String field,
                                                  float x,
                                                  float y)

      Creates a SortField for sorting by distance from a location.

      This sort orders documents by ascending distance from the location. The value returned in `FieldDoc` for the hits contains a Double instance with the distance in meters.

      If a document is missing the field, then by default it is treated as having `Double.POSITIVE_INFINITY` distance (missing values sort last).

      If a document contains multiple values for the field, the closest distance to the location is used.

      Parameters:
        `field` - field name. must not be null.
        `x` - x at the center.
        `y` - y at the center.
      Returns:
        SortField ordering documents by distance
      Throws:
        `IllegalArgumentException` - if `field` is null or location has invalid coordinates.

    - #### newSlowBoxQuery

          public static Query newSlowBoxQuery(String field,
                                              float minX,
                                              float maxX,
                                              float minY,
                                              float maxY)

      Create a query for matching a bounding box using doc values. This query is usually slow as it does not use an index structure and needs to verify documents one-by-one in order to know whether they match. It is best used wrapped in an `IndexOrDocValuesQuery` alongside a `XYPointField.newBoxQuery(java.lang.String, float, float, float, float)`.

    - #### newSlowDistanceQuery

          public static Query newSlowDistanceQuery(String field,
                                                   float x,
                                                   float y,
                                                   float radius)

      Create a query for matching points within the specified distance of the supplied location. This query is usually slow as it does not use an index structure and needs to verify documents one-by-one in order to know whether they match. It is best used wrapped in an `IndexOrDocValuesQuery` alongside a `XYPointField.newDistanceQuery(java.lang.String, float, float, float)`.
      Parameters:
        `field` - field name. must not be null.
        `x` - x at the center.
        `y` - y at the center: must be within standard +/-180 coordinate bounds.
        `radius` - maximum distance from the center in cartesian distance: 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.

    - #### newSlowPolygonQuery

          public static Query newSlowPolygonQuery(String field,
                                                  XYPolygon... polygons)

      Create a query for matching points within the supplied polygons. This query is usually slow as it does not use an index structure and needs to verify documents one-by-one in order to know whether they match. It is best used wrapped in an `IndexOrDocValuesQuery` alongside a `XYPointField.newPolygonQuery(String, XYPolygon...)`.
      Parameters:
        `field` - field name. must not be null.
        `polygons` - array of polygons. must not be null or empty.
      Returns:
        query matching points within the given polygons.
      Throws:
        `IllegalArgumentException` - if `field` is null or polygons is empty or contain a null polygon.

    - #### newSlowGeometryQuery

          public static Query newSlowGeometryQuery(String field,
                                                   XYGeometry... geometries)

      Create a query for matching points within the supplied geometries. XYLine geometries are not supported. This query is usually slow as it does not use an index structure and needs to verify documents one-by-one in order to know whether they match. It is best used wrapped in an `IndexOrDocValuesQuery` alongside a `XYPointField.newGeometryQuery(String, XYGeometry...)`.
      Parameters:
        `field` - field name. must not be null.
        `geometries` - array of XY geometries. must not be null or empty.
      Returns:
        query matching points within the given geometries.
      Throws:
        `IllegalArgumentException` - if `field` is null, `polygons` is null, empty or contains a null or XYLine geometry.

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