# Dataset.query

```python
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

**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](/docs/datasets/query/filter-by-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`](/docs/sdks/python/xarray) 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.

```python title="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,
)
```