GDALBackendEntrypoint

GDALBackendEntrypoint()

xarray backend for reading geospatial files via GDAL.

Methods

Name	Description
guess_can_open	Conservative heuristic for xarray’s engine auto-discovery.
open_dataset	Open a dataset using GDAL.

guess_can_open

GDALBackendEntrypoint.guess_can_open(filename_or_obj)

Conservative heuristic for xarray’s engine auto-discovery.

open_dataset

GDALBackendEntrypoint.open_dataset(
    filename_or_obj,
    *,
    drop_variables=None,
    chunks=None,
    multidim=True,
    group=None,
    band_as_dim=True,
    config_options=None,
    mask_and_scale=None,
    decode_times=None,
    decode_timedelta=None,
    use_cftime=None,
    concat_characters=None,
    decode_coords=None,
)

Open a dataset using GDAL.

Parameters

Name	Type	Description	Default
filename_or_obj	str	Path or GDAL-recognised URI (/vsicurl/, /vsis3/, vrt://, ZARR:, NETCDF:, /vsiicechunk/...).	required
drop_variables	iterable of hashable	Variables to omit from the returned Dataset.	None
chunks	dict	Chunk sizes for Dask arrays. None (default) returns a lazy non-Dask Dataset; {} uses GDAL’s native block sizes; an explicit mapping like {"y": 256, "x": 256} is honoured (dimensions not named keep a single chunk). Chunking is delegated to Dataset.chunk so chunked arrays are created by xarray’s active chunk manager rather than by this backend (issue #31); dask is only required when chunks is not None.	None
multidim	bool	If True, use GDAL’s multidimensional API (OpenEx + OF_MULTIDIM_RASTER). If False, use the classic raster API.	True
group	str	Group path for multidim datasets (e.g. "/group/subgroup"). Leading/trailing slashes are tolerated.	None
band_as_dim	bool	Classic-raster only. If True, bands become an xarray band dimension on a single band_data DataArray (the rioxarray- compatible idiom). If False, each band becomes a separate data variable named after its description (or band_N). The True default suits multispectral imagery; False is preferable when bands carry semantically distinct quantities. Bands reporting differing nodata/scale/offset cannot be CF-decoded as one variable: values are returned raw with per-band metadata in band_nodata/band_scale_factor/band_add_offset coordinates and a warning is emitted (use band_as_dim=False to decode each band independently).	True
config_options	dict	GDAL configuration options, e.g. {"GDAL_HTTP_MAX_RETRY": "3", "GDAL_HTTP_RETRY_DELAY": "5"}. Applied thread-locally around the open and around every subsequent read, including per-thread reopens under dask (issue #34) and reads on distributed workers after unpickling, then unset again, so concurrent opens with different options do not interfere. Values are stringified. Not applied during engine auto-detection (guess_can_open).	None
mask_and_scale	bool	If True (default), apply CF mask/scale decoding: nodata becomes NaN and scale_factor/add_offset are applied, with the original values recorded in each variable’s encoding. If False, return raw values with the CF attributes left in attrs.	None