Queries

Updated: Mar 4, 2026

Overview

Queries retrieve entities based on component criteria. Instead of manually iterating over all entities, queries provide a unified interface to find the ones relevant to your system.

Query creation

Create a query by specifying which components an entity must have:

val q = Query.where { has(Physics.id) }

This query matches all entities that have a Physics component.

Query evaluation

Evaluate a query with eval() to get a lazy sequence of matching entities:

val entities: Sequence<Entity> = q.eval()

The query doesn’t execute until eval() is called.

Query operators

Conditional operators

has — entity has the specified components

changed — components changed since last tick

changedSince — components changed since a specific DataModel version (details)

childrenOf — entities that are children of a given entity (details)

Logical operators

and — combine conditions (both must be true)

or — logical OR (either can be true)

Combine operators to build precise queries:

val q = Query.where { has(Scale.id) and changed(Scale.id, Mesh.id, Panel.id) }

This returns entities that have a Scale component AND whose Scale, Mesh, or Panel components changed since the last tick.

Filtering

Refine query results by filtering on component attribute values:

val droneEntities =
    Query.where { has(DroneComponent.id, Transform.id) }
        .filter { by(DroneComponent.enabledData).isEqualTo(true) }
        .eval()

This finds entities with both DroneComponent and Transform, then keeps only those where the enabled attribute is true. Filters run at the native (C++) layer for performance.

For more filter operations, see Filters.

Sorting

Sort and limit query results:

val sortedEntities =
    Query.where { has(DroneComponent.id, Transform.id) }
        .filter { by(DroneComponent.enabledData).isEqualTo(true) }
        .sort {
            with { by(DroneComponent.rotationSpeedData).desc() }
            take(0, 10)
        }
        .eval()

This sorts matching entities by rotationSpeed in descending order and returns the top 10 results. take(offset, count) limits the result set for pagination.

For more sort operations, see Sorting.