DuckDB Community Extensions

The duckdb/community-extensions repository is a collection of third-party extensions for DuckDB. These extensions provide additional functionality not included in the core DuckDB distribution.

To find and use these extensions:

1. Browse the list: Visit the list of Community Extensions to see what is available.
2. Learn more: Visit the DuckDB Community Extensions website for detailed information on specific extensions.
3. Understand the difference: Refer to the official vs community extensions guide to understand the distinction between core features and community-contributed ones.

A critical constraint in the Raster extension is that RT_Read and ST_Read only accept literal path values at bind time. They do not support column references or subqueries directly as arguments.

To work around this for dynamic workflows (e.g., using paths discovered via a STAC search), use SET VARIABLE and getvariable(). DuckDB resolves variables to constants before invoking the table function, allowing you to pass arrays of paths dynamically.

Community extensions are built using the C++ extension template and are tightly coupled to specific DuckDB versions because the C++ API is not stable.

There are two primary ways extensions are released:

1. Descriptor Updates: Whenever an extension descriptor (e.g., description.yml) is updated in the community extensions repository, the extension is rebuilt targeting the latest stable DuckDB version.
2. DuckDB Releases: When a new DuckDB version is released, all community extensions are automatically rebuilt to ensure availability alongside the new DuckDB release.

Note: The standard DuckDB community extension install flow does not support installing historical versions of an extension. If you need to pin a specific version, you must host the artifacts in a custom repository or provide direct URLs.

You can perform element-wise arithmetic operations on databands using standard operators (+, -, *, /) or built-in functions like RT_CubeAdd. These operations are applied to every pixel within each tile.

SELECT
    databand_1 + databand_2 AS sum_bands,
    RT_CubeAdd(databand_1, databand_2) - 1.8 AS sum_func_offset,
    databand_1 * 2 AS scaled_band
FROM
    RT_Read('./test/data/overlay-sample.tiff');

To use a DuckDB community extension, you must first install it from the community repository and then load it into your current DuckDB session using the following SQL commands. Replace {{ page.extension.name }} with the specific name of the extension you wish to use.

INSTALL {{ page.extension.name }} FROM community;
LOAD {{ page.extension.name }};

Since RT_Read output includes a geometry column for every tile, you can use the spatial extension to export these footprints to vector formats like GeoParquet or GeoPackage using COPY ... TO.

-- Export tile footprints to GeoParquet
COPY (
    SELECT id, x, y, tile_x, tile_y, cols, rows, geometry, metadata
    FROM RT_Read(['file1.tif', 'file2.tif'])
    WHERE NOT RT_CubeNullOrEmpty(databand_1)
)
TO './output.parquet'
WITH (
    FORMAT PARQUET, GEOPARQUET_VERSION 'V1'
);

-- Export tile footprints to GeoPackage
LOAD spatial;
COPY (
    SELECT id, x, y, tile_x, tile_y, cols, rows, geometry, metadata
    FROM RT_Read(['file1.tif', 'file2.tif'])
    WHERE NOT RT_CubeNullOrEmpty(databand_1)
)
TO './output.gpkg'
WITH (
    FORMAT GDAL, DRIVER 'GPKG', SRS 'EPSG:32630'
);

To perform Earth Observation analysis or complex raster workflows, you must ensure the json, spatial, and http_client extensions are loaded. The http_client extension may need to be installed from the community repository.

Run the following commands once per session:

LOAD json;
LOAD spatial;
INSTALL http_client FROM community;
LOAD http_client;

You can filter the tiles returned by RT_Read using spatial intersection tests. This requires the spatial extension.

Performance Tip: For large datasets, filter using the bbox column (which contains xmin, ymin, xmax, ymax) instead of the geometry column. Bounding-box filtering is faster because it avoids the overhead of deserializing full geometry objects.

-- Method 1: Intersection with geometry (requires spatial extension)
LOAD spatial;
SELECT x, y, bbox, geometry
FROM RT_Read('path/to/raster/file.tif')
WHERE ST_Intersects(geometry, ST_GeomFromText('POLYGON((...)))'));

-- Method 2: Fast bounding-box filtering (preferred for performance)
SELECT *
FROM RT_Read('./test/data/overlay-sample.tiff')
WHERE bbox.xmin > 545500.0 AND bbox.xmax < 545800.0
  AND bbox.ymin > 4724400.0 AND bbox.ymax < 4724600.0;

You can read remote raster files from S3 using two methods:

1. GDAL Virtual File System: Use the /vsis3/ prefix. For public buckets, you must first disable signature checking using RT_GdalConfig('AWS_NO_SIGN_REQUEST', 'YES').
2. Native DuckDB S3: Use the s3:// protocol (requires the httpfs extension for authentication).

-- Method 1: GDAL /vsis3/ (for public buckets)
SELECT RT_GdalConfig('AWS_NO_SIGN_REQUEST', 'YES');
SELECT * FROM RT_Read('/vsis3/sentinel-cogs/sentinel-s2-l2a-cogs/30/T/WN/2021/9/S2B_30TWN_20210930_0_L2A/B02.tif') LIMIT 5;

-- Method 2: Native DuckDB S3
SELECT * FROM RT_Read('s3://sentinel-cogs/sentinel-s2-l2a-cogs/30/T/WN/2021/9/S2B_30TWN_20210930_0_L2A/B02.tif') LIMIT 5;