These are the docs for 13.7, an old version of SpatialOS. The docs for this version are frozen: we do not correct, update or republish them. 14.5 is the newest →

Streaming queries

streaming_query is an optional field in the bridge configuration section of a worker configuration file.

What streaming queries are

SpatialOS is based on the idea that, usually, worker instances only need to know about in the entities they’re authoritative over, plus entities that are nearby (ie within the entity interest radius). For example, a player might need to see entities up to 50m away from them, but not any further away.

But sometimes, worker instances need information about other entities. For example, entities that are far away but should be visible (such as mountains), or entities for global communication that aren’t physically located anywhere (for example, a global weather system). To allow a worker instance to receive updates to these entities, you can use streaming queries.

Entity queries or streaming queries?

If you want information about an entity, but you don’t need regular updates about it, use an entity query instead.

If you need regular updates about an entity, it’s better to use streaming queries: they return information periodically, and they only return the new information about a component, rather than all the information about it.

Query-based interest

You can use query-based interest (beta) instead of streaming queries. This lets you write queries to express precisely which components on other entities you are interested in, meaning that the worker instance only receives updates relevant to what it is simulating.

How streaming queries work

Using streaming queries is similar to checking out. If you set up a streaming query for a component, for entities with that component, the worker instance gets a local representation of an entity, and receives updates about it. Effectively, to the worker instance, it looks like the entity is within its checkout area.

The worker instance gets updates to this entity’s components at specific time intervals. You can configure this (see below).


Streaming queries have some limitations:

  • The worker instance doesn’t receive all of the updates for each component of an entity:
    • It only gets updates at the time interval you set (see below).
    • It doesn’t receive any event updates.
  • You can only set the time interval globally for all streaming queries within a deployment.
  • You can’t change streaming queries at runtime.
  • You have to specify components to query, rather than entities.

Setting up a streaming query

First, you need to pick a component. By default, for every entity with that component, a streaming query will return updates to all components on that entity. However, it’s good practice to improve efficiency and bandwidth use by narrowing down which updates are returned.

To do this, specify:

  • which components (on the entities returned by the streaming query) you want updates for
  • a radius (around entities that a worker instance is authoritative over) that an entity must be within

You always need to include the improbable.Position component, and, if you’re writing a streaming query for a Unity or Unreal worker type, you also need to include the improbable.Metadata component.

For example, the following snippet will send this worker instance:

  • updates to the components,, and for all entities with the component
  • updates to all components from all entities with the component, within a radius of 1000 world units around an entity that the worker instance is authoritative over
"streaming_query": [
        "global_component_streaming_query": {
            "component_name": ""
        "components_streamed": {
            "specific_components": {
                "components": [
    "bounded_component_streaming_query": {
        "component_name": "",
        "radius": 1000

Configuring the time interval

To configure the time interval between streaming queries, set streaming_query_interval in your launch configuration file.

The default time interval is 4 seconds.

Search results

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums