# EntityQuery > Use an EntityQuery object to select entities with components that meet specific requirements. ## Definition * **Type:** Struct * **Namespace:** [Unity.Entities](/engine/7000.0/script-reference/unity/entities.md) * **Assembly:** UnityEngine.EntitiesModule * **Implements:** [IDisposable](https://learn.microsoft.com/dotnet/api/system.idisposable), [IEquatable\](https://learn.microsoft.com/dotnet/api/system.iequatable-1) ```csharp public struct EntityQuery : IDisposable, IEquatable ``` ## Remarks An entity query defines the set of component types that an [archetype] must contain in order for its chunks and entities to be selected and specifies whether the components accessed through the query are read-only or read-write. For simple queries, you can create an EntityQuery based on an array of component types. The following example defines a EntityQuery that finds all entities with both Rotation and RotationSpeed components. The query uses [ComponentType.ReadOnly] instead of the simpler `typeof` expression to designate that the system does not write to RotationSpeed. Always specify read-only when possible, since there are fewer constraints on read-only access to data, which can help the Job scheduler execute your Jobs more efficiently. For more complex queries, you can use an [EntityQueryDesc](/engine/7000.0/script-reference/unity/entities/entityquerydesc.md) object to create the entity query. A query description provides a flexible query mechanism to specify which archetypes to select based on the following sets of components: " `All` = All component types in this array must exist in the archetype, and must be enabled on matching entities. " `Any` = At least one of the component types in this array must exist in the archetype, and must be enabled on matching entities. " `None` = None of the component types in this array can exist in the archetype, or they must be present and disabled on matching entities. " `Disabled` = All component types in this array must exist in the archetype, and must be disabled on matching entities. " `Absent` = None of the component types in this array can exist in the archetype " `Present` = All of the component types in this array must exist in the archetype, whether or not they are enabled. For example, the following query includes archetypes containing Rotation and RotationSpeed components, but excludes any archetypes containing a Static component: **Note:** Do not include completely optional components in the query description. To handle optional components, use [IJobChunk](/engine/7000.0/script-reference/unity/entities/ijobchunk.md) and the [ArchetypeChunk.Has()] method to determine whether a chunk contains the optional component or not. Since all entities within the same chunk have the same components, you only need to check whether an optional component exists once per chunk -- not once per entity. Within a system class, use the [ComponentSystemBase.GetEntityQuery()] function to get a EntityQuery instance. You can filter entities based on whether they have [changed] or whether they have a specific value for a [shared component]. Once you have created an EntityQuery object, you can [reset] and change the filter settings, but you cannot modify the base query. Use an EntityQuery for the following purposes: " To get a [native array] of the values for a specific [IComponentData](/engine/7000.0/script-reference/unity/entities/icomponentdata.md) type for all entities matching the query " To get an [native array] of the [ArchetypeChunk](/engine/7000.0/script-reference/unity/entities/archetypechunk.md) objects matching the query " To schedule an [IJobChunk](/engine/7000.0/script-reference/unity/entities/ijobchunk.md) job " To control whether a system updates using \[ComponentSystemBase.RequireForUpdate(query)] [Entities.ForEach]: xref:Unity.Entities.SystemBase.Entities [Entities.WithStoreEntityQueryInField]: xref:Unity.Entities.SystemBase.Entities [ComponentSystemBase.GetEntityQuery()]: xref:Unity.Entities.ComponentSystemBase.GetEntityQuery" [ComponentType.ReadOnly]: xref:Unity.Entities.ComponentType.ReadOnly@@@@1 [ComponentSystemBase.RequireForUpdate()]: xref:Unity.Entities.ComponentSystemBase.RequireForUpdate\(Unity.Entities.EntityQuery\) [ArchetypeChunk.Has()]: xref:Unity.Entities.ArchetypeChunk.Has@@1\(Unity.Entities.ComponentTypeHandle{@@0}\) [archetype]: xref:Unity.Entities.EntityArchetype [changed]: xref:Unity.Entities.EntityQuery.SetChangedVersionFilter" [shared component]: xref:Unity.Entities.EntityQuery.SetSharedComponentFilter" [reset]: xref:Unity.Entities.EntityQuery.ResetFilter" [native array]: https://docs.unity3d.com/ScriptReference/Unity.Collections.NativeArray_1.html ## Properties | Property | Description | | -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | [IsEmpty](/engine/7000.0/script-reference/unity/entities/entityquery/isempty.md) | Reports whether this query would currently select zero entities. | | [IsEmptyIgnoreFilter](/engine/7000.0/script-reference/unity/entities/entityquery/isemptyignorefilter.md) | Reports whether this query would currently select zero entities. This will ignore any filters set on the EntityQuery. | ## Methods | Method | Description | | -------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [AddChangedVersionFilter](/engine/7000.0/script-reference/unity/entities/entityquery/addchangedversionfilter.md) | Filters out entities in chunks for which the specified component has not changed. Additive with other filter functions. | | [AddDependency](/engine/7000.0/script-reference/unity/entities/entityquery/adddependency.md) | Adds another job handle to this EntityQuery's dependencies. | | [AddOrderVersionFilter](/engine/7000.0/script-reference/unity/entities/entityquery/addorderversionfilter.md) | Filters out entities in chunks for which no structural changes have occurred. Additive with other filter functions. | | [AddSharedComponentFilter](/engine/7000.0/script-reference/unity/entities/entityquery/addsharedcomponentfilter.md) | Filters this EntityQuery so that it only selects entities with an unmanaged shared component of type `SharedComponent` equal to `sharedComponent`. Additive with other filter functions. | | [CalculateBaseEntityIndexArray](/engine/7000.0/script-reference/unity/entities/entityquery/calculatebaseentityindexarray.md) | Generates an array containing the index of the first entity within each chunk, relative to the list of entities that match this query. | | [CalculateBaseEntityIndexArrayAsync](/engine/7000.0/script-reference/unity/entities/entityquery/calculatebaseentityindexarrayasync.md) | Asynchronously generates an array containing the index of the first entity within each chunk, relative to the list of entities that match this query. | | [CalculateChunkCount](/engine/7000.0/script-reference/unity/entities/entityquery/calculatechunkcount.md) | Calculates the number of chunks that match this EntityQuery, taking into account all active query filters and enabled components. | | [CalculateChunkCountWithoutFiltering](/engine/7000.0/script-reference/unity/entities/entityquery/calculatechunkcountwithoutfiltering.md) | Calculates the number of chunks that match this EntityQuery, ignoring any set filters. | | [CalculateEntityCount](/engine/7000.0/script-reference/unity/entities/entityquery/calculateentitycount.md) | Calculates the number of entities selected by this EntityQuery. | | [CalculateEntityCountWithoutFiltering](/engine/7000.0/script-reference/unity/entities/entityquery/calculateentitycountwithoutfiltering.md) | Calculates the number of entities selected by this EntityQuery, ignoring any set filters. | | [CalculateFilteredChunkIndexArray](/engine/7000.0/script-reference/unity/entities/entityquery/calculatefilteredchunkindexarray.md) | Generates an array which gives the index of each chunk relative to the set of chunks that currently match the query, after taking all active filtering into account. | | [CalculateFilteredChunkIndexArrayAsync](/engine/7000.0/script-reference/unity/entities/entityquery/calculatefilteredchunkindexarrayasync.md) | Asynchronously generates an array which gives the index of each chunk relative to the set of chunks that currently match the query, after taking all active filtering into account. | | [CompareQuery](/engine/7000.0/script-reference/unity/entities/entityquery/comparequery.md) | Compares a query description to the description defining this EntityQuery. | | [CompleteDependency](/engine/7000.0/script-reference/unity/entities/entityquery/completedependency.md) | Ensures all jobs running on this EntityQuery complete. | | [CopyFromComponentDataArray](/engine/7000.0/script-reference/unity/entities/entityquery/copyfromcomponentdataarray.md) | Copies the values of component type `T` in a NativeArray into the entities matched by this query. | | [CopyFromComponentDataListAsync](/engine/7000.0/script-reference/unity/entities/entityquery/copyfromcomponentdatalistasync.md) | Asynchronously copies the values of component type `T` in a NativeList into the entities matched by this query. | | [Dispose](/engine/7000.0/script-reference/unity/entities/entityquery/dispose.md) | Disposes this EntityQuery instance. | | [Equals](/engine/7000.0/script-reference/unity/entities/entityquery/equals.md) | Compare a query to another object (assumed to be a boxed EntityQuery). | | [GetCombinedComponentOrderVersion](/engine/7000.0/script-reference/unity/entities/entityquery/getcombinedcomponentorderversion.md) | This method computes the sum of the order versions for all components required by this query. | | [GetDependency](/engine/7000.0/script-reference/unity/entities/entityquery/getdependency.md) | Combines all dependencies in this EntityQuery into a single JobHandle. | | [GetEntityQueryDescs](/engine/7000.0/script-reference/unity/entities/entityquery/getentityquerydescs.md) | Reconstructs the query descriptions used to create this [EntityQuery](/engine/7000.0/script-reference/unity/entities/entityquery.md). | | [GetEntityQueryMask](/engine/7000.0/script-reference/unity/entities/entityquery/getentityquerymask.md) | Returns an [EntityQueryMask](/engine/7000.0/script-reference/unity/entities/entityquerymask.md), which can be used to quickly determine if an entity matches the query. | | [GetHashCode](/engine/7000.0/script-reference/unity/entities/entityquery/gethashcode.md) | Compute the hash code for this query | | [GetSingleton](/engine/7000.0/script-reference/unity/entities/entityquery/getsingleton.md) | Gets the value of a singleton component. Note that if querying a singleton component from a system-associated entity, the query must include either EntityQueryOptions.IncludeSystems or the SystemInstance component. | | [GetSingletonBuffer](/engine/7000.0/script-reference/unity/entities/entityquery/getsingletonbuffer.md) | Gets the value of a singleton buffer component. Note that if querying a singleton buffer component from a system-associated entity, the query must include either EntityQueryOptions.IncludeSystems or the SystemInstance component. | | [GetSingletonEntity](/engine/7000.0/script-reference/unity/entities/entityquery/getsingletonentity.md) | Attempts to retrieve the single entity that this query matches. | | [GetSingletonRW](/engine/7000.0/script-reference/unity/entities/entityquery/getsingletonrw.md) | Gets a reference to a singleton component, for read/write access. Note that if querying a singleton component from a system-associated entity, the query must include either EntityQueryOptions.IncludeSystems or the SystemInstance component. | | [HasFilter](/engine/7000.0/script-reference/unity/entities/entityquery/hasfilter.md) | Reports whether this entity query has a filter applied to it. | | [HasSingleton](/engine/7000.0/script-reference/unity/entities/entityquery/hassingleton.md) | Checks whether a singleton component of the specified type exists. Note that if querying a singleton component from a system-associated entity, the query must include either EntityQueryOptions.IncludeSystems or the SystemInstance component. | | [Matches](/engine/7000.0/script-reference/unity/entities/entityquery/matches.md) | Returns true if the entity matches the query, false if it does not. | | [MatchesIgnoreFilter](/engine/7000.0/script-reference/unity/entities/entityquery/matchesignorefilter.md) | Returns true if the entity's archetype is matched by this query, ignoring all query filtering (including chunk filters and enableable components). | | [ResetFilter](/engine/7000.0/script-reference/unity/entities/entityquery/resetfilter.md) | Resets this EntityQuery's chunk filter settings to the default (all filtering disabled). | | [SetChangedVersionFilter](/engine/7000.0/script-reference/unity/entities/entityquery/setchangedversionfilter.md) | Filters out entities in chunks for which the specified component has not changed. | | [SetOrderVersionFilter](/engine/7000.0/script-reference/unity/entities/entityquery/setorderversionfilter.md) | Filters out entities in chunks for which no structural changes have occurred. | | [SetSharedComponentFilter](/engine/7000.0/script-reference/unity/entities/entityquery/setsharedcomponentfilter.md) | Filters this EntityQuery so that it only selects entities with shared component of type `SharedComponent` equal to `sharedComponent`. | | [SetSingleton](/engine/7000.0/script-reference/unity/entities/entityquery/setsingleton.md) | Sets the value of a singleton component. Note that if querying a singleton component from a system-associated entity, the query must include either EntityQueryOptions.IncludeSystems or the SystemInstance component. | | [ToArchetypeChunkArray](/engine/7000.0/script-reference/unity/entities/entityquery/toarchetypechunkarray.md) | Synchronously creates an array of the chunks containing entities matching this EntityQuery. | | [ToArchetypeChunkList](/engine/7000.0/script-reference/unity/entities/entityquery/toarchetypechunklist.md) | Synchronously fills a list with the chunks containing entities matching this EntityQuery. | | [ToArchetypeChunkListAsync](/engine/7000.0/script-reference/unity/entities/entityquery/toarchetypechunklistasync.md) | Asynchronously creates a list of the chunks containing entities matching this EntityQuery. | | [ToComponentDataArray](/engine/7000.0/script-reference/unity/entities/entityquery/tocomponentdataarray.md) | Creates a NativeArray containing the components of type T for the selected entities. | | [ToComponentDataListAsync](/engine/7000.0/script-reference/unity/entities/entityquery/tocomponentdatalistasync.md) | Creates (and asynchronously populates) a NativeList containing the value of component `T` for the selected entities. Since the exact number of entities matching the query won't be known until the job runs, this method returns a [NativeList\](/engine/7000.0/script-reference/unity/collections/nativelist1.md). | | [ToEntityArray](/engine/7000.0/script-reference/unity/entities/entityquery/toentityarray.md) | Creates a NativeArray containing the selected entities. | | [ToEntityListAsync](/engine/7000.0/script-reference/unity/entities/entityquery/toentitylistasync.md) | Creates (and asynchronously populates) a NativeList containing the selected entities. Since the exact number of entities matching the query won't be known until the job runs, this method returns a [NativeList\](/engine/7000.0/script-reference/unity/collections/nativelist1.md). | | [TryGetSingleton](/engine/7000.0/script-reference/unity/entities/entityquery/trygetsingleton.md) | Gets the value of a singleton component, and returns whether or not a singleton component of the specified type matches inside the [EntityQuery](/engine/7000.0/script-reference/unity/entities/entityquery.md). Note that if querying a singleton component from a system-associated entity, the query must include either EntityQueryOptions.IncludeSystems or the SystemInstance component. | | [TryGetSingletonBuffer](/engine/7000.0/script-reference/unity/entities/entityquery/trygetsingletonbuffer.md) | Gets the value of a singleton buffer component, and returns whether or not a singleton buffer component of the specified type exists in the [World](/engine/7000.0/script-reference/unity/entities/world.md). Note that if querying a singleton buffer component from a system-associated entity, the query must include either EntityQueryOptions.IncludeSystems or the SystemInstance component. | | [TryGetSingletonEntity](/engine/7000.0/script-reference/unity/entities/entityquery/trygetsingletonentity.md) | Gets the singleton Entity, and returns whether or not a singleton [Entity](/engine/7000.0/script-reference/unity/entities/entity.md) of the specified type exists in the [World](/engine/7000.0/script-reference/unity/entities/world.md). | | [TryGetSingletonRW](/engine/7000.0/script-reference/unity/entities/entityquery/trygetsingletonrw.md) | Gets a reference to the value of a singleton component, and returns whether or not a singleton component of the specified type matches inside the [EntityQuery](/engine/7000.0/script-reference/unity/entities/entityquery.md). Note that if querying a singleton component from a system-associated entity, the query must include either EntityQueryOptions.IncludeSystems or the SystemInstance component. | ## Operators | Operator | Description | | ------------------------------------------------------------------------------------------ | ------------------------------- | | [operator ==](/engine/7000.0/script-reference/unity/entities/entityquery/op-equality.md) | Test two queries for equality | | [operator !=](/engine/7000.0/script-reference/unity/entities/entityquery/op-inequality.md) | Test two queries for inequality |