These are the docs for 13.8, 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

You can use streaming queries to complement chunk-based interest. Alternatively, you can use query-based interest instead of chunk-based interest and streaming queries.

Streaming queries are a way to extend chunk-based interest (CBI) so that worker instances can have active read access to distant entity components. Find out about the different types of interest and about setting up active read access in the active read access documentation.

When you use CBI, worker instances have default areas of interest which you can extend to include nearby entities using the entity_interest radius.

Sometimes, worker instances need updates about components on entities which aren’t in the default or extended area of interest. For example, a client-worker instance that is rendering the game to a player might need to receive updates about distant mountains which should be visible to the player, or a server-worker instance might need updates on components on distant entities for weather systems or world-wide communications. You can use streaming queries to achieve this.

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

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.

How streaming queries work

If you set up a streaming query for a component, for entities with that component, the worker instance receives updates about it. Effectively, to the worker instance, it looks like the entity is within its interest 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.
  • Component filtering dictates which components a worker instance receives updates on as a result of a streaming query.

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 has write access authority 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 has write access authority 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