Dataset.find

def Dataset.find(
    datapoint_id: str | UUID,
    collections: list[str] | list[UUID] | list[Collection] | list[CollectionInfo] | list[CollectionClient] | None = None,
    skip_data: bool = False,
) -> xarray.Dataset

Copy

Find a specific datapoint by ID across one or more collections in this dataset.

If collections is not provided, all collections in the dataset are searched.

Parameters

datapoint_id str | UUID

The ID of the datapoint to find.

collections list[str | UUID | Collection | CollectionInfo | CollectionClient] | None

Optional collection scope for the lookup.

Supported values include collection names, collection IDs, and collection objects. If omitted or set to None, all collections in the dataset are searched.

skip_data bool

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

Returns

An xarray.Dataset containing the requested datapoint.

Since it returns only a single datapoint, the output dataset does not include a time dimension.

Errors

ValueError Invalid datapoint id: <id> is not a valid UUID

Raised when datapoint_id is not a valid UUID.

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.

NotFoundError No such datapoint <id>

Raised when the datapoint cannot be found in the selected collections.

Request example

Python

# search all collections in the dataset
datapoint = dataset.find("0186d6b6-66cc-fcfd-91df-bbbff72499c3")

# search specific collections only
datapoint = dataset.find(
    "0186d6b6-66cc-fcfd-91df-bbbff72499c3",
    collections=["S2A_S2MSI2A", "S2B_S2MSI2A"],
)

# check if a datapoint exists
from tilebox.datasets.sync.dataset import NotFoundError

try:
    dataset.find(
        "0186d6b6-66cc-fcfd-91df-bbbff72499c3",
        collections=["S2A_S2MSI2A"],
        skip_data=True,
    )
    exists = True
except NotFoundError:
    exists = False

Copy