docs: address review feedback on MySQL snapshot parallelism

Mark the table-splitting feature as private preview since it ships
flag-off, restructure the shared parallelism include as a per-source
list and caveat that a larger cluster can shorten the snapshot only as
far as the work parallelizes, scope the troubleshooting connection
guidance per source type, rework the overload mitigations around
upsizing the database or dropping the source and retrying, point
observability at the existing monitoring page, and add discovery blurbs
to the MySQL and PostgreSQL ingest overview pages.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016AgSuGEvoVT9TFHAgq6FCi

Author: peterdukelarsen

doc/user/content/concepts/snapshotting.md

@@ -31,8 +31,9 @@ menu:
 Snapshotting has the following upstream impacts:
 
 - **Read load.** Snapshotting puts read, CPU, and network load on the upstream
-  system, proportional to the data volume and concentrated in proportion to
-  the source cluster's [parallelism](#parallelism).
+  system. The total load is proportional to the volume of data being
+  snapshotted, while the source cluster's [parallelism](#parallelism) affects
+  the peak load: more workers compress the reads into a shorter window.
 
 - **Change-log retention for CDC database sources.** When ingesting data from
   CDC database sources (PostgreSQL, MySQL, SQL Server), the upstream system must

doc/user/content/headless/ingestion/snapshotting-parallelism.md

@@ -2,21 +2,33 @@
 headless: true
 ---
 
-Materialize parallelizes snapshotting across the workers of the cluster
-hosting the source. For PostgreSQL and MySQL sources, work is distributed by
-table, with different tables read concurrently by different workers.
-PostgreSQL sources additionally partition every table, splitting its read
-across workers (on PostgreSQL 14 and later). MySQL sources partition tables
-that meet certain requirements. See [MySQL snapshot
-parallelism](/ingest-data/mysql/snapshot-parallelism/). Kafka sources are
-parallelized by topic partition, with partitions distributed across workers,
-so parallelism is bounded by the topic's partition count. SQL Server sources
-are not parallelized: a single worker reads all tables.
+Materialize can parallelize snapshotting across the workers of the cluster
+hosting the source.
 
-A cluster's [size](/sql/create-cluster/#available-sizes) determines its
-number of workers, so a larger cluster shortens the snapshot. The volume
-read from the upstream database is unchanged, it is compressed into a
-shorter window of more concurrent queries and connections. To tell whether
-the upstream database is struggling under this load, and for options if it
-is, see [Is the upstream database
+- **PostgreSQL sources** are parallelized by table, i.e., different tables
+  are read concurrently by different workers. On PostgreSQL 14 and later,
+  Materialize additionally attempts to partition each table's read across
+  workers. Tables that cannot be partitioned fall back to a single worker.
+
+- **MySQL sources** are parallelized by table, i.e., different tables are
+  read concurrently by different workers. For tables that meet certain
+  requirements, Materialize can additionally partition the table's read
+  across workers {{< private-preview-inline />}}. See [MySQL snapshot
+  parallelism](/ingest-data/mysql/snapshot-parallelism/).
+
+- **Kafka sources** are parallelized by topic partition, with partitions
+  distributed across workers, so parallelism is bounded by the topic's
+  partition count.
+
+- **SQL Server sources** are not parallelized: a single worker reads all
+  tables.
+
+The degree of snapshot parallelism depends on the number of workers. A
+cluster's [size](/sql/create-cluster/#available-sizes) determines its number
+of workers, so a larger cluster can shorten the snapshot, to the extent the
+work parallelizes and the upstream database keeps up. The volume read from
+the upstream database is unchanged, it is compressed into a shorter window
+of more concurrent queries and connections. To determine whether
+snapshotting is overloading the upstream database, and for ways to mitigate
+the load, see [Is the upstream database
 overloaded?](/ingest-data/troubleshooting/#is-the-upstream-database-overloaded)

doc/user/content/ingest-data/mysql/_index.md

@@ -33,6 +33,11 @@ gives you the following benefits:
   read-replica to build views on top of your MySQL data that are efficiently
   maintained and always up-to-date.
 
+When a source is created, Materialize parallelizes the initial snapshot
+across the cluster's workers and can split the read of large tables that meet
+certain requirements {{< private-preview-inline />}}. See [Snapshot
+parallelism](/ingest-data/mysql/snapshot-parallelism/).
+
 ## Supported versions and services
 
 {{< note >}}

doc/user/content/ingest-data/mysql/snapshot-parallelism.md

@@ -9,22 +9,25 @@ menu:
     weight: 70
 ---
 
+{{< private-preview />}}
+
 When you create a [MySQL source](/sql/create-source/mysql-v2/), Materialize
 performs an initial, snapshot-based sync of the selected tables before it
 starts ingesting change events from the binlog. For large tables, this
 snapshot dominates the time until the source becomes healthy.
 
 How snapshot work is spread across the workers of a cluster, and what that
 means for the upstream database, is covered in
-[Snapshotting](/concepts/snapshotting/#parallelism). This page covers what is
-specific to MySQL: Materialize can split the read of a **single table**
-across all the workers of the cluster, so that even a source dominated by one
-very large table benefits from a larger cluster.
+[Snapshotting](/concepts/snapshotting/#parallelism). Materialize can split
+the read of a **single table** across all the workers of the cluster, so
+that even a source dominated by one very large table benefits from a larger
+cluster. This page covers what is specific to MySQL: which tables are
+eligible for splitting, and how their reads are partitioned.
 
 ## Which tables are split
 
-The snapshot of an individual table is split across workers when all of the
-following hold:
+Materialize splits the snapshot of an individual table across workers when
+all of the following conditions are met:
 
 - The table has a **single-column primary key**. Composite primary keys are
   not supported.
@@ -39,19 +42,22 @@ following hold:
 How evenly the split lands also depends on the distribution of the key
 values. See [How a table is partitioned](#how-a-table-is-partitioned).
 
-Tables that don't meet these requirements, or whose boundary sampling fails
-for any reason, still snapshot correctly: each is read in full by a single
-worker, and different tables are still read concurrently.
+If a table does not meet these requirements, or if the [boundary
+sampling](#how-a-table-is-partitioned) fails, its snapshot is not split: a
+single worker reads the table in full. Different tables are still read
+concurrently by different workers.
 
 ## How a table is partitioned
 
-Materialize partitions a table by the unique leading characters of its
-primary keys. Before reading the table, it probes the primary key index to
-discover key prefixes and uses the MySQL optimizer's row estimates to gauge
-how many rows fall under each one, extending prefixes until it finds
-boundaries that divide the table into roughly even ranges. The probes are
-inexpensive point lookups, capped in proportion to the table's estimated
-size, so this sampling phase stays negligible next to the snapshot itself.
+Materialize partitions an [eligible](#which-tables-are-split) table using the
+leading characters of its primary key values. Before reading the table,
+Materialize probes the primary key index to discover key prefixes and uses
+the MySQL optimizer's row estimates to gauge how many rows fall under each
+prefix. It extends the prefixes as needed to find boundaries that divide the
+table into roughly even ranges. The probes are inexpensive point lookups,
+capped in proportion to the table's estimated size, so the sampling phase
+stays negligible next to the snapshot itself.
+
 Each worker then reads only its assigned range, within the same consistent
 snapshot of the upstream database, so the result is identical to a
 single-worker snapshot, only faster.
@@ -97,8 +103,6 @@ overloaded?](/ingest-data/troubleshooting/#is-the-upstream-database-overloaded)
 
 ## Observability
 
-The progress of an ongoing snapshot is visible in the
-[`mz_internal.mz_source_statistics`](/reference/system-catalog/mz_internal/#mz_source_statistics)
-system catalog view: `snapshot_records_known` is the estimated total size of
-the snapshot and `snapshot_records_staged` is how much of it has been read so
-far.
+To observe the progress of an ongoing snapshot, see [Monitoring the
+snapshotting
+progress](/ingest-data/monitoring-data-ingestion/#monitoring-the-snapshotting-progress).

doc/user/content/ingest-data/postgres/_index.md

@@ -37,6 +37,11 @@ Materialize gives you the following benefits:
     Materialize as a read-replica to build views on top of your PostgreSQL data
     that are efficiently maintained and always up-to-date.
 
+When a source is created, Materialize parallelizes the initial snapshot
+across the cluster's workers and, on PostgreSQL 14 and later, splits each
+table's read across workers. See [Snapshot
+parallelism](/concepts/snapshotting/#parallelism).
+
 ## Supported versions and services
 
 The PostgreSQL source requires **PostgreSQL 11+** and is compatible with most

doc/user/content/ingest-data/troubleshooting.md

@@ -101,29 +101,38 @@ snapshotting](/ingest-data/#use-a-larger-cluster-for-upsert-source-snapshotting)
 
 ## Is the upstream database overloaded?
 
-Snapshotting puts significant load on the upstream database (see [Impact on
-upstream system](/concepts/snapshotting/#impact-on-upstream-system)).
+Snapshotting can put significant load on the upstream database (see [Impact
+on upstream system](/concepts/snapshotting/#impact-on-upstream-system)).
 
-Check the upstream database when a snapshot progresses more slowly than the
-data volume suggests, when applications sharing the database slow down while
+Check the upstream database when a snapshot progresses more slowly than
+expected, when applications sharing the database slow down while
 it runs, or when the source reports upstream connection errors or timeouts.
 The relevant metrics are in your cloud provider's monitoring console, or in
 OS tools like `iostat` and the database's activity views for self-hosted
 databases. Look for:
 
+- **Read IOPS or throughput** flat at a provisioned cap.
 - **CPU** pinned at the instance's limit for the duration of the snapshot.
-- **Read IOPS or throughput** flat at a provisioned cap while disk queue
-  depth and read latency climb.
 - **Network throughput** at the instance type's cap.
-- **Memory** pressure, or a falling cache hit rate as large scans evict the
-  normal workload's working set.
-- **Connections** near the database's limit. Snapshotting opens connections
-  in proportion to the source cluster's workers.
-
-If the database is overloaded, snapshot during off-peak hours, ingest from a
-read replica, use a smaller source cluster to spread the load over a longer
-window, [limit the volume of data](/ingest-data/#limit-the-volume-of-data)
-you sync, or provision more IOPS, throughput, or instance capacity.
+- **Connections** near the database's limit. For PostgreSQL and MySQL
+  sources, snapshotting opens connections in proportion to the source
+  cluster's workers.
+
+Also watch disk usage on the upstream database during a long-running
+snapshot: CDC database sources must retain their change log until Materialize
+consumes it (see [Impact on upstream
+system](/concepts/snapshotting/#impact-on-upstream-system)).
+
+If the database is overloaded, you can upsize the source database or cancel
+the snapshot by dropping the source, and retry:
+
+- on a smaller source cluster to spread the load over a longer window.
+- with more IOPS, throughput, or instance capacity provisioned for the
+  database.
+- during off-peak hours when the database is less busy, as recommended in the
+  [ingestion best practices](/ingest-data/#scheduling).
+- with a smaller [volume of data to
+  sync](/ingest-data/#limit-the-volume-of-data).
 
 ## Adding a new subsource to an existing source blocks replication. Should I just create a new source instead?