NEOLearn

Query filters

Narrow a query with With, Without, Or, Added, Changed, Spawned and Allow, combine filters, and define reusable filter types.

Updated October 20, 2026

On this page

The second type parameter of a Query is a filter. A filter decides which entities match without fetching any data from them. Use it to pick out entities by a marker component, to exclude some, or to see only what changed since the system last ran.

Rust
use neo::prelude::*;

#[derive(Component)]
struct Enemy;

#[derive(Component)]
struct Frozen;

// enemies that aren't frozen
fn move_enemies(mut query: Query<&mut Transform, (With<Enemy>, Without<Frozen>)>) {
    for mut transform in &mut query {
        transform.translation.x += 1.0;
    }
}

The filters#

FilterMatches entities that
With<T>have a T.
Without<T>don't have a T.
Or<(F1, F2, ..)>pass at least one of the filters.
(F1, F2, ..)pass all of the filters (a tuple means "and").
Added<T>had T added since this system last ran.
Changed<T>had T added or written to since this system last ran.
Spawnedwere spawned since this system last ran. Import it from neo::ecs::query::Spawned.
Allow<T>have or don't have T, overriding a default filter that would hide them, such as Disabled.

With and Without don't fetch the component, so they also work for marker types that carry no data, and they don't count as access to it. That's why Without<Player> can make a second mutable query on Transform legal next to one that has With<Player>.

Combine filters#

Rust
#[derive(Component)]
struct Player;
#[derive(Component)]
struct Npc;
#[derive(Component)]
struct Health(u32);

// players or NPCs whose health changed this frame
fn show_health(query: Query<(&Name, &Health), (Or<(With<Player>, With<Npc>)>, Changed<Health>)>) {
    for (name, health) in &query {
        info!("{name}: {}", health.0);
    }
}

Added and Changed#

Added<T> and Changed<T> compare the component's change ticks with the last time this system ran, so each system sees each change once:

  • the first time a system runs, everything counts as added and changed;
  • Changed<T> also matches when T was just added;
  • a change is any write through a Mut<T> or ResMut<T> (any mutable dereference), even if the value stayed the same. Only fetching &mut T without writing doesn't count. Use set_if_neq to avoid marking unchanged values. See Change detection.
Rust
fn on_new_enemy(query: Query<Entity, Added<Enemy>>) {
    for entity in &query {
        info!("enemy {entity} appeared");
    }
}

Default filters and disabled entities#

Some components hide entities from every query that doesn't mention them. The built-in one is Disabled. With<Disabled>, Has<Disabled> or Allow<Disabled> in a query let it see disabled entities. See Disable an entity.

Reusable filters#

Derive QueryFilter to give a combination of filters a name:

Rust
use neo::ecs::query::QueryFilter;

#[derive(QueryFilter)]
struct ActiveEnemy {
    _enemy: With<Enemy>,
    _not_frozen: Without<Frozen>,
}

fn tick(query: Query<&Transform, ActiveEnemy>) {
    for transform in &query {
        // ...
    }
}

Filters in run conditions#

The same filters drive some run conditions:

Rust
app.add_systems(Update, boss_music.run_if(any_with_component::<Boss>));
app.add_systems(Update, rebuild_nav.run_if(any_match_filter::<Changed<Obstacle>>));

Next steps#