docs: update Kafka connection examples for BOOTSTRAP BROKER syntax

Updates user-facing documentation to show the new BOOTSTRAP BROKER
and MATCHING broker rules syntax for Kafka PrivateLink connections.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: jubrad

doc/user/content/sql/create-connection.md

@@ -320,8 +320,42 @@ SSH bastion host.
 {{< include-md file="shared-content/aws-privatelink-cloud-only-note.md" >}}
 
 Depending on the hosted service you are connecting to, you might need to specify
-a PrivateLink connection [per advertised broker](#kafka-privatelink-syntax)
-(e.g. Amazon MSK), or a single [default PrivateLink connection](#kafka-privatelink-default) (e.g. Redpanda Cloud).
+a PrivateLink connection and [per-availability-zone routing rules for brokers](#kafka-privatelinks) (e.g. Confluent Cloud),
+a PrivateLink connection [per advertised broker](#kafka-privatelink-syntax) (e.g. Amazon MSK),
+or a single [default PrivateLink connection](#kafka-privatelink-default) (e.g. Redpanda Cloud).
+
+##### Dynamic broker discovery {#kafka-privatelinks}
+
+Confluent Cloud does not require listing every broker individually.
+Instead, specify a `BOOTSTRAP BROKER` for the initial connection and
+wildcard `MATCHING` rules for routing dynamically discovered brokers
+through PrivateLink.
+
+{{% include-syntax file="examples/create_connection" example="syntax-kafka-aws-privatelinks" %}}
+
+When your Confluent cluster is deployed across multiple AZs and your
+PrivateLink connection is configured with matching AZs, you should only
+specify the `AWS PRIVATELINK` on the `BOOTSTRAP BROKER`, not the
+`AVAILABILITY ZONE`. This will allow Materialize to attempt to find the
+bootstrap broker across availability zones. The `MATCHING` rules should
+specify `AVAILABILITY ZONE` to route discovered brokers through their
+specific AZ endpoint.
+
+```mzsql
+CREATE CONNECTION privatelink_svc TO AWS PRIVATELINK (
+    SERVICE NAME 'com.amazonaws.vpce.us-east-1.vpce-svc-0e123abc123198abc',
+    AVAILABILITY ZONES ('use1-az1', 'use1-az4')
+);
+
+CREATE CONNECTION kafka_connection TO KAFKA (
+    BOOTSTRAP BROKER 'lkc-xxx.domyyy.us-east-1.aws.confluent.cloud:9092'
+        USING AWS PRIVATELINK privatelink_svc,
+    BROKERS (
+        MATCHING '*.use1-az1.*' USING AWS PRIVATELINK privatelink_svc (AVAILABILITY ZONE = 'use1-az1'),
+        MATCHING '*.use1-az4.*' USING AWS PRIVATELINK privatelink_svc (AVAILABILITY ZONE = 'use1-az4')
+    )
+);
+```
 
 ##### Broker connection syntax {#kafka-privatelink-syntax}
 
@@ -347,7 +381,7 @@ broker that you want to connect to via the tunnel.
 Field                                   | Value            | Required | Description
 ----------------------------------------|------------------|:--------:|-------------------------------
 `AWS PRIVATELINK`                       | object name      | ✓        | The name of an [AWS PrivateLink connection](#aws-privatelink) through which network traffic for this broker should be routed.
-`AVAILABILITY ZONE`                     | `text`           |          | The ID of the availability zone of the AWS PrivateLink service in which the broker is accessible. If unspecified, traffic will be routed to each availability zone declared in the [AWS PrivateLink connection](#aws-privatelink) in sequence until the correct availability zone for the broker is discovered. If specified, Materialize will always route connections via the specified availability zone.
+`AVAILABILITY ZONE`                     | `text`           |          | The ID of the availability zone of the AWS PrivateLink service in which the broker is accessible.
 `PORT`                                  | `integer`        |          | The port of the AWS PrivateLink service to connect to. Defaults to the broker's port.
 
 ##### Example {#kafka-privatelink-example}
@@ -388,13 +422,6 @@ PrivateLink connection and the port of the bootstrap server instead.
 
 {{% include-syntax file="examples/create_connection" example="syntax-kafka-default-aws-privatelink" %}}
 
-##### Default connection options {#kafka-privatelink-default-options}
-
-Field                                   | Value            | Required | Description
-----------------------------------------|------------------|:--------:|-------------------------------
-`AWS PRIVATELINK`                       | object name      | ✓        | The name of an [AWS PrivateLink connection](#aws-privatelink) through which network traffic for this broker should be routed.
-`PORT`                                  | `integer`        |          | The port of the AWS PrivateLink service to connect to. Defaults to the broker's port.
-
 ##### Example {#kafka-privatelink-default-example}
 
 ```mzsql

doc/user/data/examples/create_connection.yml

@@ -242,11 +242,56 @@
   syntax_elements:
     - name: "`AWS PRIVATELINK <privatelink_connection_name>`"
       description: |
+        *Value:* object name. Required.
+
         The name of an AWS PrivateLink connection through which network traffic
         should be routed.
     - name: "`PORT`"
       description: |
-        The port of the AWS PrivateLink service to connect to.
+        *Value:* `integer`
+
+        The port of the AWS PrivateLink service to connect to. Defaults to the broker's port.
+
+- name: "syntax-kafka-aws-privatelinks"
+  code: |
+    CREATE CONNECTION <connection_name> TO KAFKA (
+        BOOTSTRAP BROKER '<broker_address>'
+            USING AWS PRIVATELINK <privatelink_connection> (PORT <port>),
+        BROKERS (
+            MATCHING '<pattern1>' USING AWS PRIVATELINK <privatelink_connection1> (
+                PORT <port1>,
+                AVAILABILITY ZONE = '<az_id1>'
+            ),
+            MATCHING '<pattern2>' USING AWS PRIVATELINK <privatelink_connection2>
+        ),
+        ...
+    );
+  syntax_elements:
+    - name: "`BOOTSTRAP BROKER`"
+      description: |
+        Specifies a broker address used for the initial connection to the Kafka cluster.
+        The broker is routed through the specified AWS PrivateLink connection.
+    - name: "`MATCHING '<pattern>' USING AWS PRIVATELINK <connection_name>`"
+      description: |
+        Routes brokers whose advertised `host:port` matches `<pattern>` through
+        the named AWS PrivateLink connection.
+        A pattern may begin with `*` to match any prefix. A pattern may end with `*` to match any suffix.
+        All other characters in the pattern are matched literally.
+        Rules are evaluated in order. The first matching rule wins.
+        If no rule matches, Materialize will attempt to connect to the broker directly, without tunneling.
+    - name: "`AVAILABILITY ZONE`"
+      description: |
+        *Value:* `text`. Optional.
+
+        The ID of the availability zone of the AWS PrivateLink service in which
+        the broker is accessible. If omitted, traffic routes through the default
+        PrivateLink endpoint, which distributes across all configured availability
+        zones. Specify this only when you need to pin brokers to specific AZs.
+    - name: "`PORT`"
+      description: |
+        *Value:* `integer`. Optional.
+
+        The port of the AWS PrivateLink service to connect to. Defaults to the broker's port.
 
 - name: "syntax-csr"
   code: |