Collection.query

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

Copy

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

Request example

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,
  skip_data=True,  # only fetch datapoint IDs and time
)
first_50 = collection.query(temporal_extent=datapoints.time[:50])

Copy