This page discusses object holds, which are metadata flags that you place on individual objects. While an object has a hold placed on it, the object cannot be deleted or replaced. You can, however, edit the metadata of the object.
Types of holds
Cloud Storage offers the following types of holds:
- Event-based holds
- Temporary holds
An object can have one type of hold, both types, or neither hold placed on it. When an object is stored in a bucket without a retention policy, both hold types behave exactly the same. When an object is stored in a bucket with a retention policy, the hold types have different effects on the object when the hold is released:
- An event-based hold resets the object's time in the bucket for the purposes of the retention period.
- A temporary hold does not affect the object's time in the bucket for the purposes of the retention period.
Say you have two objects - Object A and Object B - in a bucket whose retention policy sets a 1-year retention period. When you added the objects to the bucket, you placed an event-based hold on Object A and a temporary hold on Object B. A year passes, and while you'd normally be able to delete them at this point, because both objects still have a hold on them, you can't delete either of them.
Let's say at this point you release the hold from both objects. For Object A, its time in the bucket restarts for the purposes of the retention period. This means it must stay in the bucket for another year before it can be deleted or replaced. Object B, on the other hand, can immediately be deleted or replaced, because the temporary hold has no effect on when the object fulfilled its retention time.
This behavior allows you to use event-based holds in conjunction with retention policies to control retention based on the occurrence of some event, such as holding loan documents for a certain period after loan was paid. Temporary holds can be used for regulatory or legal purposes, such as holding trading documents for legal investigation.
The default event-based hold property
In addition to placing holds on individual objects, you can enable the default event-based property on your bucket. When you do this, each new object that subsequently gets added to the bucket automatically has an event-based hold placed on it.
This behavior is useful when you want an object to persist in your bucket for a certain length of time after a certain event occurs. For example, your bucket may be meant to store loans that you must retain for a certain number of years once they've been paid off. With a suitable retention policy and the default event-based hold property enabled for your bucket, when you upload a loan document to your bucket, it gets an event-based hold placed on it. When the loan is paid off, you can release the hold, at which point the retention policy ensures the loan remains stored and unchangeable until it fulfills the retention period set in your retention policy.
Object holds cannot be managed with the XML API, and the hold status of an object is not included when using the XML API to retrieve object metadata. However, attempting to delete or replace an object with the XML API still fails if the object has a hold on it. For XML API multipart uploads, you can initiate an upload and upload parts, but the request to complete the upload fails if it would overwrite an object that has a hold on it.
- Learn how to enable event-based holds by default and how to set individual object holds.
- Learn about retention policies, which protect data from deletion for a specified period of time.
- Learn about lifecycle configurations for your bucket, which can automatically delete objects after you remove their holds.