Develop
Develop
Select your platform

Query for changed entities

Updated: Mar 4, 2026

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

@OptIn(SpatialSDKExperimentalAPI::class)
class GrabPhysicsSystem : SystemBase() {
    private var lastVersion = 0UL

    override fun execute() {
        val currentVersion = EntityContext.getDataModel()!!.getLastUpdateVersion()
        val q = Query.where { changedSince(Grabbable.id, lastVersion) and has(Physics.id) }
        for (entity in q.eval()) {
            // Grabbable changed since lastVersion — update physics state
        }
        lastVersion = currentVersion
    }

    override fun getDependencies(): SystemDependencies? {
        return SystemDependencies(
            mustRunAfter = mutableSetOf(SystemDependencyConfig(TickPhysicsSystem::class)))
    }
}
Use getDependencies() to control execution order relative to other systems. In this example, the system runs after TickPhysicsSystem so it can react to physics-related grab changes.

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?
Nav Logo
Virtual reality / Meta Horizon
Virtual reality / Meta Horizon
Virtual reality / Meta Horizon
English (US)
© 2026 Meta