> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wherobots.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Geometry and raster API migration

> Update queries for one-based indices, raster band stacking, and no-data replacement.

When upgrading to a WherobotsDB runtime that includes the Sedona 2.0 API changes, update the calls below. This guide describes API changes; Apache Sedona and WherobotsDB have separate release numbers.

## Use one-based indices

[ST\_GeometryN](/reference/wherobots-db/geometry-data/accessors/ST_GeometryN) and [ST\_InteriorRingN](/reference/wherobots-db/geometry-data/accessors/ST_InteriorRingN) now start at `1`. Add `1` to the index used by an older runtime to keep selecting the same element.

```sql theme={"system"}
-- Before: first geometry, using a zero-based index
ST_GeometryN(geom, 0)

-- After: first geometry, using a one-based index
ST_GeometryN(geom, 1)
```

An unchanged positive index selects the preceding element under the new convention. For example, `n = 1` selects the first element instead of the second. Zero, negative, and out-of-range indices return `NULL`.

For the integer grid-coordinate forms of [RS\_Value](/reference/wherobots-db/raster-data/operators/RS_Value) and [RS\_Values](/reference/wherobots-db/raster-data/operators/RS_Values), add `1` to both the column and row. Apply the change to every element of coordinate arrays. The upper-left pixel is now `(1, 1)`. Keeping both positive grid coordinates unchanged selects a pixel one column to the left and one row up in grid order.

```sql theme={"system"}
-- Before
RS_Value(raster, 0, 0, 1)
RS_Values(raster, array(0, 1), array(0, 2), 1)

-- After: the same pixels
RS_Value(raster, 1, 1, 1)
RS_Values(raster, array(1, 2), array(1, 3), 1)
```

Geometry-coordinate overloads, band indices, and other raster pixel functions retain their existing conventions.

## Rename raster band-stacking calls

Replace `RS_Union` with [RS\_Stack](/reference/wherobots-db/raster-data/operators/RS_Stack), and replace `RS_Union_Aggr` with [RS\_Stack\_Aggr](/reference/wherobots-db/raster-data/aggregate/RS_Stack_Aggr). Update SQL calls, including SQL expressions passed from Python. The old names are removed.

These functions stack bands from rasters with matching shapes. They do not mosaic spatially adjacent grids. Arguments and band ordering are unchanged.

## Separate no-data metadata from pixel replacement

[RS\_SetBandNoDataValue](/reference/wherobots-db/raster-data/operators/RS_SetBandNoDataValue) now only sets or clears a band's no-data metadata. It leaves pixel values unchanged. Its fourth `replace` argument is removed.

| Previous call | Replacement |
| - | - |
| `RS_SetBandNoDataValue(raster, band, value, false)` | `RS_SetBandNoDataValue(raster, band, value)` |
| `RS_SetBandNoDataValue(raster, band, value, true)` | `RS_ReplaceBandNoDataValue(raster, band, value)` |

[RS\_ReplaceBandNoDataValue](/reference/wherobots-db/raster-data/operators/RS_ReplaceBandNoDataValue) rewrites existing no-data pixels and updates the band's no-data metadata. The band must already declare a no-data value. To preserve the same no-data mask, choose a replacement value exactly representable in the band's pixel type and absent from valid pixels. The two- and three-argument metadata setter forms continue to work; passing `NULL` as the setter's value clears the metadata.

## Review raster boundary assumptions

[RS\_AsRaster](/reference/wherobots-db/raster-data/operators/RS_AsRaster) selects polygon pixels by their centers when `allTouched = false`; `true` also includes cells entered by the polygon's boundary. A polygon never selects a pixel it touches only on the pixel's boundary, whichever edge that is. Points select their containing half-open pixel. Lines select cells entered by their segments without requiring a pixel-center intersection. These geometry-specific rules also apply to [RS\_Clip](/reference/wherobots-db/raster-data/operators/RS_Clip), [RS\_SetValues](/reference/wherobots-db/raster-data/operators/RS_SetValues), and zonal statistics.

For `LineString` geometries, `allTouched = true` can expand the rasterization window at grid boundaries. This can change dimensions and selected pixels in `RS_AsRaster` with `useGeometryExtent = true`, and can also change selected pixels in `RS_Clip` and `RS_SetValues`.

With `useGeometryExtent = true`, `RS_AsRaster` returns `NULL` when the geometry neither burns nor overlaps a raster pixel. [RS\_PixelAsPoint](/reference/wherobots-db/raster-data/pixel-functions/RS_PixelAsPoint) now extrapolates coordinates outside the grid instead of throwing an out-of-bounds exception.

## Handle empty geometry results

[ST\_DistanceSphere](/reference/wherobots-db/geometry-data/measurement/ST_DistanceSphere) and [ST\_DistanceSpheroid](/reference/wherobots-db/geometry-data/measurement/ST_DistanceSpheroid) return `NULL` if either input is empty. [ST\_DWithin](/reference/wherobots-db/geometry-data/predicates/ST_DWithin) returns `false` for an empty input. Spherical [nearest-neighbor searches](/reference/wherobots-db/geometry-data/nearest-neighbour-searching) skip empty geometries.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.