Evicting remote buckets and cached data

This guide demonstrates three ways to evict remote bucket content from AIStore using the ais evict command.

Overview

You can:

Evict an entire remote bucket (data + metadata).
Evict only the data, retaining bucket metadata.
Evict a subset of objects using a prefix, template, or list.

The template is usually an optional prefix, range (Bash expansion, e.g., {start..end}), and optional suffix.

1. Evict the Entire Remote Bucket (Remove Data and Metadata)

To completely remove a remote bucket from AIStore—including its metadata—run ais evict without --keep-md.

1 $ ais evict s3://abc
2 
3 Evicted bucket s3://abc from aistore

This operation removes all cached content and the bucket’s entry from AIStore’s bucket metadata (BMD).

Check eviction job status (it usually completes in a split second, so use --all to show finished jobs):

1 $ ais show job evict --all
2 
3 evict-remote-bucket[rmmd-XrjAI7JdC]
4 NODE             ID              KIND                BUCKET       START        END          STATE
5 nXItghtr         rmmd-XrjAI7JdC  evict-remote-bck    s3://abc     10:20:43     10:20:43     Finished
6 veFtyrfq         rmmd-XrjAI7JdC  evict-remote-bck    s3://abc     10:20:43     10:20:43     Finished
7 vugtciop         rmmd-XrjAI7JdC  evict-remote-bck    s3://abc     10:20:43     10:20:43     Finished

2. Evict Only Bucket Data (Preserve Metadata)

To remove only the in-cluster objects while retaining the bucket metadata, use --keep-md (or -k):

1 $ ais evict s3://abc --keep-md
2 
3 Evicted s3://abc contents from aistore: the bucket is now empty

This is useful for reclaiming space without losing bucket properties.

Confirm the bucket is still in-cluster:

1 $ ais ls
2 
3 NAME       PRESENT
4 s3://abc   yes

Check eviction job status (use -all to show running and already finished jobs):

1 $ ais show job evict --all
2 
3 evict-remote-bucket[kpmd-G7afG87fBC]
4 NODE          ID                   KIND                 BUCKET        START        END          STATE
5 nXItghtr      kpmd-G7afG87fBC      evict-remote-bck     s3://abc      10:22:05     10:22:05     Finished
6 veFtyrfq      kpmd-G7afG87fBC      evict-remote-bck     s3://abc      10:22:05     10:22:05     Finished
7 vugtciop      kpmd-G7afG87fBC      evict-remote-bck     s3://abc      10:22:05     10:22:05     Finished

3. Evict a Specific Prefix, Template, or List

You can evict subsets of objects by specifying:

A prefix in the object path
A --template pattern (e.g., brace expansions)
A --list of object names

Example: Evict by Prefix

Assume we’ve prefetched objects under the copy prefix:

1 $ ais prefetch s3://abc/copy
2 
3 prefetch-objects[acs9_7JB0]: prefetch "copy" from s3://abc. To monitor the progress, run 'ais show job acs9_7JB0'

Verify data was cached:

1 $ ais bucket summary
2 
3 NAME     OBJECTS (cached, remote)     OBJECT SIZES (min, avg, max)     TOTAL OBJECT SIZE (cached, remote)   USAGE(%)
4 -        200 0                        0B         1.00KiB    1.00KiB    200.00KiB 0B                         0%

Notice 200 “cached” (ie., in-cluster) objects. Now evict just that prefix:

1 $ ais evict s3://abc/copy
2 
3 evict-objects[HRdka7fd0]: evict "copy" from s3://abc. To monitor the progress, run 'ais show job HRdka7fd0'

Or alternatively, use an explicit prefix:

1 $ ais evict s3://abc --prefix copy

You can also use brace-expansion syntax, e.g. ais evict "s3://abc/shard-{0000..9999}.tar.lz4; see --help for details.

Check progress and notice that each target reports eviction statistics—object counts and their sizes.

This is because prefix-, template-, or list-based eviction requires AIStore to visit each matching object individually.

1 $ ais show job evict --all

Example output:

1 evict-objects[HRdka7fd0] (ctl: prefix:copy)
2 NODE             ID              KIND                    BUCKET          OBJECTS     BYTES       START       END         STATE
3 nXItghtr         HRdka7fd0       evict-listrange         s3://ais-aa     69          69.00KiB    10:24:09    10:24:10    Finished
4 veFtyrfq         HRdka7fd0       evict-listrange         s3://ais-aa     61          61.00KiB    10:24:09    10:24:10    Finished
5 vugtciop         HRdka7fd0       evict-listrange         s3://ais-aa     70          70.00KiB    10:24:09    10:24:10    Finished

In this particular case, 3-node cluster reported (69+61+70) = 200 evictions, consistent with ais bucket summary above.

Summary

Use Case	Command Example	Keeps Bucket MD?
Fully evict bucket (data + metadata)	`ais evict BUCKET`	❌ No
Evict data only, retain bucket MD	`ais evict BUCKET --keep-md` or `--k`	✅ Yes
Evict subset by prefix/template/list	`ais evict BUCKET/prefix` `--prefix`, `--template`, `--list`	✅ Yes

Use ais show job --all to monitor and verify jobs.