Skip to main content

API Reference Overview

GeoBrix provides APIs in three languages: Scala, Python, and SQL. All APIs provide access to the same underlying functionality with language-appropriate idioms.

Function References​

For detailed documentation of each function with parameters, return values, and examples:

API Languages​

Scala​

The native implementation language, providing the most direct access to GeoBrix functionality.

Scala API Documentation →

Python​

Python bindings via PySpark, providing Pythonic access to all GeoBrix features.

Python API Documentation →

SQL​

SQL functions registered in the Spark catalog, usable from any SQL context.

SQL API Documentation →

Function Naming Convention​

All GeoBrix SQL functions use the gbx_ prefix to clearly identify them as GeoBrix functions:

PackagePrefixExample
RasterXgbx_rst_gbx_rst_boundingbox
GridX/BNGgbx_bng_gbx_bng_cellarea
VectorXgbx_st_gbx_st_legacyaswkb

This makes it easy to:

  • Identify GeoBrix functions in your code
  • Distinguish from Databricks built-in st_* functions
  • Track usage and attribution

Scalar values vs lit(...) wrapping​

Previously, every non-Column argument had to be wrapped in f.lit(...) (Python) or lit(...) (Scala). That was a regression from Mosaic/DBR built-ins, where booleans and numerics can be passed as plain values. In 0.3.0, plain scalars are accepted across Python, Scala, and SQL bindings.

Python — wrappers accept Column or scalar (bool/int/float/bytes); non-string scalars are auto-wrapped with f.lit(...). Strings still follow pyspark's column-reference convention (bare string ≈ f.col(name)); wrap in f.lit("...") to pass a string literal.

# ✅ Before 0.3.0 — required f.lit for every value
rx.rst_clip("tile", "geom", f.lit(True))
rx.rst_transform("tile", f.lit(4326))
bx.bng_pointascell("pt", f.lit(1))
bx.bng_pointascell("pt", f.lit("1km"))

# ✅ 0.3.0 — scalars accepted directly
rx.rst_clip("tile", "geom", True)
rx.rst_transform("tile", 4326)
bx.bng_pointascell("pt", 1)
bx.bng_pointascell("pt", f.lit("1km"))   # string literal — still wrap in f.lit

Scala — typed overloads added for Boolean / Int / Double / String value parameters. Column args (e.g. geometry, tile) still take Column.

// ✅ 0.3.0 — scalar overloads resolve without lit(...)
rst_clip(col("tile"), col("geom"), cutlineAllTouched = true)
rst_transform(col("tile"), 4326)
bng_pointascell(col("pt"), 1)
bng_pointascell(col("pt"), "1km")

SQL — values are already natively accepted by Spark SQL; no change needed:

SELECT gbx_rst_clip(tile, geom, true) FROM ...;
SELECT gbx_bng_pointascell(pt, 1) FROM ...;
SELECT gbx_bng_pointascell(pt, '1km') FROM ...;

When you still need f.lit(...) in Python:

  • String literals: rx.rst_fromfile(f.lit("/path/to.tif"), f.lit("GTiff")) — a bare string is treated as a column reference.
  • Nulls / explicit typing: e.g. f.lit(None).cast("double").

Registration​

Before using GeoBrix functions in Python or SQL, you must register them:

Python​

from databricks.labs.gbx.rasterx import functions as rx
from databricks.labs.gbx.gridx.bng import functions as bx
from databricks.labs.gbx.vectorx.jts.legacy import functions as vx

# Register each package
rx.register(spark)
bx.register(spark)
vx.register(spark)
Example output
Registered RasterX, GridX, and VectorX functions.

Scala​

Register All Packages
import com.databricks.labs.gbx.rasterx.{functions => rx}
import com.databricks.labs.gbx.gridx.bng.{functions => bx}
import com.databricks.labs.gbx.vectorx.jts.legacy.{functions => vx}

// Register each package
rx.register(spark)
bx.register(spark)
vx.register(spark)
Example output
RasterX, GridX, and VectorX functions registered (gbx_rst_*, gbx_bng_*, gbx_st_*).

SQL​

SQL functions are registered via Python or Scala. Once registered, they're available in any SQL context:

-- No registration needed in SQL
-- Functions are available after Python/Scala registration

SHOW FUNCTIONS LIKE 'gbx_*';
Example output
+--------------------+
|function            |
+--------------------+
|gbx_rst_asformat    |
|gbx_rst_avg         |
|gbx_rst_bandmetadata|
+--------------------+

API Categories​

RasterX Functions​

Functions for raster data processing:

  • Accessors: Get raster properties (width, height, bounds, metadata)
  • Constructors: Load or create rasters
  • Transformations: Clip, reproject rasters
  • Grid Operations: Raster to grid conversions
  • Band Operations: Multi-band raster operations
  • Aggregations: Combine and merge rasters

View RasterX Functions →

GridX Functions​

Functions for grid indexing (BNG):

  • Cell Operations: Create and manipulate grid cells
  • Coordinate Conversion: Convert between coordinates and grid references
  • Grid Properties: Get grid cell attributes
  • Spatial Indexing: Use grid cells for efficient spatial operations

View GridX Functions →

VectorX Functions​

Functions for vector operations:

  • Geometry Conversion: Convert legacy formats to WKB/WKT
  • Format Transformation: Prepare data for Databricks spatial types

View VectorX Functions →

Next Steps​