---
# Licensed to the Apache Software Foundation (ASF) under one
# or more contributor license agreements.  See the NOTICE file
# distributed with this work for additional information
# regarding copyright ownership.  The ASF licenses this file
# to you under the Apache License, Version 2.0 (the
# "License"); you may not use this file except in compliance
# with the License.  You may obtain a copy of the License at
#
#   http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing,
# software distributed under the License is distributed on an
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
# KIND, either express or implied.  See the License for the
# specific language governing permissions and limitations
# under the License.

title: RS_ZonalStatsAll
description: >
  Computes every summary statistic of the raster pixels covered by a region of interest
  geometry and returns them as a struct.
kernels:
  - returns: struct
    args:
    - raster
    - {name: roi, type: geometry}
  - returns: struct
    args:
    - raster
    - {name: roi, type: geometry}
    - {name: band, type: integer}
  - returns: struct
    args:
    - raster
    - {name: roi, type: geometry}
    - {name: band, type: integer}
    - {name: all_touched, type: boolean}
  - returns: struct
    args:
    - raster
    - {name: roi, type: geometry}
    - {name: band, type: integer}
    - {name: all_touched, type: boolean}
    - {name: exclude_no_data, type: boolean}
  - returns: struct
    args:
    - raster
    - name: roi
      type: geometry
      description: >
        Region-of-interest geometry. Reprojected into the
        raster's CRS when both carry one; it is an error for exactly one side to
        have a CRS.
    - name: band
      type: integer
      description: >
        1-based band index to compute over. Required for a multiband raster; a
        single-band raster may omit it via the band-less overload.
    - name: all_touched
      type: boolean
      description: >
        If true, include every pixel the roi touches; otherwise only pixels
        whose center falls inside it. Defaults to false.
    - name: exclude_no_data
      type: boolean
      description: >
        If true (the default), skip pixels equal to the band's nodata value.
    - name: lenient
      type: boolean
      description: >
        If true (the default), return NULL when the roi does not intersect the
        raster; if false, raise an error.
---

::: callout-warning
**Experimental.** This function is experimental; its behavior may change without notice.
:::

## Description

`RS_ZonalStatsAll` returns every summary statistic of the pixels of a single
band that a roi geometry covers, as a struct with fields `count`, `sum`,
`mean`, `median`, `mode`, `stddev`, `variance`, `min`, and `max`. A pixel is
included when its
center falls inside the roi (or, with `all_touched`, when the roi touches it
at all), and the band's nodata pixels are excluded by default.

`count` is a whole number (a 64-bit integer); every other field is floating
point. Variance and standard deviation are the sample (n-1) values, and `mode`
breaks ties toward the larger value.

When the roi overlaps the raster but selects no pixel, `count` is 0 and every
other field is NULL. When the roi does not intersect the raster at all, the
whole struct is NULL under the default `lenient` behavior, or the call raises an
error when `lenient` is set to false.

The overloads are the same ladder as `RS_ZonalStats` without `stat_type`. The
`band`, `all_touched`, `exclude_no_data`, and `lenient` arguments are added one
at a time by the wider overloads; `all_touched` defaults to false,
`exclude_no_data` to true, and `lenient` to true. The band-less overload does
not default to band 1 on a multiband raster: naming the band is required there.
This function operates on 2-D `(y, x)` bands; computing statistics per
non-spatial plane of an N-D band is not supported.

Use [`RS_ZonalStats`](rs_zonalstats.qmd) to compute a single statistic.

## Examples

```sql
SELECT RS_ZonalStatsAll(
  RS_Example(),
  ST_GeomFromText('POLYGON ((60 90, 160 90, 160 190, 60 190, 60 90))', 'OGC:CRS84'),
  1
);
```