sys.sp_create_event_group_stream (Transact-SQL)

2025-06-16

Applies to: SQL Server 2025 (17.x) Preview

Creates an event group stream for the change event streaming (CES) feature introduced in SQL Server 2025 (17.x) Preview.

Note

Change event streaming is currently in preview for SQL Server 2025.

Transact-SQL syntax conventions

Syntax

sp_create_event_stream_group
    [ @stream_group_name = ] N'stream_group_name'
    , [ @destination_type = ] N'destination_type'
    , [ @destination_location = ] N'destination_location'
    [, [ @destination_credential = ] N'destination_credential' ]
    [, [ @max_message_size_kb = ] max_message_size_kb ]
    [, [ @partition_key_scheme = ] N'partition_key_scheme' ]
    [, [ @partition_key_column_name = ] N'partition_key_column_name' ]
    [, [ @encoding = ] N'encoding' ]

Arguments

[ @stream_group_name = ] N'stream_group_name'

Specifies the name of the event stream group you want to create. @stream_group_name is sysname, and can't be NULL.

[ @destination_type = ] N'destination_type'

Specifies the streaming destination type. @destination_type is sysname, and can't be NULL. Can be one of the following values: AzureEventHubsAmqp or AzureEventHubsApacheKafka

[ @destination_location = ] N'destination_location'

Describes the Azure Event Hubs namespace and instance name. @destination_location is nvarchar(4000), and can't be NULL.

For the Apache Kafka protocol, specify the port.

[ @destination_credential = ] N'destination_credential'

Specifies database scoped credential name to be used. @destination_credential is sysname, and can't be NULL.

[ @max_message_size_kb = ] max_message_size_kb

If specified, defines the max CES message size in kilobyes. @max_message_size_kb is int, and can't be NULL. The message is split if it exceeds the specified max size. This parameter is optional.

@max_message_size_kb has the following characteristics:

Default value: 256 (corresponds to 256 KB)
Minimum allowed value: 128 (corresponds to 128 KB)
Maximum allowed value: 1024 (corresponds to 1 MB)

The @max_message_size_kb parameter should align to the limits of the destination. For example, the maximum message size for Azure Event Hubs is 1 MB for the Standard and Premium tiers. To learn more, review Azure Event Hubs quotas.

[ @partition_key_scheme = ] N'partition_key_scheme'

Defines the type of partitioning. @partition_key_scheme is sysname, and can't be NULL.

@partition_key_scheme can be one of the following values:

Value	Description
`None` (default)	Partitioning isn't specified, so events are assigned to partitions by the event hub using a round-robin strategy.
`StreamGroup`	Partitioning is done by stream group so that all tables in the stream group are streamed to the same partition.
`Table`	Partitioning is done by table so that each table in the stream group is streamed to a different partition.
`Column`	Partitioning is done by column so that each column in the stream group is streamed to a different partition.

[ @partition_key_column_name = ] N'partition_key_column_name'

Defines which column to use for partitioning when @partition_key_scheme is set to Column. @partition_key_column_name is sysname, and can't be NULL.

Use a two-part name for the column that includes both the schema name and column name. For example, a valid value is dbo.Addresses.

[ @encoding = ] N'encoding'

Specifies the message encoding. @encoding is sysname, and can't be NULL. Can be one of the following values:

JSON (default)
Binary

Return code values

0 (success) or 1 (failure).

Permissions

A user with CONTROL database permissions, db_owner database role membership, or sysadmin server role membership can execute this procedure.

Examples

A. Create event stream group that streams into Azure Event Hubs with AMQP protocol

EXECUTE sys.sp_create_event_stream_group
    @stream_group_name = N'myStreamGroup',
    @destination_type = N'AzureEventHubsAmqp',
    @destination_location = N'myEventHubsNamespace.servicebus.windows.net/myEventHubsInstance',
    @destination_credential = MyDatabaseScopedCredentialForCes;

B. Create event stream group that streams into Azure Event Hubs with Kafka protocol

EXECUTE sys.sp_create_event_stream_group
    @stream_group_name = N'myStreamGroup',
    @destination_type = N'AzureEventHubsAmqp',
    @destination_location = N'myEventHubsNamespace.servicebus.windows.net:9093/myEventHubsInstance',
    @destination_credential = MyDatabaseScopedCredentialForCes;

Share via