---
warning: DO NOT CHANGE THIS MANUALLY, THIS IS GENERATED BY https://github.com/duckdb/community-extensions repository, check README there
title: cog
excerpt: |
  DuckDB Community Extensions
  GDAL-free Cloud-Optimized GeoTIFF (COG) reader — query remote rasters in place over HTTP range reads, with STAC catalog integration

extension:
  name: cog
  description: GDAL-free Cloud-Optimized GeoTIFF (COG) reader — query remote rasters in place over HTTP range reads, with STAC catalog integration
  version: 0.3.0
  language: Rust
  build: cargo
  license: MIT
  excluded_platforms: "windows_amd64_rtools;windows_amd64_mingw;linux_amd64_musl"
  requires_toolchains: "rust;python3"
  maintainers:
    - thsghdud13

repo:
  github: st-layer/duckdb-cog
  ref: 5057905a3a74b0f3343de05fe2fabcf0fc0d902b

docs:
  hello_world: |
    -- Anonymous access to public S3 buckets needs: export AWS_SKIP_SIGNATURE=true
    LOAD cog;

    -- List the tile grid of a remote Sentinel-2 COG (metadata-only range reads — never the pixels)
    SELECT level, tile_x, tile_y, bbox, crs
    FROM read_cog('https://sentinel-cogs.s3.us-west-2.amazonaws.com/sentinel-s2-l2a-cogs/52/S/CG/2026/6/S2B_52SCG_20260630_0_L2A/B04.tif')
    LIMIT 3;

    -- Sedona-style raster accessors: metadata, a pixel value, zonal statistics (native CRS coordinates)
    SELECT RS_Width(f) AS width, RS_SRID(f) AS srid,
           RS_Value(f, 325210.0, 4121100.0) AS red,
           round(RS_ZonalStats(f, [322000.0, 4119000.0, 326400.0, 4123200.0], 1, 'mean'), 1) AS zonal_mean
    FROM (SELECT 'https://sentinel-cogs.s3.us-west-2.amazonaws.com/sentinel-s2-l2a-cogs/52/S/CG/2026/6/S2B_52SCG_20260630_0_L2A/B04.tif' AS f);
    -- width = 10980, srid = 32652, red = 1748.0, zonal_mean = 1916.4

    -- Search a live STAC API (POST /search, pagination followed automatically)
    SELECT s.item_id, s.datetime
    FROM read_stac_search('https://earth-search.aws.element84.com/v1/search',
                          collections := ['sentinel-2-l2a'],
                          bbox := [127.02, 37.21, 127.04, 37.23],
                          datetime := '2026-06-28T00:00:00Z/2026-07-02T00:00:00Z') s
    WHERE s.asset_key = 'red';
  extended_description: |
    `cog` exposes Cloud-Optimized GeoTIFF rasters as SQL tables — in place, over
    HTTP/S3 range reads, with no re-encoding, no reprojection, and no
    GDAL/PROJ/GEOS anywhere in the read path (TIFF decoding and fetching are
    delegated to [async-tiff](https://github.com/developmentseed/async-tiff)).

    Surface: `read_cog()` tile-grid listing, `read_stac()` / `read_stac_search()`
    STAC catalog integration (static documents and live POST /search APIs with
    pagination), and a Sedona-style `RS_*` scalar catalog (metadata accessors,
    `RS_Value`/`RS_Values` pixel access, `RS_NormalizedDifference`,
    `RS_ZonalStats`, `RS_BandAsArray`). Every pixel-facing result is
    cross-checked against a rasterio oracle in CI. Repeated remote access is
    served by a process-wide metadata cache.

    See the [README](https://github.com/st-layer/duckdb-cog) for benchmarks and
    the full SQL surface.

extension_star_count: 5
extension_star_count_pretty: 5
extension_download_count: 813
extension_download_count_pretty: 813
image: '/images/community_extensions/social_preview/preview_community_extension_cog.png'
layout: community_extension_doc
---
### Compatibility Matrix

This table covers all DuckDB releases that have not reached [end-of-life](https://duckdb.org/release_calendar), including LTS releases, and shows the 2 most recent patch releases of each. Older patch releases are not listed, but the extension may be available for them as well.

<div class="extension_compatibility_table"></div>

| Platform | 1.4.4 | 1.4.5 | 1.5.5 | 1.5.6 | 2.0.0 |
| :--- | :---: | :---: | :---: | :---: | :---: |
| Linux AMD64 | ❌ | ❌ | ✅ | ❌ | ❌ |
| Linux ARM64 | ❌ | ❌ | ✅ | ❌ | ❌ |
| macOS AMD64 | ❌ | ❌ | ✅ | ❌ | ❌ |
| macOS ARM64 | ❌ | ❌ | ✅ | ❌ | ❌ |
| Windows AMD64 | ❌ | ❌ | ✅ | ❌ | ❌ |
| Windows ARM64 | ❌ | ❌ | ❌ | ❌ | ❌ |
| WebAssembly | ❌ | ❌ | ✅ | ❌ | ❌ |

### Installing and Loading
```sql
INSTALL {{ page.extension.name }} FROM community;
LOAD {{ page.extension.name }};
```

{% if page.docs.hello_world %}
### Example
```sql
{{ page.docs.hello_world }}```
{% endif %}

{% if page.docs.extended_description %}
### About {{ page.extension.name }}
{{ page.docs.extended_description }}
{% endif %}
### Added Functions

<div class="extension_functions_table"></div>

|      function_name      | function_type | description | comment | examples |
|-------------------------|---------------|-------------|---------|----------|
| RS_BandAsArray          | scalar        | NULL        | NULL    |          |
| RS_BandNoDataValue      | scalar        | NULL        | NULL    |          |
| RS_BandStats            | scalar        | NULL        | NULL    |          |
| RS_GeoReference         | scalar        | NULL        | NULL    |          |
| RS_Height               | scalar        | NULL        | NULL    |          |
| RS_MetaData             | scalar        | NULL        | NULL    |          |
| RS_NormalizedDifference | scalar        | NULL        | NULL    |          |
| RS_NumBands             | scalar        | NULL        | NULL    |          |
| RS_RasterToWorldCoord   | scalar        | NULL        | NULL    |          |
| RS_SRID                 | scalar        | NULL        | NULL    |          |
| RS_ScaleX               | scalar        | NULL        | NULL    |          |
| RS_ScaleY               | scalar        | NULL        | NULL    |          |
| RS_SkewX                | scalar        | NULL        | NULL    |          |
| RS_SkewY                | scalar        | NULL        | NULL    |          |
| RS_UpperLeftX           | scalar        | NULL        | NULL    |          |
| RS_UpperLeftY           | scalar        | NULL        | NULL    |          |
| RS_Value                | scalar        | NULL        | NULL    |          |
| RS_Values               | scalar        | NULL        | NULL    |          |
| RS_Width                | scalar        | NULL        | NULL    |          |
| RS_WorldToRasterCoord   | scalar        | NULL        | NULL    |          |
| RS_ZonalStats           | scalar        | NULL        | NULL    |          |
| cog_cache_stats         | table         | NULL        | NULL    |          |
| cog_io_bench            | table         | NULL        | NULL    |          |
| cog_version             | table         | NULL        | NULL    |          |
| read_cog                | table         | NULL        | NULL    |          |
| read_stac               | table         | NULL        | NULL    |          |
| read_stac_search        | table         | NULL        | NULL    |          |

### Overloaded Functions

<div class="extension_functions_table"></div>

This extension does not add any function overloads.

### Added Types

<div class="extension_types_table"></div>

This extension does not add any types.

### Added Settings

<div class="extension_settings_table"></div>

This extension does not add any settings.