Skip to content

Add a Query::count() method.#20230

Merged
alice-i-cecile merged 1 commit intobevyengine:mainfrom
chescock:query-count
Jul 21, 2025
Merged

Add a Query::count() method.#20230
alice-i-cecile merged 1 commit intobevyengine:mainfrom
chescock:query-count

Conversation

@chescock
Copy link
Copy Markdown
Contributor

Objective

Make it easy to efficiently count the number of entities matching a query.

Solution

Implement a Query::count() method.

Use as_nop() to skip initializing the fetch state, like we do for is_empty() and contains().

If the filter is archetypal, call size_hint() to get the count without iterating. Otherwise, use an ordinary count().

@chescock chescock mentioned this pull request Jul 21, 2025
@chescock chescock added C-Feature A new feature, making something new possible A-ECS Entities, components, systems, and events S-Needs-Review Needs reviewer attention (from anyone!) to move forward labels Jul 21, 2025
@alice-i-cecile alice-i-cecile added the D-Straightforward Simple bug fixes and API improvements, docs, test and examples label Jul 21, 2025
Copy link
Copy Markdown
Contributor

@Trashtalk217 Trashtalk217 left a comment

Choose a reason for hiding this comment

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

Yes, please!

@copygirl
Copy link
Copy Markdown
Contributor

If the filter is archetypal, call size_hint() to get the count without iterating. Otherwise, use an ordinary count().

Will both "archetypal => can return exact size" and "not archetypal => can't ever return exact size" always be true?

I'm not at all familiar with all this, but would it make sense to have a trait const that specifies whether size_hint() is accurate, or if adding a something new anyway, just an additional function such as size_exact() that returns an Option<usize>? Its default implementation could just return None.

@chescock
Copy link
Copy Markdown
Contributor Author

Will both "archetypal => can return exact size" and "not archetypal => can't ever return exact size" always be true?

I'm not at all familiar with all this, but would it make sense to have a trait const that specifies whether size_hint() is accurate, or if adding a something new anyway, just an additional function such as size_exact() that returns an Option<usize>? Its default implementation could just return None.

Yup, I think that's what QueryFilter::IS_ARCHETYPAL is! The idea is that all queries filter to a certain set of tables or archetypes, but only queries with Added or Changed will further filter that by looking at individual entities. So if we know we don't have those, then we know exactly how many entities will match.

It gets used in the size_hint implementation to determine the minimum size.

fn size_hint(&self) -> (usize, Option<usize>) {
let max_size = self.cursor.max_remaining(self.tables, self.archetypes);
let archetype_query = F::IS_ARCHETYPAL;
let min_size = if archetype_query { max_size } else { 0 };
(min_size as usize, Some(max_size as usize))
}

There's also an ArchetypeFilter trait that's implemented if and only if IS_ARCHETYPAL is true. That's used to get the ExactSizeIterator impl that enables len().

@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-Needs-Review Needs reviewer attention (from anyone!) to move forward labels Jul 21, 2025
@alice-i-cecile alice-i-cecile added this pull request to the merge queue Jul 21, 2025
Merged via the queue into bevyengine:main with commit 9e50e63 Jul 21, 2025
43 checks passed
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 S-Ready-For-Final-Review This PR has been approved by the community. It's ready for a maintainer to consider merging it

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants