Struct Query 

pub struct Query<T>
where
    T: QueryTuple,
{
    pub query: NonNull<ecs_query_t>,
    /* private fields */
}

Query for iterating over entities that match a set of conditions.

Queries are the primary way to find and iterate over entities in Flecs. They efficiently match entities based on components, relationships, and other criteria. Queries can be cached for fast repeated iteration or uncached for one-time use.

📚 For comprehensive documentation, see the Flecs Query Manual

Creating Queries

Queries are created using World::new_query() for simple cases or World::query() when you need a builder for complex conditions:

// Simple query - creates cached query immediately
let q1 = world.new_query::<(&Position, &Velocity)>();

// Complex query - use builder for additional conditions
let q2 = world
    .query::<(&Position, &Velocity)>()
    .without(flecs::Prefab)
    .build();

Iteration

Queries provide multiple iteration methods:

// Simple iteration over components
query.each(|(pos, vel)| {
    pos.x += vel.x;
});

// Iteration with entity access
query.each_entity(|entity, (pos, vel)| {
    println!("{} at ({}, {})", entity.name(), pos.x, pos.y);
});

// Low-level table iteration for maximum performance
query.run(|mut it| {
    while it.next() {
        let mut pos = it.field_mut::<Position>(0);
        let vel = it.field::<Velocity>(1);
        for i in it.iter() {
            pos[i].x += vel[i].x;
        }
    }
});

Cached vs Uncached

Queries can be cached or uncached:

• Uncached (created with new_query()): Fast creation, slower iteration
• Cached (created with new_query_named() or explicit cache kind): Slower creation, fast iteration

Use the builder’s set_cache_kind() to control caching behavior:

// Uncached - good for one-off queries
let uncached = world.new_query::<&Position>();

// Cached - good for repeated queries
let cached = world.new_query_named::<&Position>("positions");

// Explicit control
let custom = world
    .query::<&Position>()
    .set_cache_kind(QueryCacheKind::Auto)
    .build();

Lifetime and Ownership

Queries are reference-counted and can be cloned cheaply. They remain valid as long as the world exists. Attempting to use a query after its world is destroyed will panic.

let query = world.new_query::<&Position>();
let query_clone = query.clone(); // Cheap - just increments refcount

Examples

Returning Queries from Functions

// The 'static lifetime ensures components live long enough
fn create_foo_query(world: &World) -> Query<&'static Foo> {
    world.new_query::<&Foo>()
}

let query = create_foo_query(&world);
query.each(|foo| { /* ... */ });

Complex Query Conditions

let query = world
    .query::<(&Position, &Velocity)>()
    .with(Enemy)
    .without(flecs::Prefab)
    .build();

See Also

• QueryBuilder for building complex queries
• World::new_query() for creating simple cached queries
• World::query() for creating query builders
• World::each() for one-off iterations without creating a query
• Module documentation for comprehensive query examples
• Flecs Query Manual

Fields

query: NonNull<ecs_query_t>

Implementations

impl<T> Query<T>

where T: QueryTuple,

pub unsafe fn new_from(query: NonNull<ecs_query_t>) -> Self

wraps the query pointer in a new query

Safety

this is unsafe due to the fact that the type of the query is not checked. the user is responsible for ensuring that the query is of the correct type. if not possible, only use .iter functions that do not pass in the components in the callback

Arguments

• query - The query pointer to wrap

pub fn destruct(self)

Destroy a query and its resources.

If the query is used as the parent of subqueries, those subqueries will be orphaned and must be deinitialized as well.

Examples found in repository

examples/flecs/queries/query_group_by_callbacks.rs (line 161)

fn main() {
    let world = World::new();

    // Register components in order so that id for First is lower than Third
    world.component::<First>();
    world.component::<Second>();
    world.component::<Third>();

    // Grouped query
    let query = world
        .query::<(&Position,)>()
        .group_by(Group)
        // Callback invoked when a new group is created
        .on_group_create(Some(callback_group_create))
        // Callback invoked when a group is deleted
        .on_group_delete(Some(callback_group_delete))
        .build();

    // Create entities in 6 different tables with 3 group ids
    world
        .entity()
        .add((Group, Third))
        .set(Position { x: 1.0, y: 1.0 });
    world
        .entity()
        .add((Group, Second))
        .set(Position { x: 2.0, y: 2.0 });
    world
        .entity()
        .add((Group, First))
        .set(Position { x: 3.0, y: 3.0 });

    world
        .entity()
        .add((Group, Third))
        .set(Position { x: 4.0, y: 4.0 })
        .add(Tag);
    world
        .entity()
        .add((Group, Second))
        .set(Position { x: 5.0, y: 5.0 })
        .add(Tag);
    world
        .entity()
        .add((Group, First))
        .set(Position { x: 6.0, y: 6.0 })
        .add(Tag);

    println!();

    // The query cache now looks like this:
    //  - group First:
    //     - table [Position, (Group, First)]
    //     - table [Position, Tag, (Group, First)]
    //
    //  - group Second:
    //     - table [Position, (Group, Second)]
    //     - table [Position, Tag, (Group, Second)]
    //
    //  - group Third:
    //     - table [Position, (Group, Third)]
    //     - table [Position, Tag, (Group, Third)]
    //

    query.run(|mut it| {
        while it.next() {
            let group = world.entity_from_id(it.group_id());
            let pos = it.field::<Position>(0);

            let ctx = unsafe { &*(query.group_context(group) as *mut GroupCtx) };
            println!(
                "Group: {:?} - Table: [{:?}] - Counter: {}",
                group.path().unwrap(),
                it.archetype(),
                ctx.counter
            );

            for i in it.iter() {
                println!(" [{:?}]", pos[i]);
            }

            println!();
        }
    });

    // Deleting the query will call the on_group_deleted callback
    query.destruct();

    // Output:
    //  Group created: "Third"
    //  Group created: "Second"
    //  Group created: "First"
    //
    //  Group: "::First" - Table: [Position, (Group,First)] - Counter: 3
    //   [Position { x: 3.0, y: 3.0 }]
    //
    //  Group: "::First" - Table: [Position, Tag, (Group,First)] - Counter: 3
    //   [Position { x: 6.0, y: 6.0 }]
    //
    //  Group: "::Second" - Table: [Position, (Group,Second)] - Counter: 2
    //   [Position { x: 2.0, y: 2.0 }]
    //
    //  Group: "::Second" - Table: [Position, Tag, (Group,Second)] - Counter: 2
    //   [Position { x: 5.0, y: 5.0 }]
    //
    //  Group: "::Third" - Table: [Position, (Group,Third)] - Counter: 1
    //   [Position { x: 1.0, y: 1.0 }]
    //
    //  Group: "::Third" - Table: [Position, Tag, (Group,Third)] - Counter: 1
    //   [Position { x: 4.0, y: 4.0 }]
    //
    //  Group deleted: "Second"
    //  Group deleted: "First"
    //  Group deleted: "Third"
}

pub fn reference_count(&self) -> i32

pub fn get_iter_raw(&mut self) -> ecs_iter_t

Get the iterator for the query

Arguments

• world - The world to get the iterator for

pub fn is_changed(&self) -> bool

Returns whether the query data changed since the last iteration.

This operation must be invoked before obtaining the iterator, as this will reset the changed state.

Returns

The operation will return true after:

• new entities have been matched with
• matched entities were deleted
• matched components were changed

Otherwise, it will return false.

See also

• TableIter::is_changed()

Examples found in repository

examples/flecs/queries/query_change_tracking_2.rs (line 88)

fn main() {
    let world = World::new();

    // Make Dirty inheritable so that queries can match it on prefabs
    world
        .component::<Dirty>()
        .add_trait::<(flecs::OnInstantiate, flecs::Inherit)>();

    // Create a query that just reads a component. We'll use this query for
    // change tracking. Change tracking for a query is automatically enabled
    // when query::changed() is called.
    // Each query has its own private dirty state which is reset only when the
    // query is iterated.

    let query_read = world
        .query::<&Position>()
        .detect_changes()
        .set_cached()
        .build();

    // Create a query that writes the component based on a Dirty state.
    let query_write = world
        .query::<(&Dirty, &mut Position)>()
        .term_at(0)
        .up_id(id::<flecs::IsA>()) // Only match Dirty from prefab
        .build();

    // Create two prefabs with a Dirty component. We can use this to share a
    // single Dirty value for all entities in a table.
    let prefab_dirty_false = world
        .prefab_named("prefab_dirty_false")
        .set(Dirty { value: false });

    let prefab_dirty_true = world
        .prefab_named("prefab_dirty_true")
        .set(Dirty { value: true });

    // Create instances of p1 and p2. Because the entities have different
    // prefabs, they end up in different tables.
    world
        .entity_named("e1_dirty_false")
        .is_a(prefab_dirty_false)
        .set(Position { x: 10.0, y: 20.0 });

    world
        .entity_named("e2_dirty_false")
        .is_a(prefab_dirty_false)
        .set(Position { x: 30.0, y: 40.0 });

    world
        .entity_named("e3_dirty_true")
        .is_a(prefab_dirty_true)
        .set(Position { x: 40.0, y: 50.0 });

    world
        .entity_named("e4_dirty_true")
        .is_a(prefab_dirty_true)
        .set(Position { x: 50.0, y: 60.0 });

    // We can use the changed() function on the query to check if any of the
    // tables it is matched with has changed. Since this is the first time that
    // we check this and the query is matched with the tables we just created,
    // the function will return true.
    println!();
    println!("query_read.is_changed(): {}", query_read.is_changed());
    println!();

    // The changed state will remain true until we have iterated each table.
    query_read.run(|mut iter| {
        while iter.next() {
            // With the it.changed() function we can check if the table we're
            // currently iterating has changed since last iteration.
            // Because this is the first time the query is iterated, all tables
            // will show up as changed.
            println!(
                "iiter.is_changed() for table [{}]: {}",
                iter.archetype().unwrap(),
                iter.is_changed()
            );
        }
    });

    // Now that we have iterated all tables, the dirty state is reset.
    println!();
    println!("query_read.is_changed(): {:?}", query_read.is_changed());
    println!();

    // Iterate the write query. Because the Position term is InOut (default)
    // iterating the query will write to the dirty state of iterated tables.
    query_write.run(|mut it| {
        while it.next() {
            let dirty = it.field::<Dirty>(0);
            let mut pos = it.field_mut::<Position>(1);

            println!("iterate table [{}]", it.archetype().unwrap());

            // Because we enforced that Dirty is a shared component, we can check
            // a single value for the entire table.
            if !dirty[0].value {
                println!("iter.skip() for table [{}]", it.archetype().unwrap());

                // If the dirty flag is false, skip the table. This way the table's
                // dirty state is not updated by the query.
                dirty.drop();
                pos.drop();
                it.skip();

                continue;
            }

            // For all other tables the dirty state will be set.
            for i in it.iter() {
                pos[i].x += 1.0;
                pos[i].y += 1.0;
            }
        }
    });

    // One of the tables has changed, so q_read.changed() will return true
    println!();
    println!("query_read.is_changed(): {}", query_read.is_changed());
    println!();

    // When we iterate the read query, we'll see that one table has changed.
    query_read.run(|mut iter| {
        while iter.next() {
            println!(
                "iter.is_changed() for table [{}]: {}",
                iter.archetype().unwrap(),
                iter.is_changed()
            );
        }
    });
    println!();

    // Output:
    //  query_read.is_changed(): true
    //
    //  iiter.is_changed() for table [Position, (Identifier,Name), (IsA,prefab_dirty_false)]: true
    //  iiter.is_changed() for table [Position, (Identifier,Name), (IsA,prefab_dirty_true)]: true
    //
    //  query_read.is_changed(): false
    //
    //  iterate table [Position, (Identifier,Name), (IsA,prefab_dirty_false)]
    //  iter.skip() for table [Position, (Identifier,Name), (IsA,prefab_dirty_false)]
    //  iterate table [Position, (Identifier,Name), (IsA,prefab_dirty_true)]
    //
    //  query_read.is_changed(): true
    //
    //  iter.is_changed() for table [Position, (Identifier,Name), (IsA,prefab_dirty_false)]: false
    //  iter.is_changed() for table [Position, (Identifier,Name), (IsA,prefab_dirty_true)]: true
}

pub fn group_info( &self, group_id: impl Into<Entity>, ) -> *const ecs_query_group_info_t

Get info for group

Arguments

• group_id - The group id to get info for

Returns

Returns a pointer to the group info

pub fn group_context(&self, group_id: impl Into<Entity>) -> *mut c_void

Get context for group

Arguments

• group_id - The group id to get context for

Returns

Returns a (void) pointer to the group context

Examples found in repository

examples/flecs/queries/query_group_by_callbacks.rs (line 144)

fn main() {
    let world = World::new();

    // Register components in order so that id for First is lower than Third
    world.component::<First>();
    world.component::<Second>();
    world.component::<Third>();

    // Grouped query
    let query = world
        .query::<(&Position,)>()
        .group_by(Group)
        // Callback invoked when a new group is created
        .on_group_create(Some(callback_group_create))
        // Callback invoked when a group is deleted
        .on_group_delete(Some(callback_group_delete))
        .build();

    // Create entities in 6 different tables with 3 group ids
    world
        .entity()
        .add((Group, Third))
        .set(Position { x: 1.0, y: 1.0 });
    world
        .entity()
        .add((Group, Second))
        .set(Position { x: 2.0, y: 2.0 });
    world
        .entity()
        .add((Group, First))
        .set(Position { x: 3.0, y: 3.0 });

    world
        .entity()
        .add((Group, Third))
        .set(Position { x: 4.0, y: 4.0 })
        .add(Tag);
    world
        .entity()
        .add((Group, Second))
        .set(Position { x: 5.0, y: 5.0 })
        .add(Tag);
    world
        .entity()
        .add((Group, First))
        .set(Position { x: 6.0, y: 6.0 })
        .add(Tag);

    println!();

    // The query cache now looks like this:
    //  - group First:
    //     - table [Position, (Group, First)]
    //     - table [Position, Tag, (Group, First)]
    //
    //  - group Second:
    //     - table [Position, (Group, Second)]
    //     - table [Position, Tag, (Group, Second)]
    //
    //  - group Third:
    //     - table [Position, (Group, Third)]
    //     - table [Position, Tag, (Group, Third)]
    //

    query.run(|mut it| {
        while it.next() {
            let group = world.entity_from_id(it.group_id());
            let pos = it.field::<Position>(0);

            let ctx = unsafe { &*(query.group_context(group) as *mut GroupCtx) };
            println!(
                "Group: {:?} - Table: [{:?}] - Counter: {}",
                group.path().unwrap(),
                it.archetype(),
                ctx.counter
            );

            for i in it.iter() {
                println!(" [{:?}]", pos[i]);
            }

            println!();
        }
    });

    // Deleting the query will call the on_group_deleted callback
    query.destruct();

    // Output:
    //  Group created: "Third"
    //  Group created: "Second"
    //  Group created: "First"
    //
    //  Group: "::First" - Table: [Position, (Group,First)] - Counter: 3
    //   [Position { x: 3.0, y: 3.0 }]
    //
    //  Group: "::First" - Table: [Position, Tag, (Group,First)] - Counter: 3
    //   [Position { x: 6.0, y: 6.0 }]
    //
    //  Group: "::Second" - Table: [Position, (Group,Second)] - Counter: 2
    //   [Position { x: 2.0, y: 2.0 }]
    //
    //  Group: "::Second" - Table: [Position, Tag, (Group,Second)] - Counter: 2
    //   [Position { x: 5.0, y: 5.0 }]
    //
    //  Group: "::Third" - Table: [Position, (Group,Third)] - Counter: 1
    //   [Position { x: 1.0, y: 1.0 }]
    //
    //  Group: "::Third" - Table: [Position, Tag, (Group,Third)] - Counter: 1
    //   [Position { x: 4.0, y: 4.0 }]
    //
    //  Group deleted: "Second"
    //  Group deleted: "First"
    //  Group deleted: "Third"
}

Trait Implementations

impl<T> Clone for Query<T>

where T: QueryTuple,

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T> Drop for Query<T>

where T: QueryTuple,

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl<T: QueryTuple> From<&Query<T>> for NonNull<ecs_query_t>

fn from(q: &Query<T>) -> Self

Converts to this type from the input type.

impl<T> From<Query<T>> for Entity

where T: QueryTuple,

fn from(query: Query<T>) -> Self

Converts to this type from the input type.

impl<T> IterOperations for Query<T>

where T: QueryTuple,

impl<T> QueryAPI<'_, (), T> for Query<T>

where T: QueryTuple,

fn entity(&self) -> EntityView<'_>

Get the entity of the current query

fn each(&self, func: impl FnMut(T::TupleType<'_>))

Each iterator. The “each” iterator accepts a function that is invoked for each matching entity. The following function signatures is valid:

unsafe fn each_unchecked(&self, func: impl FnMut(T::TupleType<'_>))

Each iterator without aliasing checks.

fn each_internal<const CHECKED: bool>(&self, func: impl FnMut(T::TupleType<'_>))

Internal implementation for both checked and unchecked each iteration.

fn each_entity(&self, func: impl FnMut(EntityView<'_>, T::TupleType<'_>))

Each iterator. The “each” iterator accepts a function that is invoked for each matching entity. The following function signatures is valid:

unsafe fn each_entity_unchecked( &self, func: impl FnMut(EntityView<'_>, T::TupleType<'_>), )

Each entity iterator without aliasing checks.

fn each_entity_internal<const CHECKED: bool>( &self, func: impl FnMut(EntityView<'_>, T::TupleType<'_>), )

Internal implementation for both checked and unchecked each_entity iteration.

fn each_iter( &self, func: impl FnMut(TableIter<'_, false, P>, FieldIndex, T::TupleType<'_>), )

where P: ComponentId,

Each iterator. This variant of each provides access to the TableIter object, which contains more information about the object being iterated. The usize argument contains the index of the entity being iterated, which can be used to obtain entity-specific data from the TableIter object.

unsafe fn each_iter_unchecked( &self, func: impl FnMut(TableIter<'_, false, P>, FieldIndex, T::TupleType<'_>), )

where P: ComponentId,

Each iterator without aliasing checks.

fn each_iter_internal<const CHECKED: bool>( &self, func: impl FnMut(TableIter<'_, false, P>, FieldIndex, T::TupleType<'_>), )

where P: ComponentId,

Internal implementation for both checked and unchecked each_iter iteration.

fn find( &self, func: impl FnMut(T::TupleType<'_>) -> bool, ) -> Option<EntityView<'a>>

find iterator to find an entity The “find” iterator accepts a function that is invoked for each matching entity and checks if the condition is true. if it is, it returns that entity. The following function signatures is valid:

fn find_entity( &self, func: impl FnMut(EntityView<'_>, T::TupleType<'_>) -> bool, ) -> Option<EntityView<'a>>

find iterator to find an entity The “find” iterator accepts a function that is invoked for each matching entity and checks if the condition is true. if it is, it returns that entity. The following function signatures is valid:

fn run(&self, func: impl FnMut(TableIter<'_, true, P>))

where P: ComponentId,

Run iterator.

fn run_each<FuncEach>( &self, func: impl FnMut(TableIter<'_, true, P>), func_each: FuncEach, )

where P: ComponentId, FuncEach: FnMut(T::TupleType<'_>),

Run iterator with each forwarding. The “iter” iterator accepts a function that is invoked for each matching table. The following function signature is valid:

fn run_each_entity<FuncEachEntity>( &self, func: impl FnMut(TableIter<'_, true, P>), func_each: FuncEachEntity, )

where P: ComponentId, FuncEachEntity: FnMut(EntityView<'_>, T::TupleType<'_>),

Run iterator with each entity forwarding.

fn run_each_iter<FuncEachIter>( &self, func: impl FnMut(TableIter<'_, true, P>), func_each: FuncEachIter, )

where P: ComponentId, FuncEachIter: FnMut(TableIter<'_, false, P>, FieldIndex, T::TupleType<'_>),

Each iterator. This variant of each provides access to the TableIter object, which contains more information about the object being iterated. The usize argument contains the index of the entity being iterated, which can be used to obtain entity-specific data from the TableIter object.

fn each_term(&self, func: impl FnMut(&TermRef<'_>))

Each term iterator. The each_term iterator accepts a function that is invoked for each term in the query. The following function signature is valid:

fn term(&self, index: usize) -> TermRef<'_>

Get a immutable reference of the term of the current query at the given index This is mostly used for debugging purposes.

fn field_count(&self) -> i8

Get the field count of the current query

fn term_count(&self) -> u32

Get the count of terms set of the current query

fn to_string(&self) -> String

Convert query to string expression. Convert query terms to a string expression. The resulting expression can be parsed to create the same query.

fn find_var(&self, name: &str) -> Option<i32>

fn plan(&self) -> String

fn iterable(&self) -> QueryIter<'_, P, T>

fn iter_stage(&'a self, stage: impl WorldProvider<'a>) -> QueryIter<'a, P, T>

fn try_first_entity(&self) -> Option<EntityView<'a>>

Return first matching entity.

fn first_entity(&self) -> EntityView<'a>

Return first matching entity.

fn try_first<R>(&self, func: impl FnOnce(T::TupleType<'_>) -> R) -> Option<R>

iterates over the first entity in the iterator and returns a user-defined result.

fn first<R>(&self, func: impl FnOnce(T::TupleType<'_>) -> R) -> R

iterates over the first entity in the iterator and returns a user-defined result.

fn try_first_only<R>( &self, func: impl FnOnce(T::TupleType<'_>) -> R, ) -> Result<R, FirstOnlyError>

Iterates over the first entity in the iterator and returns a user-defined result.

fn first_only<R>(&self, func: impl FnOnce(T::TupleType<'_>) -> R) -> R

iterates over the first entity in the iterator and returns a user-defined result.

fn is_true(&mut self) -> bool

Returns true if iterator yields at least once result.

fn count(&self) -> i32

Return total number of entities in result.

fn set_group(&self, group_id: impl IntoEntity) -> QueryIter<'_, P, T>

Limit results to tables with specified group id (grouped queries only)

fn set_var(&self, var_id: i32, value: impl Into<Entity>) -> QueryIter<'_, P, T>

set variable of iter

fn set_var_table( &self, var_id: i32, table: impl IntoTableRange, ) -> QueryIter<'_, P, T>

set variable of iter as table

fn set_var_expr( &self, name: &str, value: impl Into<Entity>, ) -> QueryIter<'_, P, T>

set variable for rule iter

fn set_var_table_expr( &self, name: &str, table: impl IntoTableRange, ) -> QueryIter<'_, P, T>

set variable for rule iter as table

fn to_json(&self, desc: Option<&IterToJsonDesc>) -> Option<String>

Available on crate feature flecs_json only.

Serialize iterator result to JSON.

fn cache_query(&self) -> Option<Query<()>>

impl<T> Send for Query<T>

where T: QueryTuple,

impl<T> Sync for Query<T>

where T: QueryTuple,

impl<'a, T> WorldProvider<'a> for Query<T>

where T: QueryTuple,

fn world(&self) -> WorldRef<'a>