Mostly small changes to compaction docs + changelog

jonesphillip · jonesphillip · commit aa90ed074706 · 2025-09-23T18:37:28.000-07:00
diff --git a/src/content/changelog/r2/2025-09-25-data-catalog-compaction.mdx b/src/content/changelog/r2/2025-09-25-data-catalog-compaction.mdx
@@ -1,39 +1,27 @@
 ---
-title: R2 Data Catalog now supports compaction.
+title: R2 Data Catalog now supports compaction
 description: Users can now enable compaction on R2 Data Catalog
 products:
   - r2
-date: 2025-09-25
+date: 2025-09-25T13:00:00
 hidden: true
 ---
 import {
 	LinkCard,
 } from "~/components";
 
-Today, we're adding support for managed [compaction](/r2/data-catalog/about-compaction) for [Apache Iceberg](https://iceberg.apache.org/) tables managed by [R2 Data Catalog](/r2/data-catalog/).
+You can now enable automatic compaction for [Apache Iceberg](https://iceberg.apache.org/) tables in [R2 Data Catalog](/r2/data-catalog/) to improve query performance.
 
-Compaction is the process of taking a group of small files and combining them into fewer larger files. This is an important maintenance operation as it helps ensure that performance remains consistent by reducing the number of files that needs to be scanned when running queries.
+Compaction is the process of taking a group of small files and combining them into fewer larger files. This is an important maintenance operation as it helps ensure that query performance remains consistent by reducing the number of files that needs to be scanned.
 
-To enable compaction in R2 Data Catalog, find it under **R2 Data Catalog** in your bucket settings in the dashboard
+To enable automatic compaction in R2 Data Catalog, find it under **R2 Data Catalog** in your R2 bucket settings in the dashboard.
 
 ![compaction-dash](~/assets/images/changelog/r2/compaction.png)
 
-or simply run:
+Or with [Wrangler](/workers/wrangler/), run:
 
 ```bash
-npx wrangler r2 bucket catalog compaction enable <BUCKET_NAME>  --targetSizeMb 128 --token <API_TOKEN>
+npx wrangler r2 bucket catalog compaction enable <BUCKET_NAME>  --target-size 128 --token <API_TOKEN>
 ```
 
-And that's it. Compaction will start running automatically.
-
-<LinkCard
-	title="Learn more about R2 Data Catalog"
-	href="/r2/data-catalog/manage-catalogs"
-	description="Learn how to manage R2 Data Catalog and enable compaction on your bucket."
-/>
-
-<LinkCard
-	title="Learn more about compaction"
-	href="/r2/data-catalog/about-compaction"
-	description="Learn more about compaction, best practices, and limitations."
-/>
+To get started with compaction, check out [manage catalogs](/r2/data-catalog/manage-catalogs/). For best practices and limitations, refer to [about compaction](/r2/data-catalog/about-compaction/).
diff --git a/src/content/docs/r2/data-catalog/about-compaction.mdx b/src/content/docs/r2/data-catalog/about-compaction.mdx
@@ -8,36 +8,32 @@ sidebar:
 
 ## What is compaction?
 
-Compaction is the process of taking a group of small files and combining them into fewer larger files. This is an important maintenance operation as it helps ensure that performance remains consistent by reducing the number of files that needs to be scanned.
+Compaction is the process of taking a group of small files and combining them into fewer larger files. This is an important maintenance operation as it helps ensure that query performance remains consistent by reducing the number of files that needs to be scanned.
 
 ## Why do I need compaction?
 
-Every write operation in Apache Iceberg, no matter how small or large, results in a series of new files being generated. As time goes on, the number of files can grow unbounded. This can lead to:
-- Increased metadata overhead: Each file has its own metadata, file path, column statistics, etc. This means the query engine will have to read a large amount of metadata to satisfy a given query.
-- Increased I/O operations: Without compaction, query engines will have to open and read each individual file, resulting in increased resource usage and cost.
-- Reduced compression efficiency: Smaller files tend to compress less efficiently compared to larger files.
+Every write operation in [Apache Iceberg](https://iceberg.apache.org/), no matter how small or large, results in a series of new files being generated. As time goes on, the number of files can grow unbounded. This can lead to:
+- Slower queries and increased I/O operations: Without compaction, query engines will have to open and read each individual file, resulting in longer query times and increased costs.
+- Increased metadata overhead: Query engines must scan metadata files to determine which ones to read. With thousands of small files, query planning takes longer even before data is accessed.
+- Reduced compression efficiency: Smaller files compress less efficiently than larger files, leading to higher storage costs and more data to transfer during queries.
 
-## R2 Data Catalog Compaction
+## R2 Data Catalog automatic compaction
 
-R2 Data Catalog can now [manage compaction](/r2/data-catalog/manage-catalogs) for Apache Iceberg tables stored in R2. The compaction service periodically runs every hour and compacts new files that have not been compacted yet.
+R2 Data Catalog can now [manage compaction](/r2/data-catalog/manage-catalogs) for Apache Iceberg tables stored in R2. When enabled, compaction runs automatically and combines new files that have not been compacted yet.
 
-You can tell which files in R2 have been compacted as they have a `compacted-` added to the file name in the `/data/` directory.
+Compacted files are prefixed with `compacted-` in the `/data/` directory.
 
 ### Choosing the right target file size
 
-You can configure the target file size compaction should try to generate if possible. There is a minimum of `64 MB` and a maximum of `512 MB` currently.
+You can configure the target file size for compaction. Currently, the minimum is 64 MB and the maximum is 512 MB.
 
-Different compute engines tend to have different best practices when it comes to ideal file sizes so it's best to consult their documentation to find out what's best.
+Different compute engines have different optimal file sizes, so check their documentation.
 
-It's important to note that there are performance tradeoffs to keep in mind based on the use case. For example, if your use case is primarily performing queries that are well defined and will return small amounts of data, having a smaller target file size might be more beneficial as you might end up reading more data than necessary with larger files.
+Performance tradeoffs depend on your use case. For example, queries that return small amounts of data may perform better with smaller files, as larger files could result in reading unnecessary data.
 - For workloads that are more latency sensitive, consider a smaller target file size (for example, 64MB - 128MB)
 - For streaming ingest workloads, consider medium file sizes (for example, 128MB - 256MB)
 - For OLAP style queries that need to scan a lot of data, consider larger file sizes (for example, 256MB - 512MB)
 
-:::note
-Make sure to check to your compute engine documentation to check if there's a recommended file size.
-:::
-
 ## Current limitations
 - During open beta, compaction will compact up to 2GB worth of files once per hour for each table.
 - Only data files stored in parquet format are currently supported with compaction.
diff --git a/src/content/docs/r2/data-catalog/config-examples/index.mdx b/src/content/docs/r2/data-catalog/config-examples/index.mdx
@@ -3,7 +3,7 @@ pcx_content_type: navigation
 title: Connect to Iceberg engines
 head: []
 sidebar:
-  order: 4
+  order: 5
   group:
     hideIndex: true
 description: Find detailed setup instructions for Apache Spark and other common query engines.
diff --git a/src/content/docs/r2/data-catalog/manage-catalogs.mdx b/src/content/docs/r2/data-catalog/manage-catalogs.mdx
@@ -78,7 +78,7 @@ npx wrangler r2 bucket catalog disable <BUCKET_NAME>
 </Tabs>
 
 ## Enable compaction
-Compaction is a performance optimization that takes the many small files created when ingesting data and combines them into fewer, larger files according to the set `target file size`. [Click here](http:///r2/data-catalog/about-compaction) to learn more about compaction.
+Compaction improves query performance by combining the many small files created during data ingestion into fewer, larger files according to the set `target file size`. For more information about compaction and why it's valuable, refer to [About compaction](/r2/data-catalog/about-compaction/).
 <Tabs syncKey='CLIvDash'>
 <TabItem label='Dashboard'>
 
@@ -87,10 +87,10 @@ Compaction is a performance optimization that takes the many small files created
 
    <DashButton url="/?to=/:account/r2/overview" />
 2. Select the bucket you want to enable compaction on.
-3. Switch to the **Settings** tab, scroll down to **R2 Data Catalog**, and click on the **edit** icon next to the compaction card.
-4. Click enable and optionally set a target file size. The default is 128MB.
-5. Provide a credential: you can choose to allow us generate an account-level token on your behalf, which is scoped to your bucket (recommended); or, you can manually input a token.
-6. Slick *save*
+3. Switch to the **Settings** tab, scroll down to **R2 Data Catalog**, and click on the **Edit** icon next to the compaction card.
+4. Enable compaction and optionally set a target file size. The default is 128MB.
+5. (Optional) Provide a Cloudflare API token for compaction to access and rewrite files in your bucket.
+6. Select **Save**.
 </Steps>
 
 </TabItem>
@@ -99,16 +99,16 @@ Compaction is a performance optimization that takes the many small files created
 To enable the compaction on your catalog, run the [`r2 bucket catalog enable command`](/workers/wrangler/commands/#r2-bucket-catalog-compaction-enable):
 
 ```bash
-npx wrangler r2 bucket catalog compaction enable <BUCKET_NAME>  --targetSizeMb 128 --token <API_TOKEN>
+npx wrangler r2 bucket catalog compaction enable <BUCKET_NAME>  --target-size 128 --token <API_TOKEN>
 ```
 </TabItem>
 </Tabs>
-An API Token is a required argument to enable compaction because our process needs to access and write metadata in R2 Catalog and access files in the R2 bucket, just like any Iceberg client would require. So we need an API Token with R2 Bucket Read/Write permissions and R2 Catalog Read/Write permissions. The token is encrypted and securely accessed only by our compaction processor. Once saved, it is not required again if you re-enable compaction on your Catalog after disabling it.
+Compaction requires a Cloudflare API token with **both** R2 storage and R2 Data Catalog read/write permissions to act as a service credential. The compaction process uses this token to read files, combine them, and update table metadata. Refer to [Authenticate your Iceberg engine](#authenticate-your-iceberg-engine) for details on creating a token with the required permissions.
 
-After enabling, compaction will be enabled retroactively on all existing tables, and will be enabled by default for newly created tables. During open beta, we currently compact up to 2GB worth of files once per hour for each table.
+Once enabled, compaction applies retroactively to all existing tables and automatically to newly created tables. During open beta, we currently compact up to 2GB worth of files once per hour for each table.
 
 ## Disable compaction
-Disabling compaction will prevent the process from running for all tables within the Catalog. You can re-enable it at any time.
+Disabling compaction will prevent the process from running for all tables managed by the catalog. You can re-enable it at any time.
 
 <Tabs syncKey='CLIvDash'>
 <TabItem label='Dashboard'>
@@ -119,8 +119,8 @@ Disabling compaction will prevent the process from running for all tables within
    <DashButton url="/?to=/:account/r2/overview" />
 2. Select the bucket you want to enable compaction on.
 3. Switch to the **Settings** tab, scroll down to **R2 Data Catalog**, and click on the **edit** icon next to the compaction card.
-4. Click **disable**.
-5. Slick *save*.
+4. Disable compaction.
+5. Select **Save**.
 </Steps>
 
 </TabItem>
@@ -129,7 +129,7 @@ Disabling compaction will prevent the process from running for all tables within
 To disable the compaction on your catalog, run the [`r2 bucket catalog disable command`](/workers/wrangler/commands/#r2-bucket-catalog-compaction-disable):
 
 ```bash
-npx wrangler r2 bucket catalog compaction disable <BUCKET_NAME> --token <API_TOKEN>
+npx wrangler r2 bucket catalog compaction disable <BUCKET_NAME>
 ```
 </TabItem>
 </Tabs>
diff --git a/src/content/partials/workers/wrangler-commands/r2.mdx b/src/content/partials/workers/wrangler-commands/r2.mdx
@@ -122,8 +122,8 @@ wrangler r2 bucket catalog compaction enable <BUCKET> [OPTIONS]
   - The name of the bucket to enable R2 Data Catalog compaction for.
 - `--token` <Type text="string" /> <MetaInfo text="required" />
   - The R2 API token with R2 Data Catalog edit permissions
-- `--targetSizeMb` <Type text="number" /> <MetaInfo text="required" />
-  - The target file size compaction will attempt to generate if possible. Default: 128MB.
+- `--target-size` <Type text="number" /> <MetaInfo text="required" />
+  - The target file size (in MB) compaction will attempt to generate. Default: 128.
 
 <AnchorHeading
 	title="`catalog compaction disable`"
