Raster Tables

WherobotsDB stores tables in Apache Iceberg. New tables in Wherobots-managed catalogs, such as org_catalog, are format-version 3 (V3), which has geometry and geography column types, and Wherobots adds a raster column type. Tables created before September 15, 2026 were created at format-version 2 (V2), and Wherobots doesn’t raise them to V3. Which column types a table can have, and whether WherobotsDB skips data files for spatial filters, depend on its format version; see the Iceberg Tables Overview. A raster column holds in-db or out-db rasters, and the RS_ functions in WherobotsDB work on them. This page shows how to create, write, and query tables with raster columns. The examples use the catalog name org_catalog; replace it with the name of the catalog you write to.

Creating a table with a raster column

Choose the format version before you create the table. WherobotsDB skips data files for raster spatial filters only on format-version 1 and 2 tables, and a new table in a Wherobots-managed catalog is format-version 3. A table can’t be lowered from format-version 3 to 2. The two examples below create format-version 2 tables, with TBLPROPERTIES ('format-version'='2') on CREATE TABLE and .tableProperty("format-version", "2") before .create(). Leave the property off if you don’t filter the rasters spatially, or if the table needs a GEOMETRY(<srid>) or GEOGRAPHY(<srid>) column, which requires format-version 3. See Raster columns on the push-down page. Declare the column with the raster type:

Python
Scala
Java

sedona.sql("""
CREATE TABLE IF NOT EXISTS org_catalog.test_db.test_table (
    id bigint,
    data string,
    rast raster
) USING iceberg
TBLPROPERTIES ('format-version'='2')""")

sedona.sql("""
CREATE TABLE IF NOT EXISTS org_catalog.test_db.test_table (
    id bigint,
    data string,
    rast raster
) USING iceberg
TBLPROPERTIES ('format-version'='2')""")

sedona.sql(
    "CREATE TABLE IF NOT EXISTS org_catalog.test_db.test_table (" +
    "id bigint," +
    "data string," +
    "rast raster" +
    ") USING iceberg " +
    "TBLPROPERTIES ('format-version'='2')"
);

This creates an empty table with a raster column rast. Inspect the table schema with DESCRIBE TABLE:

Python
Scala
Java

sedona.sql("DESCRIBE TABLE org_catalog.test_db.test_table").show()

sedona.sql("DESCRIBE TABLE org_catalog.test_db.test_table").show()

sedona.sql("DESCRIBE TABLE org_catalog.test_db.test_table").show();

+--------+---------+-------+
|col_name|data_type|comment|
+--------+---------+-------+
|      id|   bigint|   null|
|    data|   string|   null|
|    rast|   raster|   null|
+--------+---------+-------+

Or with printSchema():

Python
Scala
Java

sedona.table("org_catalog.test_db.test_table").printSchema()

sedona.table("org_catalog.test_db.test_table").printSchema()

sedona.table("org_catalog.test_db.test_table").printSchema();

root
 |-- id: long (nullable = true)
 |-- data: string (nullable = true)
 |-- rast: raster (nullable = true)

SHOW CREATE TABLE prints a raster column as rast BINARY on a format-version 3 table. The column still holds rasters, stored the same way as on a format-version 2 table. To create a table from a DataFrame that holds rasters, call writeTo(...).create():

Python
Scala
Java

# Create a DataFrame containing raster data
df_binary = sedona.read.format("binaryFile")\
    .option("pathGlobFilter", "*.tif")\
    .option("recursiveFileLookup", "true")\
    .load('s3://wherobots-examples/data/eurosat_small')
df_geotiff = df_binary.withColumn("rast", expr("RS_FromGeoTiff(content)"))\
    .selectExpr("rast", "path AS data")

# Create a table from the DataFrame
df_geotiff.writeTo("org_catalog.test_db.test_table").tableProperty("format-version", "2").create()

// Create a DataFrame containing raster data
val df_binary = sedona.read.format("binaryFile")
    .option("pathGlobFilter", "*.tif")
    .option("recursiveFileLookup", "true")
    .load("s3://wherobots-examples/data/eurosat_small")

val df_geotiff = df_binary.withColumn("rast", expr("RS_FromGeoTiff(content)"))
    .selectExpr("rast", "path AS data")

// Create a table from the DataFrame
df_geotiff.writeTo("org_catalog.test_db.test_table").tableProperty("format-version", "2").create()

// Create a DataFrame containing raster data
Dataset<Row> df_binary = sedona.read().format("binaryFile")
    .option("pathGlobFilter", "*.tif")
    .option("recursiveFileLookup", "true")
    .load("s3://wherobots-examples/data/eurosat_small");

Dataset<Row> df_geotiff = df_binary.withColumn("rast", expr("RS_FromGeoTiff(content)"))
    .selectExpr("rast", "path AS data");

// Create a table from the DataFrame
df_geotiff.writeTo("org_catalog.test_db.test_table").tableProperty("format-version", "2").create();

Writing data

Storing raster data in a table is similar to PostGIS. There are two options for storing raster data:

in-db raster: raster data completely stored in a table.
out-db raster: raster data is stored in an external file (such as GeoTIFF file on S3) and the table stores the path to the file and geo-referencing metadata of that raster.

In-DB Raster

To construct in-db raster data and write them to a table, user can use RS_FromGeoTiff to construct a raster value and write the DataFrame using .writeTo(...).append()

Python
Scala
Java

# Read GeoTIFF files using RS_FromGeoTiff
df_binary = sedona.read.format("binaryFile")\
    .option("pathGlobFilter", "*.tif")\
    .option("recursiveFileLookup", "true")\
    .load('s3://wherobots-examples/data/eurosat_small')
df_geotiff = df_binary.withColumn("rast", expr("RS_FromGeoTiff(content)"))\
    .selectExpr("rast", "path AS data")

# Writing the data into the table
df_geotiff.writeTo("org_catalog.test_db.test_table").append()

// Read GeoTIFF files using RS_FromGeoTiff
val df_binary = sedona.read.format("binaryFile")
    .option("pathGlobFilter", "*.tif")
    .option("recursiveFileLookup", "true")
    .load("s3://wherobots-examples/data/eurosat_small")

val df_geotiff = df_binary.withColumn("rast", expr("RS_FromGeoTiff(content)"))
    .selectExpr("rast", "path AS data")

// Writing the data into the table
df_geotiff.writeTo("org_catalog.test_db.test_table").append()

// Read GeoTIFF files using RS_FromGeoTiff
Dataset<Row> df_binary = sedona.read().format("binaryFile")
    .option("pathGlobFilter", "*.tif")
    .option("recursiveFileLookup", "true")
    .load("s3://wherobots-examples/data/eurosat_small");

Dataset<Row> df_geotiff = df_binary.withColumn("rast", expr("RS_FromGeoTiff(content)"))
    .selectExpr("rast", "path AS data");

// Writing the data into the table
df_geotiff.writeTo("org_catalog.test_db.test_table").append();

Or load the GeoTIFF files with the raster data source, which reads them as out-db rasters, then use RS_AsInDB to convert them to in-db rasters. Take the path with RS_BandPath before the conversion, because an in-db raster no longer references its source file:

Python
Scala
Java

# Read GeoTIFF files as out-db rasters with the raster data source, then convert to in-db rasters using RS_AsInDB
df_rast = sedona.read.format("raster")\
    .option("retile", "false")\
    .load("s3://wherobots-examples/data/eurosat_small/AnnualCrop/*.tif")\
    .selectExpr("RS_AsInDB(rast) AS rast", "RS_BandPath(rast) AS data")

# Writing the data into the table
df_rast.writeTo("org_catalog.test_db.test_table").append()

// Read GeoTIFF files as out-db rasters with the raster data source, then convert to in-db rasters using RS_AsInDB
val df_rast = sedona.read.format("raster")
    .option("retile", "false")
    .load("s3://wherobots-examples/data/eurosat_small/AnnualCrop/*.tif")
    .selectExpr("RS_AsInDB(rast) AS rast", "RS_BandPath(rast) AS data")

// Writing the data into the table
df_rast.writeTo("org_catalog.test_db.test_table").append()

// Read GeoTIFF files as out-db rasters with the raster data source, then convert to in-db rasters using RS_AsInDB
Dataset<Row> df_rast = sedona.read().format("raster")
    .option("retile", "false")
    .load("s3://wherobots-examples/data/eurosat_small/AnnualCrop/*.tif")
    .selectExpr("RS_AsInDB(rast) AS rast", "RS_BandPath(rast) AS data");

// Writing the data into the table
df_rast.writeTo("org_catalog.test_db.test_table").append();

Out-DB Raster

To write out-db rasters to a table, load the raster files with the raster data source and write the DataFrame. Each row holds an out-db raster that references the file. The name column holds only the file name, so these examples write the full path from RS_BandPath to data. The EuroSAT sample files aren’t internally tiled, so these examples set retile to false and load each file as one raster. For tiled files such as Cloud Optimized GeoTIFFs, leave tiling on to write one row for each tile:

Python
Scala
Java

# Read GeoTIFF files as out-db rasters with the raster data source
df_rast = sedona.read.format("raster")\
    .option("retile", "false")\
    .load("s3://wherobots-examples/data/eurosat_small/AnnualCrop/*.tif")\
    .selectExpr("rast", "RS_BandPath(rast) AS data")

# Writing the data into the table
df_rast.writeTo("org_catalog.test_db.test_table").append()

// Read GeoTIFF files as out-db rasters with the raster data source
val df_rast = sedona.read.format("raster")
    .option("retile", "false")
    .load("s3://wherobots-examples/data/eurosat_small/AnnualCrop/*.tif")
    .selectExpr("rast", "RS_BandPath(rast) AS data")

// Writing the data into the table
df_rast.writeTo("org_catalog.test_db.test_table").append()

// Read GeoTIFF files as out-db rasters with the raster data source
Dataset<Row> df_rast = sedona.read().format("raster")
    .option("retile", "false")
    .load("s3://wherobots-examples/data/eurosat_small/AnnualCrop/*.tif")
    .selectExpr("rast", "RS_BandPath(rast) AS data");

// Writing the data into the table
df_rast.writeTo("org_catalog.test_db.test_table").append();

Updating, deleting, and merging data

UPDATE, DELETE, and MERGE INTO work on raster tables, in both copy-on-write and merge-on-read mode. The syntax is the same as in Apache Iceberg; see Apache Iceberg - Write with SQL.

Querying data

Load a table into a DataFrame with sedona.table(...):

Python
Scala
Java

df = sedona.table("org_catalog.test_db.test_table")

val df = sedona.table("org_catalog.test_db.test_table")

Dataset<Row> df = sedona.table("org_catalog.test_db.test_table");

You can set read options when you load the table. For example, with a smaller split size, the table is read into more partitions:

Python
Scala
Java

df = sedona.read.option('split-size', '1000').table("org_catalog.test_db.test_table")

val df = sedona.read.option("split-size", "1000").table("org_catalog.test_db.test_table")

Dataset<Row> df = sedona.read().option("split-size", "1000").table("org_catalog.test_db.test_table");

Run a spatial range query with Spatial SQL:

Python
Scala
Java

df = sedona.sql("""
SELECT * FROM org_catalog.test_db.test_table
WHERE RS_Intersects(rast, ST_GeomFromText('POLYGON ((0 0, 0 2, 2 2, 2 0, 0 0))'))
""")

val df = sedona.sql("""
SELECT * FROM org_catalog.test_db.test_table
WHERE RS_Intersects(rast, ST_GeomFromText('POLYGON ((0 0, 0 2, 2 2, 2 0, 0 0))'))
""")

Dataset<Row> df = sedona.sql(
        "SELECT * FROM org_catalog.test_db.test_table " +
        "WHERE RS_Intersects(rast, ST_GeomFromText('POLYGON ((0 0, 0 2, 2 2, 2 0, 0 0))'))"
);

Or with the DataFrame API:

Python
Scala
Java

df = sedona.table("org_catalog.test_db.test_table")\
    .where("RS_Intersects(rast, ST_GeomFromText('POLYGON ((0 0, 0 2, 2 2, 2 0, 0 0))'))")

val df = sedona.table("org_catalog.test_db.test_table")
    .where("RS_Intersects(rast, ST_GeomFromText('POLYGON ((0 0, 0 2, 2 2, 2 0, 0 0))'))")

Dataset<Row> df = sedona.table("org_catalog.test_db.test_table")
    .where("RS_Intersects(rast, ST_GeomFromText('POLYGON ((0 0, 0 2, 2 2, 2 0, 0 0))'))");

You can also load a table by naming the data source with .format("iceberg"). This loads an isolated table reference, which doesn’t refresh automatically when the table changes:

Python
Scala
Java

df = sedona.read.format("iceberg").load("org_catalog.test_db.test_table")

val df = sedona.read.format("iceberg").load("org_catalog.test_db.test_table")

Dataset<Row> df = sedona.read().format("iceberg").load("org_catalog.test_db.test_table");

On format-version 1 and 2 tables, WherobotsDB skips the data files whose rasters can’t match a raster spatial filter. See Raster columns on the push-down page.

Working with raster data

A raster column is read as RasterUDT values, which every RS_ function in WherobotsDB works on. For example, RS_MapAlgebra creates a new raster by applying a map algebra expression to each raster:

Python
Scala
Java

sedona.sql("SELECT RS_MapAlgebra(rast, NULL, 'out = rast[0] * 0.5;') FROM org_catalog.test_db.test_table").show()

sedona.sql("SELECT RS_MapAlgebra(rast, NULL, 'out = rast[0] * 0.5;') FROM org_catalog.test_db.test_table").show()

sedona.sql("SELECT RS_MapAlgebra(rast, NULL, 'out = rast[0] * 0.5;') FROM org_catalog.test_db.test_table").show();

To write the result to a new table, use CREATE TABLE ... AS SELECT:

Python
Scala
Java

sedona.sql("""
CREATE TABLE org_catalog.test_db.test_table_mapalg AS
SELECT RS_MapAlgebra(rast, NULL, 'out = rast[0] * 0.5;') AS rast FROM org_catalog.test_db.test_table
""")

sedona.sql("""
CREATE TABLE org_catalog.test_db.test_table_mapalg AS
SELECT RS_MapAlgebra(rast, NULL, 'out = rast[0] * 0.5;') AS rast FROM org_catalog.test_db.test_table
""")

sedona.sql(
        "CREATE TABLE org_catalog.test_db.test_table_mapalg AS " +
        "SELECT RS_MapAlgebra(rast, NULL, 'out = rast[0] * 0.5;') AS rast FROM org_catalog.test_db.test_table"
);

Or call writeTo(...).create() on the DataFrame the query returns:

Python
Scala
Java

sedona.sql("SELECT RS_MapAlgebra(rast, NULL, 'out = rast[0] * 0.5;') AS rast FROM org_catalog.test_db.test_table")\
    .writeTo("org_catalog.test_db.test_table_mapalg").create()

sedona.sql("SELECT RS_MapAlgebra(rast, NULL, 'out = rast[0] * 0.5;') AS rast FROM org_catalog.test_db.test_table")
    .writeTo("org_catalog.test_db.test_table_mapalg").create()

sedona.sql("SELECT RS_MapAlgebra(rast, NULL, 'out = rast[0] * 0.5;') AS rast FROM org_catalog.test_db.test_table")
    .writeTo("org_catalog.test_db.test_table_mapalg").create();

Both create a format-version 3 table in a Wherobots-managed catalog. To filter the result spatially with file skipping, set the format version as described in Creating a table with a raster column.

Iceberg Tables Overview

Format versions, spatial file skipping, and format-version 3 features.

Spatial Filter Push-down and Clustering

Partition or cluster a raster table so WherobotsDB skips more data files for raster filters.

Tune Out-DB Raster Reads

When to use in-db or out-db rasters, and how to tune the out-db raster cache.

Apache Iceberg documentation for Spark

Table maintenance, procedures, and the rest of the Iceberg Spark integration.

Start here

Havasu data catalogs

Vector data

Raster data

Iceberg tables

Maps and visualization

Creating a table with a raster column

Writing data

In-DB Raster

Out-DB Raster

Updating, deleting, and merging data

Querying data

Working with raster data

Iceberg Tables Overview

Spatial Filter Push-down and Clustering

Tune Out-DB Raster Reads

Apache Iceberg documentation for Spark

​Creating a table with a raster column

​Writing data

​In-DB Raster

​Out-DB Raster

​Updating, deleting, and merging data

​Querying data

​Working with raster data

​Related pages

Iceberg Tables Overview

Spatial Filter Push-down and Clustering

Tune Out-DB Raster Reads

Apache Iceberg documentation for Spark

Creating a table with a raster column

Writing data

In-DB Raster

Out-DB Raster

Updating, deleting, and merging data

Querying data

Working with raster data

Related pages