Develop
Develop
Select your platform

Query for changed entities

Updated: Jun 20, 2025

Overview

The changedSince query is an advanced, experimental API. It retrieves entities that changed since a specified DataModel version. The DataModel version increments each time the DataModel changes.

How it works

The changedSince query takes two parameters:
  1. The component ID to track changes for
  2. A DataModel version number
When the query runs, it returns only entities whose specified component has been modified since the provided version number.

Example usage

Here’s an example from the GrabbablePhysicsSystem that demonstrates how to use the changedSince query:
class GrabbablePhysicsSystem() : SystemBase() {
    private var lastUpdateVersion = 0UL

    @OptIn(SpatialSDKExperimentalAPI::class)
    override fun execute() {
        val q = Query.where { changedSince(Grabbable.id, lastUpdateVersion) and has(Physics.id) }
        lastUpdateVersion = EntityContext.getDataModel()!!.getLastUpdateVersion()
        for (entity in q.eval()) {
            ...
        }
    }

    override fun getDependencies(): SystemDependencies? {
        return SystemDependencies(
            mustRunBefore =
                mutableSetOf(SystemDependencyConfig(GrabbableSystem::class, isRequired = false)),
            mustRunAfter = mutableSetOf(SystemDependencyConfig(TickPhysicsSystem::class)))
    }
}
In this example:
  1. The system creates a query that finds all entities where:
    • The Grabbable component has changed since lastUpdateVersion
    • The entity also has a Physics component
  2. After executing the query, the system updates lastUpdateVersion to the current DataModel version
  3. The system then processes the query results.
This approach removes the one tick lag of the changed API, which makes sure that the GrabbablePhysicsSystem can process the entities that have been set a Grabbable component in the same tick.

Tracking version numbers

To use changedSince queries effectively, you need to:
  1. Maintain a version number variable (like lastUpdateVersion in the example)
  2. Update this version number after processing the query results
  3. Use this updated version number in the next query execution
The current version of the data model can be obtained using the getLastUpdateVersion method of the DataModel class:
@SpatialSDKExperimentalAPI
fun getLastUpdateVersion(): ULong {
//
}
Did you find this page helpful?
Thumbs up icon
Thumbs down icon
Nav Logo
Virtual reality / Meta Horizon
Virtual reality / Meta Horizon
Virtual reality / Meta Horizon
English (US)
© 2025 Meta