Skip to content

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.

bash
tilebox dataset get open_data.aws_earth.sentinel2

The 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.

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:

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

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:

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.

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.

Next steps

Type to search…