Exclude Prefixes

You can exclude up to 10 prefixes on a bucket with versioning enabled.

This is especially useful for Spark or Hadoop workloads or any process that initially creates objects with temporary prefixes.

Prefixes

A prefix is a common leading string of characters under a bucket that a set of objects share.

Consider a bucket with the following contents

ALIAS/team-bucket/reports/2025/june.docx
ALIAS/team-bucket/reports/2025/may.docx
ALIAS/team-bucket/reports/2025/april.docx
ALIAS/team-bucket/reports/2025/march.docx
ALIAS/team-bucket/template/team-reports.dotx
ALIAS/team-bucket/graphics/team-photo.jpg

The string reports/2025/ is shared by the reports for March, April, May, and June, making reports/2025/ a prefix for those objects. However, the template and the team-photo do not share the same beginning set of characters and are therefore not part of the prefix.

You can exclude the prefixes for template and graphics from versioning while allowing versioning to track changes to team reports in the reports/2025/ prefix.

Behavior

The list of --excluded-prefixes match all objects containing the specified string in their prefix or name, similar to a regular expression of the form prefix*.

To match objects by prefix only, use prefix/*.

Replication

Objects under an excluded prefix are not replicated by bucket replication or site replication, because replication requires versioned objects. Under site replication, the excluded-prefix list itself synchronizes to all peer sites automatically.

Excluding prefixes is the supported way to keep data out of site replication. To keep the contents of an entire bucket local to each site while site replication is enabled, exclude all objects in the bucket with --excluded-prefixes "*". Disabling the bucket’s site-repl-* replication rules with mc replicate update may appear to hold, but site replication silently re-enables the rules whenever it reconfigures the bucket.

Excluded prefixes persist across a suspend cycle

MinIO AIStor preserves the excluded-prefix list when you suspend and then re-enable versioning on a bucket. When you re-enable versioning, the stored list is restored automatically unless you supply a new, non-empty list of excluded prefixes, which replaces the stored one.

While versioning is Suspended, mc version info does not display the excluded prefixes even though MinIO AIStor retains them internally. The list reappears after you re-enable versioning.

Procedure

Begin to create a new bucket or to edit an existing bucket.
If not already enabled, select the Versioning radio button to enable versioning.
Select the toggle next to Exclude Prefixes.

or

When editing a bucket, select the link to + Add Prefixes.
Add each prefix to exclude from versioning.

The bucket must already exist. You cannot exclude prefixes on a bucket while creating the bucket in the AIStor Client.

Use the mc version enable command to add a comma-separated list of prefixes to exclude with the --excluded-prefixes flag.

mc version enable --excluded-prefixes "prefix1, prefix2" ALIAS/BUCKET

Replace prefix1, prefix2 with a comma-separated list of the prefixes to exclude.
Replace ALIAS with the alias of a configured MinIO AIStor deployment.
Replace BUCKET with the target bucket on which to enable versioning.

Resume versioning a prefix

You can re-enable versioning of a prefix or all prefixes in a bucket at any time.

Objects created in a prefix before versioning is re-enabled will have a null version ID after re-enabling versioning for the prefix.

Begin to create a new bucket or to edit an existing bucket.
Select the x next to prefix you want to resume versioning.
Select Save.

Use the mc version enable command to add a comma-separated list of prefixes to exclude with the --excluded-prefixes flag.

mc version enable --excluded-prefixes "prefix2, prefix3" ALIAS/BUCKET

Replace prefix2, prefix3 with a comma-separated list of the prefix(es) to continue to exclude.

If you want to resume versioning on all prefixes in the bucket, do not include the --excluded-prefixes option when running the command.
Replace ALIAS with the alias of a configured MinIO AIStor deployment.
Replace BUCKET with the target bucket on which to enable versioning.

IMPORTANT: This command modifies all versioning options for the bucket. If you have other options enabled you want to continue using, such as ignoring folder objects, be sure to include that option in the command.

Review a list of excluded prefixes

To see a list of excluded prefixes and other versioning options enabled for a bucket, use mc version info ALIAS/BUCKET with the --json option.

mc version info ALIAS/BUCKET --json

The output resembles the following, with the list of excluded prefixes in the ExcludedPrefixes property:

$ mc version info local/my-bucket --json
{
 "Op": "info",
 "status": "success",
 "url": "local/my-bucket",
 "versioning": {
  "status": "Enabled",
  "MFADelete": "",
  "ExcludedPrefixes": [
   "prefix1, prefix2"
  ]
 }
}