Function ecs_query_new


#include <include/flecs.h>

FLECS_API ecs_query_t * ecs_query_new(ecs_world_t *world, const char *sig)


Create a query. This operation creates a query. Queries are used to iterate over entities that match a signature expression and are the fastest way to find and iterate over entities and their components.

Queries should be created once, and reused multiple times. While iterating a query is a cheap operation, creating and deleting a query is expensive. The reason for this is that queries are "prematched", which means that a query stores state about which entities (or rather, tables) match with the query. Building up this state happens during query creation.

Once a query is created, matching only happens when new tables are created. In most applications this is an infrequent process, since it only occurs when a new combination of components is introduced. While matching is expensive, it is importent to note that matching does not happen on a per-entity basis, but on a per-table basis. This means that the average time spent on matching per frame should rapidly approach zero over the lifetime of an application.

A query provides direct access to the component arrays. When an application creates/deletes entities or adds/removes components, these arrays can shift component values around, or may grow in size. This can cause unexpected or undefined behavior to occur if these operations are performed while iterating. To prevent this from happening an application should either not perform these operations while iterating, or use deferred operations (see ecs_defer_begin and ecs_defer_end).

Queries can be created and deleted dynamically. If a query was not deleted (using ecs_query_free) before the world is deleted, it will be deleted automatically.


world - The world.

sig - The query signature expression.

The new query.

Mentioned in


Line 2218 in include/flecs.h.