Skip to content

Change QueryManyIter to return Result instead of only matched items - #25200

Merged
alice-i-cecile merged 6 commits into
bevyengine:mainfrom
JonasJebing:query-iter-many-results
Aug 5, 2026
Merged

alice-i-cecile merged 6 commits into
bevyengine:mainfrom
JonasJebing:query-iter-many-results

Conversation

@JonasJebing

@JonasJebing JonasJebing commented Jul 28, 2026 •

Copy link
Copy Markdown
Contributor

Objective

Fixes #24607

Solution

The original solution created a modified copy of QueryManyIter, but that would induce some API bloat and compile times.

Instead, this PR now changes the signature of QueryManyIter to iterate over Result<D::Item<'w, 's>, QueryEntityError> instead of only matched D::Item<'w, 's>. To make the common cases of iterating only matched entities or unwrapping the errors easy, there are new .matched() and .unwrapped() methods. Similar changes have also been made to related unique and parallel iterators.

Testing

  • Existing unit and documentation test have been adjusted.
  • You can run the tests with cargo test -p bevy_ecs and cargo test -p bevy_ecs --doc

Showcase

This makes it possible to perform custom error handling when an entity does not match, which was not possible with QueryManyIter.
For example logging, returning errors or a panic (unwrap) when iterating many entities are all now possible.

Click to view showcase (Example: return `BevyError`)
use bevy_ecs::prelude::*;

#[derive(Component)]
struct Counter {
    value: i32
}

// A component containing an entity list.
#[derive(Component)]
struct Friends {
    list: Vec<Entity>,
}

fn system(
    friends_query: Query<&Friends>,
    counter_query: Query<&Counter>,
) -> Result<(), BevyError> {
    for friends in &friends_query {
        for counter_result in counter_query.iter_many(&friends.list) {
            let counter = counter_result?;
            println!("Friend's counter: {}", counter.value);
        }
    }
    Ok(())
}

@JonasJebing
JonasJebing marked this pull request as ready for review July 28, 2026 11:59
@alice-i-cecile alice-i-cecile added C-Feature A new feature, making something new possible A-ECS Entities, components, systems, and events X-Contentious There are nontrivial implications that should be thought through D-Straightforward Simple bug fixes and API improvements, docs, test and examples S-Needs-Review Needs reviewer attention (from anyone!) to move forward labels Jul 28, 2026
@github-project-automation github-project-automation Bot moved this to Needs SME Triage in ECS Jul 28, 2026
@alice-i-cecile

Copy link
Copy Markdown
Member

I'm a little leery to add more methods to this effect: the compile time and API bloat costs are real, and iter_many_results is pretty niche. Definitely agree on the mut variant, much less sold on the others.

@JonasJebing

JonasJebing commented Jul 29, 2026 •

Copy link
Copy Markdown
Contributor Author

I wasn't initially planning to add sorting to QueryManyResultsIter. I think sorting results is a niche within a niche anyways. If I remove QueryManySortedResultsIter, then it should also be trivial to implement QueryManyIter by using QueryManyResultsIter internally. That way the amount of new lines of code to compile should be only around 100 lines.

@alice-i-cecile do you also want me to remove the _manual and make the _inner variant private?

Or do you want to go back to designing a different solution altogether? I mean the problem that I am trying to solve for myself is just that it can be pretty hard to notice and debug when an entity is silently skipped via iter_many. Maybe there is a different solution like taking the slight performance hit with Query::get or logging skipped entities inside of iter_many that'd already be good enough.

@alice-i-cecile

Copy link
Copy Markdown
Member

What if we just changed the call signature of iter_many? Breaking changes are fine, and it sounds like this is a real problem.

@JonasJebing

Copy link
Copy Markdown
Contributor Author

Sure, I could change QueryManyIter to be an iterator with Item = Result<...>.
Just to be sure: the existing sort methods would also change to sort the results, just like QueryManyResultsIter does in this PR, correct @alice-i-cecile? And also I guess all the other variants like _unique would be affected.

I feel like ergonomics would be slightly worse, but that could be easily improved with additional iter.unwrapped() and iter.matched() methods.

@alice-i-cecile

Copy link
Copy Markdown
Member

Yes, that sounds like a lovely plan. I would prefer to make this robust, with sugar for making it easy, rather than duplicating the API or making it impossible to handle this robustly.

@alice-i-cecile alice-i-cecile added S-Waiting-on-Author The author needs to make changes or address concerns before this can be merged and removed S-Needs-Review Needs reviewer attention (from anyone!) to move forward labels Jul 30, 2026
@JonasJebing
JonasJebing force-pushed the query-iter-many-results branch 2 times, most recently from f56df93 to d7721e7 Compare July 31, 2026 18:26
@JonasJebing JonasJebing changed the title Add Query::iter_many_results and _mut, _inner, _manual variants Change QueryManyIter to return Result instead of only matched items Jul 31, 2026
@JonasJebing
JonasJebing force-pushed the query-iter-many-results branch from d7721e7 to f593b61 Compare July 31, 2026 18:42
@JonasJebing

JonasJebing commented Jul 31, 2026 •

Copy link
Copy Markdown
Contributor Author

According to our exchange above, I've reworked the PR as I saw fit. But happy to change it further as needed. @alice-i-cecile would you like to take another look?

@alice-i-cecile alice-i-cecile added S-Needs-Review Needs reviewer attention (from anyone!) to move forward and removed S-Waiting-on-Author The author needs to make changes or address concerns before this can be merged labels Aug 2, 2026

@alice-i-cecile alice-i-cecile left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's a much healthier looking diff now. Remember to add a migration guide :)

@alice-i-cecile alice-i-cecile added M-Migration-Guide A breaking change to Bevy's public API that needs to be noted in a migration guide S-Waiting-on-Author The author needs to make changes or address concerns before this can be merged and removed S-Needs-Review Needs reviewer attention (from anyone!) to move forward labels Aug 2, 2026
@JonasJebing

Copy link
Copy Markdown
Contributor Author

I added a migration guide now. I also deleted 3 code comments that didn't seem fitting or that I forgot to delete. Is there anything else needed @alice-i-cecile ?

@alice-i-cecile alice-i-cecile left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah okay, I'm happy with this now :) I'll try and wrangle a second reviewer for you.

@piedoom piedoom left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm still very new to reading Bevy internals so take with a grain of salt :) This looks good though, I like being able to get errors back.


// 0.20
fn my_system(entity_list: Res<MyEntityList>, my_component_query: Query<&MyComponent>) {
my_component_query.par_iter_many(entity_list.iter()).for_each(|my_component| {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

random, and not sure if this is even possible but i wonder if a filter_map could work with the iterator chains better than the let Ok(..) else { }

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since QueryParManyIter does not actually implement the Iterator trait, it is not possible to call Iterator::filter_map.

/// }
/// }
/// # bevy_ecs::system::assert_is_system(system);
///

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wonder if this should be the first example listed (since I believe it is the most usual behavior if users don't care about catching errors)

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Makes sense. I changed the order to matching_system, unwrapping_system then error_system, so that the very similar looking matching_system and unwrapping_system are still next to each other.

@JonasJebing

Copy link
Copy Markdown
Contributor Author

Thank you both for the reviews. @piedoom I think I addressed all your comments. Please check.

@alice-i-cecile alice-i-cecile added S-Ready-For-Final-Review This PR has been approved by the community. It's ready for a maintainer to consider merging it and removed S-Waiting-on-Author The author needs to make changes or address concerns before this can be merged labels Aug 4, 2026
@alice-i-cecile
alice-i-cecile added this pull request to the merge queue Aug 5, 2026
Merged via the queue into bevyengine:main with commit f4611c5 Aug 5, 2026
40 checks passed
@github-project-automation github-project-automation Bot moved this from Needs SME Triage to Done in ECS Aug 5, 2026
joelawm pushed a commit to joelawm/bevy that referenced this pull request Sep 8, 2026
…ms (bevyengine#25200)

# Objective

Fixes bevyengine#24607

## Solution

The original solution created a modified copy of `QueryManyIter`, but
that would induce some API bloat and compile times.

Instead, this PR now changes the signature of `QueryManyIter` to iterate
over `Result<D::Item<'w, 's>, QueryEntityError>` instead of only matched
`D::Item<'w, 's>`. To make the common cases of iterating only matched
entities or unwrapping the errors easy, there are new `.matched()` and
`.unwrapped()` methods. Similar changes have also been made to related
unique and parallel iterators.

## Testing

- Existing unit and documentation test have been adjusted.
- You can run the tests with `cargo test -p bevy_ecs` and `cargo test -p
bevy_ecs --doc`

---

## Showcase

This makes it possible to perform custom error handling when an entity
does not match, which was not possible with `QueryManyIter`.
For example logging, returning errors or a panic (unwrap) when iterating
many entities are all now possible.

<details>
<summary>Click to view showcase (Example: return `BevyError`)</summary>

```rust
use bevy_ecs::prelude::*;

#[derive(Component)]
struct Counter {
    value: i32
}

// A component containing an entity list.
#[derive(Component)]
struct Friends {
    list: Vec<Entity>,
}

fn system(
    friends_query: Query<&Friends>,
    counter_query: Query<&Counter>,
) -> Result<(), BevyError> {
    for friends in &friends_query {
        for counter_result in counter_query.iter_many(&friends.list) {
            let counter = counter_result?;
            println!("Friend's counter: {}", counter.value);
        }
    }
    Ok(())
}
```

</details>
hymm pushed a commit to hymm/bevy that referenced this pull request Oct 6, 2026
# Objective

Fixes bevyengine#25840.

## Solution

bevyengine#25200 added wrappers around `fetch_next_aliased_unchecked_internal`,
which is marked as `#[inline(always)]`. The new wrappers aren't marked
as `#[inline(always)]`, so the function stopped getting inlined.


## Testing
Ran a couple benchmarks on my laptop, times in μs. 

| Benchmark | Before bevyengine#25200 | main | This PR |
|---|---|---|---|
| propagate_parent_transforms/full_recompute_roots_changed | 300.6 ±
18.5 | 389.8 ± 14.7 | 308.4 ± 21.3 |
| propagate_parent_transforms/full_recompute_leaves_changed | 482.0 ±
11.5 | 575.7 ± 10.7 | 488.5 ± 8.5 |
| transform_pipeline/localized_updates_static_optimized | 428.5 ± 12.6 |
516.1 ± 16.4 | 407.4 ± 17.0 |
| transform_pipeline/localized_updates_no_static_optimization | 303.4 ±
10.1 | 395.9 ± 14.1 | 281.9 ± 14.2 |

---
I used a LLM to find the cause of the regression. I then read the bevyengine#25200
diff to verify its claims and ran the benchmarks.
mockersf pushed a commit that referenced this pull request Oct 7, 2026
# Objective

Fixes #25840.

## Solution

#25200 added wrappers around `fetch_next_aliased_unchecked_internal`,
which is marked as `#[inline(always)]`. The new wrappers aren't marked
as `#[inline(always)]`, so the function stopped getting inlined.


## Testing
Ran a couple benchmarks on my laptop, times in μs. 

| Benchmark | Before #25200 | main | This PR |
|---|---|---|---|
| propagate_parent_transforms/full_recompute_roots_changed | 300.6 ±
18.5 | 389.8 ± 14.7 | 308.4 ± 21.3 |
| propagate_parent_transforms/full_recompute_leaves_changed | 482.0 ±
11.5 | 575.7 ± 10.7 | 488.5 ± 8.5 |
| transform_pipeline/localized_updates_static_optimized | 428.5 ± 12.6 |
516.1 ± 16.4 | 407.4 ± 17.0 |
| transform_pipeline/localized_updates_no_static_optimization | 303.4 ±
10.1 | 395.9 ± 14.1 | 281.9 ± 14.2 |

---
I used a LLM to find the cause of the regression. I then read the #25200
diff to verify its claims and ran the benchmarks.
@rparrett

Copy link
Copy Markdown
Contributor

Do we have any benchmark coverage for these functions?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

A-ECS Entities, components, systems, and events C-Feature A new feature, making something new possible D-Straightforward Simple bug fixes and API improvements, docs, test and examples M-Migration-Guide A breaking change to Bevy's public API that needs to be noted in a migration guide S-Ready-For-Final-Review This PR has been approved by the community. It's ready for a maintainer to consider merging it X-Contentious There are nontrivial implications that should be thought through

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

Add Query::iter_many_results for user-facing flexibility/ergonomics

4 participants