Package org.apache.iceberg.geospatial

Class GeospatialBound

java.lang.Object
org.apache.iceberg.geospatial.GeospatialBound
public class GeospatialBound extends Object
Represents a geospatial bound (minimum or maximum) for Iceberg tables.

According to the Bound serialization section of Iceberg Table spec, geospatial bounds are serialized differently from the regular WKB representation. Geometry and geography bounds are single point encoded as a concatenation of 8-byte little-endian IEEE 754 coordinate values in the order X, Y, Z (optional), M (optional).

The encoding varies based on which coordinates are present:

  • x:y (2 doubles) when both z and m are unset
  • x:y:z (3 doubles) when only m is unset
  • x:y:NaN:m (4 doubles) when only z is unset
  • x:y:z:m (4 doubles) when all coordinates are set

This class represents a lower or upper geospatial bound and handles serialization and deserialization of these bounds to/from byte arrays, conforming to the Iceberg specification.

  • Method Summary

    Modifier and Type
    Method
    Description
    static GeospatialBound
    createXY(double x, double y)
    Creates a GeospatialBound with X and Y coordinates only.
    static GeospatialBound
    createXYM(double x, double y, double m)
    Creates a GeospatialBound with X, Y, and M values, with no Z coordinate.
    static GeospatialBound
    createXYZ(double x, double y, double z)
    Creates a GeospatialBound with X, Y, and Z coordinates, with no M value.
    static GeospatialBound
    createXYZM(double x, double y, double z, double m)
    Creates a GeospatialBound with X, Y, Z, and M coordinates.
    boolean
    equals(Object other)
     
    static GeospatialBound
    fromByteArray(byte[] bytes)
    Parses a geospatial bound from a byte array according to Iceberg spec.
    static GeospatialBound
    fromByteBuffer(ByteBuffer buffer)
    Parses a geospatial bound from a byte buffer according to Iceberg spec.
    int
    hashCode()
     
    boolean
    hasM()
    Check if this bound has a defined M value.
    boolean
    hasZ()
    Check if this bound has a defined Z coordinate.
    double
    m()
    Get the M value (measure).
    String
    simpleString()
     
    ByteBuffer
    toByteBuffer()
    Serializes this geospatial bound to a byte buffer according to Iceberg spec.
    String
    toString()
     
    double
    x()
    Get the X coordinate (longitude/easting).
    double
    y()
    Get the Y coordinate (latitude/northing).
    double
    z()
    Get the Z coordinate (typically elevation).

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

  • Method Details

    • fromByteBuffer

      public static GeospatialBound fromByteBuffer(ByteBuffer buffer)
      Parses a geospatial bound from a byte buffer according to Iceberg spec.

      Based on the buffer size, this method determines which coordinates are present:

      • 16 bytes (2 doubles): x and y only
      • 24 bytes (3 doubles): x, y, and z
      • 32 bytes (4 doubles): x, y, z (might be NaN), and m

      The ordinates are encoded as 8-byte little-endian IEEE 754 values.

      Parameters:
      buffer - the ByteBuffer containing the serialized geospatial bound
      Returns:
      a GeospatialBound object representing the parsed bound
      Throws:
      IllegalArgumentException - if the buffer has an invalid size

    • toByteBuffer

      public ByteBuffer toByteBuffer()
      Serializes this geospatial bound to a byte buffer according to Iceberg spec.

      Following the Iceberg spec, the bound is serialized based on which coordinates are set:

      • x:y (2 doubles) when both z and m are unset
      • x:y:z (3 doubles) when only m is unset
      • x:y:NaN:m (4 doubles) when only z is unset
      • x:y:z:m (4 doubles) when all coordinates are set
      Returns:
      A ByteBuffer containing the serialized geospatial bound

    • fromByteArray

      public static GeospatialBound fromByteArray(byte[] bytes)
      Parses a geospatial bound from a byte array according to Iceberg spec.
      Parameters:
      bytes - the byte array containing the serialized geospatial bound
      Returns:
      a GeospatialBound object representing the parsed bound
      Throws:
      IllegalArgumentException - if the byte array has an invalid length

    • createXY

      public static GeospatialBound createXY(double x, double y)
      Creates a GeospatialBound with X and Y coordinates only.
      Parameters:
      x - the X coordinate (longitude/easting)
      y - the Y coordinate (latitude/northing)
      Returns:
      a GeospatialBound with XY coordinates

    • createXYZ

      public static GeospatialBound createXYZ(double x, double y, double z)
      Creates a GeospatialBound with X, Y, and Z coordinates, with no M value.
      Parameters:
      x - the X coordinate (longitude/easting)
      y - the Y coordinate (latitude/northing)
      z - the Z coordinate (elevation)
      Returns:
      a GeospatialBound with XYZ coordinates

    • createXYZM

      public static GeospatialBound createXYZM(double x, double y, double z, double m)
      Creates a GeospatialBound with X, Y, Z, and M coordinates.
      Parameters:
      x - the X coordinate (longitude/easting)
      y - the Y coordinate (latitude/northing)
      z - the Z coordinate (elevation)
      m - the M value (measure)
      Returns:
      a GeospatialBound with XYZM coordinates

    • createXYM

      public static GeospatialBound createXYM(double x, double y, double m)
      Creates a GeospatialBound with X, Y, and M values, with no Z coordinate.
      Parameters:
      x - the X coordinate (longitude/easting)
      y - the Y coordinate (latitude/northing)
      m - the M value (measure)
      Returns:
      a GeospatialBound with XYM coordinates

    • x

      public double x()
      Get the X coordinate (longitude/easting).
      Returns:
      X coordinate value

    • y

      public double y()
      Get the Y coordinate (latitude/northing).
      Returns:
      Y coordinate value

    • z

      public double z()
      Get the Z coordinate (typically elevation).
      Returns:
      Z coordinate value or NaN if not set

    • m

      public double m()
      Get the M value (measure).
      Returns:
      M value or NaN if not set

    • hasZ

      public boolean hasZ()
      Check if this bound has a defined Z coordinate.
      Returns:
      true if Z is not NaN

    • hasM

      public boolean hasM()
      Check if this bound has a defined M value.
      Returns:
      true if M is not NaN

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • simpleString

      public String simpleString()

    • equals

      public boolean equals(Object other)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object