Filter by custom fields

Queryable fields let you filter datapoints by custom metadata before Tilebox returns the query result. You can combine custom field expressions with temporal, spatial, and collection filters in the same query.

Find queryable fields

The dataset schema identifies which fields are queryable. Inspect the schema to find fields available for filtering.

tilebox dataset get open_data.aws_earth.sentinel2

The open_data.aws_earth.sentinel2 dataset exposes these queryable fields:

Filter datapoints

This query returns Sentinel-2C Level-2A datapoints with less than one percent cloud cover between July 20 and July 28, 2026.

from tilebox.datasets import Client, field

client = Client()
dataset = client.dataset("open_data.aws_earth.sentinel2")

data = dataset.query(
    collections=["L2A"],
    temporal_extent=("2026-07-20", "2026-07-28"),
    filter=(field("cloud_cover") < 1) & (field("platform") == "sentinel-2c"),
)

startDate := time.Date(2026, 7, 20, 0, 0, 0, 0, time.UTC)
endDate := time.Date(2026, 7, 28, 0, 0, 0, 0, time.UTC)

dataset, err := client.Datasets.Get(ctx, "open_data.aws_earth.sentinel2")
if err != nil {
    return err
}
collection, err := client.Collections.Get(ctx, dataset.ID, "L2A")
if err != nil {
    return err
}

page, err := client.Datapoints.QueryPage(ctx,
    dataset.ID,
    datasets.WithCollections(collection),
    datasets.WithTemporalExtent(query.NewTimeInterval(startDate, endDate)),
    datasets.WithFilters(
        query.Field("cloud_cover").LessThan(1.0),
        query.Field("platform").Equal("sentinel-2c"),
    ),
)
if err != nil {
    return err
}
fmt.Println(len(page.Datapoints))

tilebox dataset query open_data.aws_earth.sentinel2 \
  --collections L2A \
  --after 2026-07-20 \
  --before 2026-07-28 \
  --filter "cloud_cover < 1 AND platform = 'sentinel-2c'"

Tilebox combines custom field expressions with temporal, spatial, and collection filters using AND.

Operators

Custom field filters support comparisons, boolean composition, and null checks.

Fields of type bool support only equality and inequality.

Missing and null values

Filter expressions use three-valued logic: true, false, and null (unknown). A datapoint matches only when the complete expression is true. Comparisons against a missing or explicitly null field return null and do not match.

This behavior also applies to inequality. For example, quality != 1 requires quality to be present. Combine the comparison with an explicit null check when missing values should also match.

filter = (field("quality") != 1) | field("quality").is_null()

filter := query.Or(
    query.Field("quality").NotEqual(1),
    query.Field("quality").IsNull(),
)

Query safeguards

A single query can contain filters with at most 64 top-level expressions or operands, 256 expression nodes in total, and eight levels of nesting. These safeguards keep query evaluation bounded.

Next steps