Dataset.query

def Dataset.query(
    *,
    collections: list[str] | list[UUID] | list[Collection] | list[CollectionInfo] | list[CollectionClient] | dict[str, CollectionClient] | None = None,
    temporal_extent: TimeIntervalLike,
    filter: Expression | None = None,
    spatial_extent: SpatialFilterLike | None = None,
    skip_data: bool = False,
    show_progress: bool | Callable[[float], None] = False,
) -> xarray.Dataset

Query data points across one or more collections in this dataset. If collections is not provided, all collections in the dataset are queried. If no data matches the filters, an empty xarray.Dataset is returned.

Parameters

list[...] | dict[str, CollectionClient] | None

Optional collection scope for the query.Supported values include:

A list of collection names (list[str])
A list of collection IDs (list[UUID])
A list of collection objects (list[Collection], list[CollectionInfo], list[CollectionClient])
The dictionary returned by dataset.collections()

If omitted or set to None, all collections in the dataset are queried.

TimeIntervalLike

The time or time interval to query. This can be a single time scalar, a tuple of two time scalars, or a TimeInterval object.

Expression | None

Optional expression over fields marked queryable in the dataset schema. Build expressions with field() and combine them with &, |, and ~. See Filter by custom fields.

SpatialFilterLike | None

Optional spatial filter. Use this for spatial queries in spatio-temporal datasets.

bool

If True, only required datapoint fields are returned (time, id, ingestion_time). Defaults to False.

bool | Callable[[float], None]

If True, display a progress bar when pagination is required. You can also pass a callback to receive progress values between 0 and 1. Defaults to False.

Returns

An xarray.Dataset containing matching datapoints.

Errors

A temporal_extent for your query must be specified

Raised when temporal_extent is not provided.

Collection <name> not found in dataset <dataset>

Raised when one or more collection names do not exist in the dataset.

Collection <id> is not part of the dataset <dataset>

Raised when one or more provided collection IDs/objects are not part of the dataset.

from tilebox.datasets import field

# query all collections in the dataset
data = dataset.query(
    temporal_extent=("2025-04-01", "2025-05-01"),
)

# query using custom fields marked queryable in the dataset schema
data = dataset.query(
    temporal_extent=("2026-07-20", "2026-07-28"),
    filter=(field("cloud_cover") < 1) & (field("platform") == "sentinel-2c"),
)

# query selected collections by name
data = dataset.query(
    collections=["S2A_S2MSI2A", "S2B_S2MSI2A"],
    temporal_extent=("2025-04-01", "2025-05-01"),
    show_progress=True,
)

# query selected collections by object
collections = dataset.collections()
data = dataset.query(
    collections=[collections["S2A_S2MSI2A"], collections["S2B_S2MSI2A"]],
    temporal_extent=("2025-04-01", "2025-05-01"),
    skip_data=True,
)

Python

Go

Parameters

Returns

Errors

​Parameters

​Returns

​Errors

Parameters

Returns

Errors