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`