ALTER STREAMING QUERY

ALTER STREAMING QUERY changes settings of streaming queries and controls their lifecycle (start and stop).

Syntax

ALTER STREAMING QUERY [IF EXISTS] <query_name> SET (
    <key1> = <value1>,
    <key2> = <value2>,
    ...
)

Parameters

IF EXISTS — do not fail if the streaming query does not exist.
query_name — name of the streaming query to change.
SET (<key> = <value>) — optional list of settings to update.

Changing query settings

Syntax:

ALTER STREAMING QUERY [IF EXISTS] <query_name> SET (<key> = <value>)

Available parameters:

RUN = (TRUE|FALSE) — start or stop the query.
RESOURCE_POOL = <resource_pool_name> — name of the resource pool where the query runs.

When you run SET (RUN = TRUE), read offsets from topics and aggregation state are restored from a checkpoint. If there is no checkpoint, reading starts from the latest data.

Examples of changing settings are below.

Permissions

Streaming queries require permission ALTER SCHEMA. Example grant for my_streaming_query:

GRANT ALTER SCHEMA ON my_streaming_query TO `user@domain`

Examples

Changing settings

Stop my_streaming_query:

ALTER STREAMING QUERY my_streaming_query SET (
    RUN = FALSE
)

Start my_streaming_query in resource pool my_resource_pool:

ALTER STREAMING QUERY my_streaming_query SET (
    RUN = TRUE,
    RESOURCE_POOL = my_resource_pool
)

Query status

Current status is available in the Status column of the .sys/streaming_queries system view View streaming query metadata:

SELECT
    Path,
    Status,
    Text,
    Run
FROM
    `.sys/streaming_queries`

Possible status values:

CREATING — query is being created after CREATE STREAMING QUERY.
CREATED — query exists but is not running (for example, RUN = FALSE).
STARTING — query is starting.
RUNNING — query is executing.
SUSPENDED — query paused due to internal errors; the system will retry.
STOPPING — query is stopping after ALTER STREAMING QUERY ... SET (RUN = FALSE).
STOPPED — query is stopped.

After successful DDL for create or alter, status is guaranteed to be CREATED, STARTING, RUNNING, STOPPED, or SUSPENDED depending on RUN = (TRUE|FALSE) and whether startup succeeded.

More examples for other data formats: Topic read and write formats. For capabilities and limitations of streaming queries, see Streaming queries.