Filter by custom fields
Filter datapoints server-side with queryable custom dataset 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.sentinel2The open_data.aws_earth.sentinel2 dataset exposes these queryable fields:
| Field | Type |
|---|---|
stac_id |
string |
platform |
string |
cloud_cover |
float64 |
nodata_pixel_percentage |
float64 |
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
You can compare field values, combine filters, check for missing values, and search for values in repeated enum fields.
| Operation | Syntax |
|---|---|
| Equal | field("x") == value |
| Not equal | field("x") != value |
| Less than | field("x") < value |
| Less than or equal | field("x") <= value |
| Greater than | field("x") > value |
| Greater than or equal | field("x") >= value |
| AND | left & right |
| OR | left | right |
| NOT | ~expression |
| Is null | field("x").is_null() |
| Is not null | field("x").is_not_null() |
Use &, |, and ~ instead of and, or, and not, and place each comparison in parentheses.
| Operation | Syntax |
|---|---|
| Equal | query.Field("x").Equal(value) |
| Not equal | query.Field("x").NotEqual(value) |
| Less than | query.Field("x").LessThan(value) |
| Less than or equal | query.Field("x").LessThanOrEqual(value) |
| Greater than | query.Field("x").GreaterThan(value) |
| Greater than or equal | query.Field("x").GreaterThanOrEqual(value) |
| AND | query.And(left, right) |
| OR | query.Or(left, right) |
| NOT | query.Not(expression) |
| Is null | query.Field("x").IsNull() |
| Is not null | query.Field("x").IsNotNull() |
The CLI accepts a subset of the CQL2 Text syntax.
| Operation | Syntax |
|---|---|
| Equal | x = value |
| Not equal | x <> value |
| Less than | x < value |
| Less than or equal | x <= value |
| Greater than | x > value |
| Greater than or equal | x >= value |
| AND | left AND right |
| OR | left OR right |
| NOT | NOT expression |
| Is null | x IS NULL |
| Is not null | x IS NOT NULL |
String, boolean, and numeric literals and parentheses are supported. Repeating --filter combines expressions with AND.
Fields of type bool and scalar custom enums support only equality and inequality comparisons.
Filter by enum values
Compare an enum field with one of its allowed strings. For the
imagery_products dataset, you can filter for surface-reflectance products:
field("product_type") == "surface-reflectance"query.Field("product_type").Equal("surface-reflectance")--filter "product_type = 'surface-reflectance'"To accept several values, combine equality checks with OR. You can also check for inequality, but enums don’t
support comparisons such as < or >. Values are case-sensitive. An undeclared value causes an error rather
than returning no matches.
Filter by repeated enum fields
A product can be useful for more than one application. If you use a repeated enum to tag products by use case, you can search for products suited to agriculture, flood monitoring, or both.
The ingestion example uses these three products:
| Product | product_type |
use_cases |
|---|---|---|
| A | surface-reflectance |
agriculture, flood-monitoring |
| B | land-cover |
agriculture, urban-planning |
| C | surface-reflectance |
Empty |
# Agriculture: A and B.
field("use_cases").contains("agriculture")
# Agriculture and flood monitoring: A.
field("use_cases").contains_all(["agriculture", "flood-monitoring"])
# Flood monitoring or urban planning: A and B.
field("use_cases").contains_any(["flood-monitoring", "urban-planning"])
# Exclude flood monitoring: B and C.
~field("use_cases").contains("flood-monitoring")// Agriculture: A and B.
query.Field("use_cases").ContainsAll("agriculture")
// Agriculture and flood monitoring: A.
query.Field("use_cases").ContainsAll("agriculture", "flood-monitoring")
// Flood monitoring or urban planning: A and B.
query.Field("use_cases").ContainsAny("flood-monitoring", "urban-planning")
// Exclude flood monitoring: B and C.
query.Not(query.Field("use_cases").ContainsAll("flood-monitoring"))# Agriculture: A and B.
--filter "A_CONTAINS(use_cases, ('agriculture'))"
# Agriculture and flood monitoring: A.
--filter "A_CONTAINS(use_cases, ('agriculture', 'flood-monitoring'))"
# Flood monitoring or urban planning: A and B.
--filter "A_OVERLAPS(use_cases, ('flood-monitoring', 'urban-planning'))"
# Exclude flood monitoring: B and C.
--filter "NOT A_CONTAINS(use_cases, ('flood-monitoring'))"In CLI filters, wrap lists of values in parentheses, not square brackets. Pass the filter with
tilebox dataset query --filter.
Combine scalar and repeated enum filters
Find surface-reflectance products suitable for flood monitoring during October. Replace my_org with your
dataset’s group:
from tilebox.datasets import Client, field
client = Client()
dataset = client.dataset("my_org.imagery_products")
matches = dataset.query(
temporal_extent=("2026-10-01", "2026-11-01"),
filter=(field("product_type") == "surface-reflectance")
& field("use_cases").contains("flood-monitoring"),
)// Imports: "fmt", "time", "github.com/tilebox/tilebox-go/datasets/v1",
// and "github.com/tilebox/tilebox-go/query".
dataset, err := client.Datasets.Get(ctx, "my_org.imagery_products")
if err != nil {
return err
}
start := time.Date(2026, 10, 1, 0, 0, 0, 0, time.UTC)
end := time.Date(2026, 11, 1, 0, 0, 0, 0, time.UTC)
page, err := client.Datapoints.QueryPage(ctx,
dataset.ID,
datasets.WithTemporalExtent(query.NewTimeInterval(start, end)),
datasets.WithFilters(
query.Field("product_type").Equal("surface-reflectance"),
query.Field("use_cases").ContainsAll("flood-monitoring"),
),
)
if err != nil {
return err
}
fmt.Println(len(page.Datapoints))tilebox dataset query my_org.imagery_products \
--after 2026-10-01 --before 2026-11-01 \
--filter "product_type = 'surface-reflectance'" \
--filter "A_CONTAINS(use_cases, ('flood-monitoring'))"How matching works
Reordering or repeating values doesn’t change the matches. A datapoint can have additional values beyond the ones you ask for. You can request up to 100 values per filter, counting duplicates. Each must be a nonempty string defined in the field’s schema.
| Filter | With requested values | With an empty list |
|---|---|---|
| Contains all | Matches when every requested value is present | Matches all datapoints |
| Contains any | Matches when at least one requested value is present | Matches no datapoints |
An empty list means .contains_all([]) or .contains_any([]) in Python, and .ContainsAll() or .ContainsAny()
in Go. Time, location, and other filters still apply. The CLI requires at least one value and doesn’t accept empty
() lists.
These filters work only on queryable repeated custom enums. You can’t compare a repeated field with ==, check it
for null, or test whether its entire list equals or is contained in another list.
Missing and null values
Scalar comparisons 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(),
)This also applies to scalar enums. A filter for products that aren’t land-cover excludes datapoints with no
product_type, whether you use inequality or negate an equality check. Add a null check to include them.
Repeated enums behave differently: an omitted field is an empty list, and membership filters always return true or
false. Searching for flood-monitoring excludes product C, but excluding flood-monitoring includes it, because
C has no use cases assigned.
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.