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

Copy

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

collections 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.

temporal_extent 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.

filter 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.

spatial_extent SpatialFilterLike | None

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

skip_data bool

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

show_progress 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

ValueError A temporal_extent for your query must be specified

Raised when temporal_extent is not provided.

ValueError Collection <name> not found in dataset <dataset>

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

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

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

Request example

Python

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,
)

Copy