RasterX Function Reference

Complete reference for all RasterX functions with detailed descriptions, parameters, return values, and examples.

Overview

RasterX provides functions for working with raster (pixel) data in Spark—loading, querying, transforming, and aggregating rasters from formats such as GeoTIFF, COG, and NetCDF.

Function Count: 65 functions organized into 6 categories (see rasterx/functions.scala):

Accessor Functions (29): Read raster properties and metadata (bounds, dimensions, CRS, bands, pixel size, georeference, format, type, NoData, subdatasets, summary, etc.)
Aggregator Functions (3): Combine or merge rasters in group-by (combineavg_agg, derivedband_agg, merge_agg)
Constructor Functions (3): Create or load rasters from paths, binary content, or bands
Generator Functions (5): Produce multiple tiles or bands (h3_tessellate, maketiles, retile, separatebands, tooverlappingtiles)
Grid Functions (H3) (5): Aggregate raster values to H3 cells (rastertogrid avg/count/max/min/median)
Operations (20): Transform and analyze rasters (clip, transform, merge, asformat, ndvi, filter, convolve, map algebra, coordinate conversion, isEmpty, tryOpen, initNoData, updateType, combineavg, derivedband)

SQL examples

Examples on this page use SQL, where RasterX functions are prefixed with gbx_ (e.g. gbx_rst_boundingbox, gbx_rst_width). For Python and Scala usage and more tips, see the Python, Scala, and SQL API pages.

Common setup

Run this once before the examples below. It registers RasterX and loads sample rasters into a temp view rasters.

Python:

RasterX setup
from databricks.labs.gbx.rasterx import functions as rx
rx.register(spark)
rasters = spark.read.format("gdal").load(SAMPLE_RASTER_PATH)
rasters.createOrReplaceTempView("rasters")

Example output
RasterX registered. Temp view `rasters` created from sample raster.

SQL: After registering RasterX (e.g. from Python above), create the view so SQL examples can use FROM rasters:

SQL view setup
RASTERX_SQL_SETUP = _rasterx_sql_setup_content()

RASTERX_SQL_SETUP_output = """
View `rasters` created. You can now run SELECT ... FROM rasters; for each example.
"""

# ============================================================================
# Accessor Functions - Get Raster Properties
# ============================================================================

Example output
View `rasters` created. You can now run SELECT ... FROM rasters; for each example.

Accessor Functions

Functions to read raster properties and metadata (29 total).

rst_avg

Signature: rst_avg(tile: Column): Column — Per-band average pixel values.

SQL:

-- Get average values
SELECT
    path,
    gbx_rst_avg(tile) as band_averages,
    gbx_rst_avg(tile)[0] as band1_avg
FROM rasters;

-- Filter by average threshold
SELECT * FROM rasters
WHERE gbx_rst_avg(tile)[0] > 50.0;

Example output
+----+--------------+----------+
|path|band_averages |band1_avg |
+----+--------------+----------+
|... |[0.42]        |0.42      |
+----+--------------+----------+

rst_bandmetadata

Signature: rst_bandmetadata(tile: Column, band: Column): Column — Band metadata map.

SQL:

SELECT gbx_rst_bandmetadata(tile, 1) as band1_metadata FROM rasters;

Example output
+----------------+
|band1_metadata  |
+----------------+
|{...}           |
+----------------+

rst_boundingbox

Signature: rst_boundingbox(tile: Column): Column — Bounding box geometry.

SQL:

SELECT path, gbx_rst_boundingbox(tile) as bbox FROM rasters;

Example output
+--------------------+-----------------+
|path                |bbox             |
+--------------------+-----------------+
|.../nyc_sentinel2...|POLYGON ((-74....|
+--------------------+-----------------+

rst_format

Signature: rst_format(tile: Column): Column — GDAL format name.

SQL:

-- Identify formats
SELECT
    gbx_rst_format(tile) as format,
    COUNT(*) as count
FROM rasters
GROUP BY gbx_rst_format(tile);

-- Find non-GeoTIFF files
SELECT path, gbx_rst_format(tile) as format
FROM rasters
WHERE gbx_rst_format(tile) != 'GTiff';

Example output
+------+-----+
|format|count|
+------+-----+
|GTiff |10   |
+------+-----+

rst_georeference

Signature: rst_georeference(tile: Column): Column — Georeference parameters as a map.

The result is a MapType with the following keys, corresponding to GDAL's 6-element geotransform:

Key	Geotransform index	Meaning
`upperLeftX`	GT(0)	X of the upper-left corner of the upper-left pixel
`upperLeftY`	GT(3)	Y of the upper-left corner of the upper-left pixel
`scaleX`	GT(1)	Pixel width (west–east resolution)
`scaleY`	GT(5)	Pixel height (north–south resolution; often negative for north-up)
`skewX`	GT(2)	Row rotation (typically 0)
`skewY`	GT(4)	Column rotation (typically 0)

See the GDAL geotransform tutorial and raster data model for details.

SQL:

SELECT gbx_rst_georeference(tile) as georeference FROM rasters;

Example output
+-------------+
|georeference |
+-------------+
|[ ... ]      |
+-------------+

rst_getnodata

Signature: rst_getnodata(tile: Column): Column — NoData values per band.

SQL:

SELECT
    path,
    gbx_rst_getnodata(tile) as nodata_values,
    gbx_rst_getnodata(tile)[0] as band1_nodata
FROM rasters;

Example output
+----+-------------+------------+
|path|nodata_values|band1_nodata|
+----+-------------+------------+
|... |[-9999.0]    |-9999.0     |
+----+-------------+------------+

rst_getsubdataset

Signature: rst_getsubdataset(tile: Column, subsetName: Column): Column — Extract subdataset.

SQL:

SELECT
    path,
    gbx_rst_getsubdataset(tile, 'temperature') as temp_layer
FROM netcdf_files;

Example output
+----+--------------------+
|path|temp_layer          |
+----+--------------------+
|... |[BINARY]            |
+----+--------------------+

rst_height

Signature: rst_height(tile: Column): Column — Height in pixels.

SQL:

SELECT gbx_rst_height(tile) as height, gbx_rst_width(tile) as width FROM rasters;

Example output
+------+-----+
|height|width|
+------+-----+
|10980 |10980|
+------+-----+

rst_max

Signature: rst_max(tile: Column): Column — Maximum pixel values per band.

SQL:

SELECT path, gbx_rst_max(tile) as max_per_band, gbx_rst_max(tile)[0] as band1_max FROM rasters;

Example output
+----+------------+----------+
|path|max_per_band|band1_max |
+----+------------+----------+
|... |[255.0]     |255.0     |
+----+------------+----------+

rst_median

Signature: rst_median(tile: Column): Column — Median pixel values per band.

SQL:

SELECT
    path,
    gbx_rst_avg(tile)[0] as mean_value,
    gbx_rst_median(tile)[0] as median_value,
    ABS(gbx_rst_avg(tile)[0] - gbx_rst_median(tile)[0]) as skewness
FROM rasters;

Example output
+----+----------+------------+--------+
|path|mean_value|median_value|skewness|
+----+----------+------------+--------+
|... |0.45      |0.42        |0.03    |
+----+----------+------------+--------+

rst_memsize

Signature: rst_memsize(tile: Column): Column — In-memory size in bytes.

SQL:

SELECT path, gbx_rst_memsize(tile) as size_bytes FROM rasters;

Example output
+----+----------+
|path|size_bytes|
+----+----------+
|... |120560400 |
+----+----------+

rst_metadata

Signature: rst_metadata(tile: Column): Column — Metadata map.

SQL:

SELECT gbx_rst_metadata(tile) as metadata FROM rasters;

Example output
+----------+
|metadata  |
+----------+
|{...}     |
+----------+

rst_min

Signature: rst_min(tile: Column): Column — Minimum pixel values per band.

SQL:

SELECT path, gbx_rst_min(tile) as min_per_band, gbx_rst_min(tile)[0] as band1_min FROM rasters;

Example output
+----+------------+----------+
|path|min_per_band|band1_min |
+----+------------+----------+
|... |[0.0]       |0.0       |
+----+------------+----------+

rst_numbands

Signature: rst_numbands(tile: Column): Column — Number of bands.

SQL:

SELECT gbx_rst_numbands(tile) as bands FROM rasters;

Example output
+------+
|bands |
+------+
|1     |
+------+

rst_pixelcount

Signature: rst_pixelcount(tile: Column): Column — Total pixel count.

SQL:

SELECT gbx_rst_pixelcount(tile) as pixel_count FROM rasters;

Example output
+------------+
|pixel_count |
+------------+
|120560400   |
+------------+

rst_pixelheight

Signature: rst_pixelheight(tile: Column): Column — Pixel height in ground units.

SQL:

SELECT
    path,
    gbx_rst_pixelwidth(tile) as pixel_width,
    gbx_rst_pixelheight(tile) as pixel_height,
    gbx_rst_width(tile) * gbx_rst_pixelwidth(tile) as total_width_m
FROM rasters;

Example output
+----+-----------+------------+--------------+
|path|pixel_width|pixel_height|total_width_m |
+----+-----------+------------+--------------+
|... |30.0       |-30.0       |329400.0      |
+----+-----------+------------+--------------+

rst_pixelwidth

Signature: rst_pixelwidth(tile: Column): Column — Pixel width in ground units.

SQL:

SELECT
    path,
    gbx_rst_pixelwidth(tile) as pixel_width,
    gbx_rst_pixelheight(tile) as pixel_height,
    gbx_rst_width(tile) * gbx_rst_pixelwidth(tile) as total_width_m
FROM rasters;

Example output
+----+-----------+------------+--------------+
|path|pixel_width|pixel_height|total_width_m |
+----+-----------+------------+--------------+
|... |30.0       |-30.0       |329400.0      |
+----+-----------+------------+--------------+

rst_rotation

Signature: rst_rotation(tile: Column): Column — Rotation in radians.

SQL:

SELECT path, gbx_rst_rotation(tile) as rotation_rad FROM rasters;

Example output
+----+------------+
|path|rotation_rad|
+----+------------+
|... |0.0         |
+----+------------+

rst_scalex / rst_scaley

Signature: rst_scalex(tile: Column): Column, rst_scaley(tile: Column): Column — Scale (pixel size) in X/Y.

SQL:

SELECT
    path,
    gbx_rst_scalex(tile) as scale_x,
    gbx_rst_scaley(tile) as scale_y
FROM rasters;

Example output
+----+--------+-------+
|path|scale_x|scale_y |
+----+--------+-------+
|... |30.0   |-30.0   |
+----+--------+-------+

rst_skewx / rst_skewy

Signature: rst_skewx(tile: Column): Column, rst_skewy(tile: Column): Column — Skew in X/Y.

SQL:

SELECT
    path,
    gbx_rst_skewx(tile) as skew_x,
    gbx_rst_skewy(tile) as skew_y
FROM rasters;

Example output
+----+-------+------+
|path|skew_x|skew_y |
+----+-------+------+
|... |0.0   |0.0    |
+----+-------+------+

rst_srid

Signature: rst_srid(tile: Column): Column — Spatial reference ID (e.g. EPSG).

SQL:

SELECT gbx_rst_srid(tile) as srid FROM rasters;

Example output
+-----+
|srid |
+-----+
|32618|
+-----+

rst_subdatasets

Signature: rst_subdatasets(tile: Column): Column — List of subdataset names.

SQL:

SELECT path, gbx_rst_subdatasets(tile) as subdatasets FROM netcdf_rasters;

Example output
+----+--------------------+
|path|subdatasets         |
+----+--------------------+
|... |[temp, precip, ...] |
+----+--------------------+

rst_summary

Signature: rst_summary(tile: Column): Column — Statistical summary of values.

SQL:

SELECT path, gbx_rst_summary(tile) as summary FROM rasters;

Example output
+----+--------+
|path|summary |
+----+--------+
|... |{...}   |
+----+--------+

rst_type

Signature: rst_type(tile: Column): Column — Data type per band.

SQL:

-- Get data types
SELECT
    path,
    gbx_rst_type(tile) as band_types,
    gbx_rst_type(tile)[0] as band1_type
FROM rasters;

-- Group by data type
SELECT
    gbx_rst_type(tile)[0] as data_type,
    COUNT(*) as count
FROM rasters
GROUP BY gbx_rst_type(tile)[0];

Example output
+----+----------+----------+
|path|band_types|band1_type|
+----+----------+----------+
|... |[Byte]    |Byte      |
+----+----------+----------+

rst_upperleftx / rst_upperlefty

Signature: rst_upperleftx(tile: Column): Column, rst_upperlefty(tile: Column): Column — Upper-left corner coordinates.

SQL:

SELECT
    path,
    gbx_rst_upperleftx(tile) as upper_left_x,
    gbx_rst_upperlefty(tile) as upper_left_y
FROM rasters;

Example output
+----+-------------+-------------+
|path|upper_left_x |upper_left_y |
+----+-------------+-------------+
|... |500000.0     |200000.0     |
+----+-------------+-------------+

rst_width

Signature: rst_width(tile: Column): Column — Width in pixels.

SQL:

SELECT gbx_rst_width(tile) as width FROM rasters;

Example output
+-----+
|width|
+-----+
|10980|
+-----+

Aggregator Functions

Combine or merge rasters in group-by (3 total).

rst_combineavg_agg

Signature: rst_combineavg_agg(tile: Column): Column — Average tiles per group.

SQL:

-- Group by region and average
SELECT
    region,
    gbx_rst_combineavg_agg(tile) as regional_average
FROM rasters
GROUP BY region;

Example output
+------+--------------------+
|region|regional_average    |
+------+--------------------+
|...   |[BINARY]            |
+------+--------------------+

rst_derivedband_agg

Signature: rst_derivedband_agg(tile: Column, pyfunc: String, funcName: String): Column — Apply Python UDF to tiles per group.

SQL:

SELECT region, gbx_rst_derivedband_agg(tile, 'def f(a): return a', 'f') as result FROM rasters GROUP BY region;

Example output
+------+--------------------+
|region|result              |
+------+--------------------+
|...   |[BINARY]            |
+------+--------------------+

rst_merge_agg

Signature: rst_merge_agg(tile: Column): Column — Merge tiles per group.

SQL:

SELECT
    scene_id,
    gbx_rst_merge_agg(tile) as merged_scene
FROM satellite_tiles
GROUP BY scene_id;

Example output
+--------+--------------------+
|scene_id|merged_scene        |
+--------+--------------------+
|S2A_001 |[BINARY]            |
+--------+--------------------+

Constructor Functions

Create or load rasters from path, binary content, or bands (3 total).

rst_fromfile

Load a raster from a file path.

Signature: rst_fromfile(path: Column, driver: Column): Column

Parameters: path — File path; driver — GDAL driver name (e.g. GTiff)

Returns: Binary raster tile data

SQL:

-- Load from path
SELECT 
    gbx_rst_fromfile('/data/raster.tif', 'GTiff') as tile;

-- Load multiple and get properties
SELECT 
    path,
    gbx_rst_width(gbx_rst_fromfile(path, 'GTiff')) as width,
    gbx_rst_height(gbx_rst_fromfile(path, 'GTiff')) as height
FROM raster_paths;

Example output
+--------------------+
|tile                |
+--------------------+
|[BINARY]            |
+--------------------+

+----+-----+------+
|path|width|height|
+----+-----+------+
|... |10980|10980 |
+----+-----+------+

rst_fromcontent

Create a raster from binary content.

Signature: rst_fromcontent(content: Column, driver: Column): Column

Parameters: content — Binary column; driver — GDAL driver name

Returns: Binary raster tile data

SQL:

-- Load from binary table
SELECT 
    path,
    gbx_rst_fromcontent(content, 'GTiff') as tile
FROM binary_raster_table;

Example output
+----+--------------------+
|path|tile                |
+----+--------------------+
|... |[BINARY]            |
+----+--------------------+

rst_frombands

Create a raster from an array of band tiles.

Signature: rst_frombands(bands: Column): Column

SQL:

SELECT
    gbx_rst_frombands(array(band1, band2, band3)) as multi_band
FROM separated_bands;

Example output
+--------------------+
|multi_band          |
+--------------------+
|[BINARY]            |
+--------------------+

Generator Functions

Produce multiple tiles or bands (5 total).

rst_h3_tessellate

Signature: rst_h3_tessellate(tile: Column, resolution: Column): Column — Tessellate raster to H3 cells.

SQL:

-- Tessellate and explode H3 cells
SELECT
    path,
    h3_tile.cellid as h3_cell,
    h3_tile as tile,
    gbx_rst_avg(h3_tile) as avg_value
FROM rasters
LATERAL VIEW explode(gbx_rst_h3_tessellate(tile, 7)) AS h3_tile;

-- Count cells per raster
SELECT
    path,
    SIZE(gbx_rst_h3_tessellate(tile, 7)) as num_cells
FROM rasters;

Example output
+----+--------+--------------------+---------+
|path|h3_cell |tile                |avg_value|
+----+--------+--------------------+---------+
|... |8f283...|[BINARY]            |0.42     |
+----+--------+--------------------+---------+

+----+---------+
|path|num_cells|
+----+---------+
|... |12       |
+----+---------+

rst_maketiles

Signature: rst_maketiles(tile: Column, tileWidth: Column, tileHeight: Column): Column — Subdivide into smaller tiles.

SQL:

-- Subdivide and explode tiles
SELECT
    path,
    tile_subtile as tile
FROM rasters
LATERAL VIEW explode(gbx_rst_maketiles(tile, 512, 512)) AS tile_subtile;

-- Count tiles per raster
SELECT
    path,
    SIZE(gbx_rst_maketiles(tile, 512, 512)) as num_tiles
FROM rasters;

Example output
+----+--------------------+
|path|tile                |
+----+--------------------+
|... |[BINARY]            |
+----+--------------------+

+----+---------+
|path|num_tiles|
+----+---------+
|... |42       |
+----+---------+

rst_retile

Signature: rst_retile(tile: Column, tileWidth: Column, tileHeight: Column): Column — Retile to uniform dimensions.

SQL:

SELECT
    path,
    tile
FROM rasters
LATERAL VIEW explode(gbx_rst_retile(tile, 256, 256)) AS tile;

Example output
+----+--------------------+
|path|tile                |
+----+--------------------+
|... |[BINARY]            |
+----+--------------------+

rst_separatebands

Signature: rst_separatebands(tile: Column): Column — Split multi-band into array of bands.

SQL:

SELECT
    path,
    bands[0] as red_band,
    bands[1] as green_band,
    bands[2] as blue_band
FROM (
    SELECT path, gbx_rst_separatebands(tile) as bands
    FROM rgb_rasters
);

Example output
+----+--------------------+--------------------+--------------------+
|path|red_band            |green_band          |blue_band           |
+----+--------------------+--------------------+--------------------+
|... |[BINARY]            |[BINARY]            |[BINARY]            |
+----+--------------------+--------------------+--------------------+

rst_tooverlappingtiles

Signature: rst_tooverlappingtiles(tile: Column, tileWidth: Column, tileHeight: Column, overlap: Column): Column — Create overlapping tiles.

SQL:

SELECT
    path,
    tile
FROM rasters
LATERAL VIEW explode(gbx_rst_tooverlappingtiles(tile, 256, 256, 10)) AS tile;

Example output
+----+--------------------+
|path|tile                |
+----+--------------------+
|... |[BINARY]            |
+----+--------------------+

Grid Functions (H3)

Aggregate raster values to H3 grid cells (5 total).

rst_h3_rastertogridavg

Signature: rst_h3_rastertogridavg(tile: Column, resolution: Column): Column

SQL:

-- Aggregate raster to H3 grid
SELECT 
    path,
    gbx_rst_h3_rastertogridavg(tile, 6) as h3_grid
FROM rasters;

-- Get cells from first band
SELECT 
    path,
    cell.cellID as h3_cell,
    cell.measure as avg_value
FROM rasters
LATERAL VIEW explode(gbx_rst_h3_rastertogridavg(tile, 6)[0]) AS cell;

Example output
+----+--------------------+
|path|h3_grid             |
+----+--------------------+
|... |[STRUCT...]         |
+----+--------------------+

+----+--------+---------+
|path|h3_cell |avg_value|
+----+--------+---------+
|... |8f283...|0.45     |
+----+--------+---------+

rst_h3_rastertogridcount

Signature: rst_h3_rastertogridcount(tile: Column, resolution: Column): Column — Pixel count per H3 cell.

SQL:

SELECT
    gbx_rst_h3_rastertogridcount(tile, 5) as pixel_counts
FROM rasters;

Example output
+--------------------+
|pixel_counts        |
+--------------------+
|[STRUCT...]         |
+--------------------+

rst_h3_rastertogridmax

Signature: rst_h3_rastertogridmax(tile: Column, resolution: Column): Column — Max value per H3 cell.

SQL:

SELECT
    cell.cellID as h3_cell,
    cell.measure as max_value
FROM rasters
LATERAL VIEW explode(gbx_rst_h3_rastertogridmax(tile, 7)[0]) AS cell;

Example output
+--------+---------+
|h3_cell |max_value|
+--------+---------+
|8f283...|255.0    |
+--------+---------+

rst_h3_rastertogridmin

Signature: rst_h3_rastertogridmin(tile: Column, resolution: Column): Column — Min value per H3 cell.

SQL:

SELECT
    cell.cellID as h3_cell,
    cell.measure as min_value
FROM rasters
LATERAL VIEW explode(gbx_rst_h3_rastertogridmin(tile, 7)[0]) AS cell;

Example output
+--------+---------+
|h3_cell |min_value|
+--------+---------+
|8f283...|0.0      |
+--------+---------+

rst_h3_rastertogridmedian

Signature: rst_h3_rastertogridmedian(tile: Column, resolution: Column): Column — Median value per H3 cell.

SQL:

SELECT
    cell.cellID as h3_cell,
    cell.measure as median_value
FROM rasters
LATERAL VIEW explode(gbx_rst_h3_rastertogridmedian(tile, 7)[0]) AS cell;

Example output
+--------+------------+
|h3_cell |median_value|
+--------+------------+
|8f283...|128.0       |
+--------+------------+

Operations

Transform and analyze rasters (20 total).

rst_asformat

Signature: rst_asformat(tile: Column, newFormat: Column): Column — Convert to another format.

SQL:

-- Convert NetCDF to GeoTIFF
SELECT
    path,
    gbx_rst_asformat(tile, 'GTiff') as geotiff_tile
FROM netcdf_rasters;

-- Convert to PNG
SELECT
    path,
    gbx_rst_asformat(tile, 'PNG') as png_tile
FROM visualization_tiles;

Example output
+----+--------------------+
|path|geotiff_tile        |
+----+--------------------+
|... |[BINARY]            |
+----+--------------------+

rst_clip

Signature: rst_clip(tile: Column, clip: Column, cutlineAllTouched: Column): Column — Clip by geometry. The clip argument must be WKT (string) or WKB (binary); do not use st_geomfromtext() or other DBR native geometry.

SQL:

-- Clip with WKT geometry
SELECT
    path,
    gbx_rst_clip(
        tile,
        'POLYGON((-122 37, -122 38, -121 38, -121 37, -122 37))',
        true
    ) as clipped
FROM rasters;

Example output
+----+--------------------+
|path|clipped             |
+----+--------------------+
|... |[BINARY]            |
+----+--------------------+

rst_combineavg

Signature: rst_combineavg(tiles: Column): Column — Average multiple tiles (e.g. temporal composite).

SQL:

-- Average rasters for temporal composite
WITH loaded_tiles AS (
  SELECT 
    date_trunc('week', date) as week,
    gbx_rst_fromfile(path, 'GTiff') as tile
  FROM daily_rasters
  WHERE date >= '2024-01-01'
)
SELECT 
    week,
    gbx_rst_combineavg(collect_list(tile)) as weekly_composite
FROM loaded_tiles
GROUP BY week;

Example output
+-------------------+--------------------+
|week               |weekly_composite    |
+-------------------+--------------------+
|2024-01-01 00:00:00|[BINARY]            |
+-------------------+--------------------+

rst_convolve

Signature: rst_convolve(tile: Column, kernel: Column): Column — Apply convolution kernel.

SQL:

-- Apply 3x3 kernel (e.g. blur); kernel format is driver-specific
SELECT path, gbx_rst_convolve(tile, kernel) as filtered FROM rasters_with_kernels;

Example output
+----+--------------------+
|path|filtered            |
+----+--------------------+
|... |[BINARY]            |
+----+--------------------+

rst_derivedband

Signature: rst_derivedband(tile: Column, pyfunc: String, funcName: String): Column — Apply Python UDF to derive band.

SQL:

-- Apply custom Python function to raster band; requires registered UDF
SELECT path, gbx_rst_derivedband(tile, 'def my_func(arr): return arr * 2', 'my_func') as derived FROM rasters;

Example output
+----+--------------------+
|path|derived             |
+----+--------------------+
|... |[BINARY]            |
+----+--------------------+

rst_filter

Signature: rst_filter(tile: Column, kernelSize: Column, operation: Column): Column — Spatial filter (e.g. median, avg).

SQL:

-- Median filter (3x3 window)
SELECT
    path,
    gbx_rst_filter(tile, 3, 'median') as denoised
FROM noisy_rasters;

-- Average smoothing (5x5 window)
SELECT
    path,
    gbx_rst_filter(tile, 5, 'avg') as smoothed
FROM rasters;

Example output
+----+--------------------+
|path|denoised            |
+----+--------------------+
|... |[BINARY]            |
+----+--------------------+

rst_initnodata

Signature: rst_initnodata(tile: Column): Column — Initialize NoData values.

SQL:

SELECT gbx_rst_initnodata(tile) as tile FROM rasters;

Example output
+--------------------+
|tile                |
+--------------------+
|[BINARY]            |
+--------------------+

rst_isempty

Signature: rst_isempty(tile: Column): Column — Check if raster is empty.

SQL:

-- Filter out empty rasters
SELECT * FROM rasters
WHERE NOT gbx_rst_isempty(tile);

-- Count empty vs valid
SELECT
    COUNT(*) as total,
    SUM(CASE WHEN gbx_rst_isempty(tile) THEN 1 ELSE 0 END) as empty_count,
    SUM(CASE WHEN NOT gbx_rst_isempty(tile) THEN 1 ELSE 0 END) as valid_count
FROM rasters;

Example output
+-----+-----------+------------+
|total|empty_count|valid_count |
+-----+-----------+------------+
|100  |0          |100         |
+-----+-----------+------------+

rst_mapalgebra

Signature: rst_mapalgebra(tiles: Column, expression: Column): Column — Map algebra expression (e.g. A-B).

SQL:

-- Calculate difference between two rasters
SELECT
    gbx_rst_mapalgebra(
        tiles,
        '{"calc": "A-B", "A_index": 0, "B_index": 1}'
    ) as difference
FROM raster_arrays;

Example output
+--------------------+
|difference          |
+--------------------+
|[BINARY]            |
+--------------------+

rst_merge

Signature: rst_merge(tiles: Column): Column — Merge tiles into mosaic.

SQL:

-- Merge rasters from a table
WITH loaded_tiles AS (
  SELECT 
    id,
    gbx_rst_fromfile(path, 'GTiff') as tile
  FROM raster_paths
)
SELECT gbx_rst_merge(collect_list(tile)) as merged_mosaic
FROM loaded_tiles;

Example output
+--------------------+
|merged_mosaic       |
+--------------------+
|[BINARY]            |
+--------------------+

rst_ndvi

Signature: rst_ndvi(tile: Column, redBand: Column, nirBand: Column): Column — NDVI from band indices.

SQL:

-- Calculate NDVI for Sentinel-2 imagery
SELECT
    path,
    date,
    gbx_rst_ndvi(tile, 4, 8) as ndvi_tile,
    gbx_rst_avg(gbx_rst_ndvi(tile, 4, 8))[0] as mean_ndvi
FROM sentinel2_images;

-- Monthly vegetation trends
SELECT
    date_trunc('month', date) as month,
    AVG(gbx_rst_avg(gbx_rst_ndvi(tile, 4, 8))[0]) as avg_monthly_ndvi
FROM sentinel2_images
GROUP BY date_trunc('month', date)
ORDER BY month;

Example output
+----+----------+--------------------+---------+
|path|date      |ndvi_tile           |mean_ndvi|
+----+----------+--------------------+---------+
|... |2024-01-15|[BINARY]            |0.42     |
+----+----------+--------------------+---------+

rst_rastertoworldcoord / rst_rastertoworldcoordx / rst_rastertoworldcoordy

Signature: rst_rastertoworldcoord(tile: Column, pixelX: Column, pixelY: Column): Column (and X/Y variants) — Pixel to world coordinates.

SQL:

SELECT
    path,
    gbx_rst_rastertoworldcoord(tile, 100, 200) as coords,
    gbx_rst_rastertoworldcoord(tile, 100, 200).x as longitude,
    gbx_rst_rastertoworldcoord(tile, 100, 200).y as latitude
FROM rasters;

Example output
+----+--------+---------+--------+
|path|coords  |longitude|latitude|
+----+--------+---------+--------+
|... |POINT(...)|-74.0  |40.5    |
+----+--------+---------+--------+

rst_transform

Signature: rst_transform(tile: Column, targetSrid: Column): Column — Reproject to target CRS.

SQL:

-- Reproject to WGS84
SELECT
    path,
    gbx_rst_transform(tile, 4326) as wgs84_tile,
    gbx_rst_srid(gbx_rst_transform(tile, 4326)) as new_srid
FROM rasters;

-- Reproject and clip
SELECT
    path,
    gbx_rst_clip(gbx_rst_transform(tile, 4326), boundary, true) as result
FROM rasters;

Example output
+----+--------------------+--------+
|path|wgs84_tile          |new_srid|
+----+--------------------+--------+
|... |[BINARY]            |4326    |
+----+--------------------+--------+

rst_tryopen

Signature: rst_tryopen(tile: Column): Column — Validate raster can be opened.

SQL:

-- Filter valid rasters
SELECT * FROM rasters
WHERE gbx_rst_tryopen(tile) = true;

-- Identify corrupt rasters
SELECT path
FROM rasters
WHERE gbx_rst_tryopen(tile) = false;

-- Validation summary
SELECT
    COUNT(*) as total,
    SUM(CASE WHEN gbx_rst_tryopen(tile) THEN 1 ELSE 0 END) as valid,
    SUM(CASE WHEN NOT gbx_rst_tryopen(tile) THEN 1 ELSE 0 END) as invalid
FROM rasters;

Example output
+-----+-----+--------+
|total|valid|invalid |
+-----+-----+--------+
|100  |98   |2       |
+-----+-----+--------+

rst_updatetype

Signature: rst_updatetype(tile: Column, newType: Column): Column — Convert raster data type.

SQL:

SELECT gbx_rst_updatetype(tile, 'Float32') as float_tile FROM rasters;

Example output
+--------------------+
|float_tile          |
+--------------------+
|[BINARY]            |
+--------------------+

rst_worldtorastercoord / rst_worldtorastercoordx / rst_worldtorastercoordy

Signature: rst_worldtorastercoord(tile: Column, worldX: Column, worldY: Column): Column (and X/Y variants) — World to pixel coordinates.

rst_worldtorastercoord — full struct (pixel with .x and .y):

-- Find pixel coordinates for a specific location
SELECT
    path,
    gbx_rst_worldtorastercoord(tile, -122.4194, 37.7749) as pixel,
    gbx_rst_worldtorastercoord(tile, -122.4194, 37.7749).x as col,
    gbx_rst_worldtorastercoord(tile, -122.4194, 37.7749).y as row
FROM rasters;

Example output
+----+-----+---+---+
|path|pixel|col|row|
+----+-----+---+---+
|... |...  |100|200|
+----+-----+---+---+

rst_worldtorastercoord — multiple points (e.g. from a locations table):

-- Sample raster at multiple points
WITH locations AS (
    SELECT -122.4194 as lon, 37.7749 as lat UNION ALL
    SELECT -122.4183, 37.7745
)
SELECT
    l.lat,
    l.lon,
    gbx_rst_worldtorastercoord(r.tile, l.lon, l.lat) as pixel
FROM rasters r, locations l;

Example output
+--------+---------+-----+
|lat     |lon      |pixel|
+--------+---------+-----+
|37.7749 |-122.4194|...  |
|37.7745 |-122.4183|...  |
+--------+---------+-----+

rst_worldtorastercoordx — pixel column only:

SELECT
    gbx_rst_worldtorastercoordx(tile, -122.4194, 37.7749) as pixel_col
FROM rasters;

Example output
+---------+
|pixel_col|
+---------+
|100      |
+---------+

rst_worldtorastercoordy — pixel row only:

SELECT
    gbx_rst_worldtorastercoordy(tile, -122.4194, 37.7749) as pixel_row
FROM rasters;

Example output
+----------+
|pixel_row |
+----------+
|200       |
+----------+

Overview​

Common setup​

Accessor Functions​

rst_avg​

rst_bandmetadata​

rst_boundingbox​

rst_format​

rst_georeference​

rst_getnodata​

rst_getsubdataset​

rst_height​

rst_max​

rst_median​

rst_memsize​

rst_metadata​

rst_min​

rst_numbands​

rst_pixelcount​

rst_pixelheight​

rst_pixelwidth​

rst_rotation​

rst_scalex / rst_scaley​

rst_skewx / rst_skewy​

rst_srid​

rst_subdatasets​

rst_summary​

rst_type​

rst_upperleftx / rst_upperlefty​

rst_width​

Aggregator Functions​

rst_combineavg_agg​

rst_derivedband_agg​

rst_merge_agg​

Constructor Functions​

rst_fromfile​

rst_fromcontent​

rst_frombands​

Generator Functions​

rst_h3_tessellate​

rst_maketiles​

rst_retile​

rst_separatebands​

rst_tooverlappingtiles​

Grid Functions (H3)​

rst_h3_rastertogridavg​

rst_h3_rastertogridcount​

rst_h3_rastertogridmax​

rst_h3_rastertogridmin​

rst_h3_rastertogridmedian​

Operations​

rst_asformat​

rst_clip​

rst_combineavg​

rst_convolve​

rst_derivedband​

rst_filter​

rst_initnodata​

rst_isempty​

rst_mapalgebra​

rst_merge​

rst_ndvi​

rst_rastertoworldcoord / rst_rastertoworldcoordx / rst_rastertoworldcoordy​

rst_transform​

rst_tryopen​

rst_updatetype​

rst_worldtorastercoord / rst_worldtorastercoordx / rst_worldtorastercoordy​

Next Steps​

Overview

Common setup

Accessor Functions

rst_avg

rst_bandmetadata

rst_boundingbox

rst_format

rst_georeference

rst_getnodata

rst_getsubdataset

rst_height

rst_max

rst_median

rst_memsize

rst_metadata

rst_min

rst_numbands

rst_pixelcount

rst_pixelheight

rst_pixelwidth

rst_rotation

rst_scalex / rst_scaley

rst_skewx / rst_skewy

rst_srid

rst_subdatasets

rst_summary

rst_type

rst_upperleftx / rst_upperlefty

rst_width

Aggregator Functions

rst_combineavg_agg

rst_derivedband_agg

rst_merge_agg

Constructor Functions

rst_fromfile

rst_fromcontent

rst_frombands

Generator Functions

rst_h3_tessellate

rst_maketiles

rst_retile

rst_separatebands

rst_tooverlappingtiles

Grid Functions (H3)

rst_h3_rastertogridavg

rst_h3_rastertogridcount

rst_h3_rastertogridmax

rst_h3_rastertogridmin

rst_h3_rastertogridmedian

Operations

rst_asformat

rst_clip

rst_combineavg

rst_convolve

rst_derivedband

rst_filter

rst_initnodata

rst_isempty

rst_mapalgebra

rst_merge

rst_ndvi

rst_rastertoworldcoord / rst_rastertoworldcoordx / rst_rastertoworldcoordy

rst_transform

rst_tryopen

rst_updatetype

rst_worldtorastercoord / rst_worldtorastercoordx / rst_worldtorastercoordy

Next Steps