---
title: "Collection.query"
description: "Query data points in a collection within a temporal extent."
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.

# Collection.query

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

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

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

```python
def Collection.query(
    *,
    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 a range of data points in this collection in a specified temporal extent.
If no data exists for the requested time or interval, an empty `xarray.Dataset` is returned.

## Parameters

**temporal_extent**

type: TimeIntervalLike

The time or time interval for which to query data. This can be a single time scalar, a tuple of two time scalars, or an array of time scalars.

Valid time scalars are: `datetime.datetime` objects, strings in ISO 8601 format, or Unix timestamps in seconds.

Behavior for each input type:

- **TimeScalar**: If a single time scalar is provided, `query` returns all data points for that exact millisecond.

- **TimeInterval**: If a time interval is provided, `query` returns all data points in that interval. Intervals can be a tuple of two `TimeScalars` or a `TimeInterval` object. Tuples are interpreted as a half-open interval `[start, end)`. With a `TimeInterval` object, the `start_exclusive` and `end_inclusive` parameters control whether the start and end time are inclusive or exclusive.

- **Iterable[TimeScalar]**: If an array of time scalars is provided, `query` constructs a time interval from the first and last time scalar in the array. Here, both the `start` and `end` times are inclusive.

**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, such as `time`, `id`, and `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 the requested data points.

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

```python
from datetime import datetime
from tilebox.datasets import field
from tilebox.datasets.query import TimeInterval

# querying a specific time
time = "2023-05-01 12:45:33.423"
data = collection.query(temporal_extent=time)

# querying a time interval
interval = ("2023-05-01", "2023-08-01")
data = collection.query(temporal_extent=interval)

# displaying a progress bar while querying
data = collection.query(
    temporal_extent=interval,
    show_progress=True,
)

# querying a spatio-temporal collection
# with a spatial filter
data = collection.query(
    temporal_extent=interval,
    spatial_extent=geometry,
    filter=(field("cloud_cover") < 10)
    & (field("platform") == "sentinel-2c"),
)

# querying a time interval with TimeInterval
interval = TimeInterval(
    start=datetime(2023, 5, 1),
    end=datetime(2023, 8, 1),
    start_exclusive=False,
    end_inclusive=False,
)
data = collection.query(temporal_extent=interval)

# querying with an iterable
datapoints = collection.query(
    temporal_extent=interval,
    # only fetch datapoint IDs and time
    skip_data=True,
)
first_50 = collection.query(
    temporal_extent=datapoints.time[:50]
)
```

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