---
title: "Dataset.query"
description: "Query data points across one or more collections in this dataset."
image: "https://tilebox.com/images/tilebox-docs-social-preview.png"
---

> Documentation Index
> Fetch the complete documentation index at: https://tilebox.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Dataset.query

import { Fragment } from "astro/jsx-runtime";

import ApiReference from "@docs/components/ApiReference.astro";

import ParamField from "@docs/components/ParamField.astro";

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

type: 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**

type: 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**

type: 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**

type: SpatialFilterLike | None

Optional spatial filter for spatio-temporal datasets. Pass a geometry to use the default intersection behavior, or configure a [spatial filter mode](/docs/datasets/query/filter-by-location#spatial-filter-modes).

**skip_data**

type: bool

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

**show_progress**

type: 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**

type: A temporal_extent for your query must be specified

Raised when `temporal_extent` is not provided.

**ValueError**

type: "Collection

not found in dataset <dataset>">
Raised when one or more collection names do not exist in the dataset.

**ValueError**

type: "Collection

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

<h2 id="request-example">Usage example</h2>

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

Source: https://tilebox.com/docs/api-reference/python/tilebox.datasets/Dataset.query/index.mdx