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

Package org.apache.lucene.document

# Class BinaryPoint

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

All Implemented Interfaces:
  `IndexableField`

public final class BinaryPoint extends Field
An indexed binary field for fast range filters. If you also need to store the value, you should add a separate `StoredField` instance.

Finding all documents within an N-dimensional shape or range at search time is efficient. Multiple values for the same field in one document is allowed.

This field defines static factory methods for creating common queries:

- `newExactQuery(String, byte[])` for matching an exact 1D point.
- `newSetQuery(String, byte[]...)` for matching a set of 1D values.
- `newRangeQuery(String, byte[], byte[])` for matching a 1D range.
- `newRangeQuery(String, byte[][], byte[][])` for matching points/ranges in n-dimensional space.

See Also:
  - `PointValues`

- ## Nested Class Summary

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

  `Field.Store`

- ## Field Summary

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

  `fieldsData, name, type`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `BinaryPoint(String name, byte[]... point)`
  General purpose API: creates a new BinaryPoint, indexing the provided N-dimensional binary point.
  `BinaryPoint(String name, byte[] packedPoint, IndexableFieldType type)`
  Expert API

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static Query`
  `newExactQuery(String field, byte[] value)`
  Create a query for matching an exact binary value.
  `static Query`
  `newRangeQuery(String field, byte[][] lowerValue, byte[][] upperValue)`
  Create a range query for n-dimensional binary values.
  `static Query`
  `newRangeQuery(String field, byte[] lowerValue, byte[] upperValue)`
  Create a range query for binary values.
  `static Query`
  `newSetQuery(String field, byte[]... values)`
  Create a query matching any of the specified 1D values.

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

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

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

- ## Constructor Details

  - ### BinaryPoint

    public BinaryPoint(String name, byte[]... point)
    General purpose API: creates a new BinaryPoint, indexing the provided N-dimensional binary point.
    Parameters:
      `name` - field name
      `point` - byte[][] value
    Throws:
      `IllegalArgumentException` - if the field name or value is null.

  - ### BinaryPoint

    public BinaryPoint(String name, byte[] packedPoint, IndexableFieldType type)
    Expert API

- ## Method Details

  - ### newExactQuery

    public static Query newExactQuery(String field, byte[] value)
    Create a query for matching an exact binary value.

    This is for simple one-dimension points, for multidimensional points use `newRangeQuery(String, byte[][], byte[][])` instead.

    Parameters:
      `field` - field name. must not be `null`.
      `value` - binary value
    Returns:
      a query matching documents with this exact value
    Throws:
      `IllegalArgumentException` - if `field` is null or `value` is null

  - ### newRangeQuery

    public static Query newRangeQuery(String field, byte[] lowerValue, byte[] upperValue)
    Create a range query for binary values.

    This is for simple one-dimension ranges, for multidimensional ranges use `newRangeQuery(String, byte[][], byte[][])` instead.

    Parameters:
      `field` - field name. must not be `null`.
      `lowerValue` - lower portion of the range (inclusive). must not be `null`
      `upperValue` - upper portion of the range (inclusive). must not be `null`
    Returns:
      a query matching documents within this range.
    Throws:
      `IllegalArgumentException` - if `field` is null, if `lowerValue` is null, or if `upperValue` is null

  - ### newRangeQuery

    public static Query newRangeQuery(String field, byte[][] lowerValue, byte[][] upperValue)
    Create a range query for n-dimensional binary values.
    Parameters:
      `field` - field name. must not be `null`.
      `lowerValue` - lower portion of the range (inclusive). must not be null.
      `upperValue` - upper portion of the range (inclusive). must not be null.
    Returns:
      a query matching documents within this range.
    Throws:
      `IllegalArgumentException` - if `field` is null, if `lowerValue` is null, if `upperValue` is null, or if `lowerValue.length != upperValue.length`

  - ### newSetQuery

    public static Query newSetQuery(String field, byte[]... values)
    Create a query matching any of the specified 1D values. This is the points equivalent of `TermsQuery`.
    Parameters:
      `field` - field name. must not be `null`.
      `values` - all values to match