Usage

This page discusses object holds, which are metadata flags that youplace 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 does not have aretention configuration and is stored in abucket without aretention policy, both hold types behave exactly the same.The following table describes how each hold type behaves if an object has aretention configuration or is stored in a bucket with a retention policy:

Event-based hold example

Say you have two objects - Object A and Object B - in a bucket whose retentionpolicy 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. Ayear 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.

At this point, you release the hold from both objects. For Object A, which wasusing an event-based hold, its time in the bucket restarts for the purposes ofthe retention period. This means it must stay in the bucket for another yearbefore it can be deleted or replaced. Object B, which was using a temporaryhold, can immediately be deleted or replaced, because the temporary hold has noeffect on when the object fulfilled its retention time.

This behavior lets you use event-based holds in conjunction withretention policies to control retention based on the occurrence of someevent, such as holding loan documents for a certain period after the loan waspaid. Temporary holds can be used for regulatory or legal purposes, suchas holding trading documents for legal investigation.

The default event-based hold property

In addition to placing holds on individual objects, you canenable the default event-based property on your bucket. When you do this,each new object that subsequently gets added to the bucket automatically has anevent-based hold placed on it.

This behavior is useful when you want an object to persist in your bucket fora 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 certainnumber of years once they've been paid off. With a suitable retention policyand the default event-based hold property enabled for your bucket, when youupload 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 theretention policy ensures the loan remains stored and unchangeable until itfulfills the retention period set in your retention policy.

Restrictions

• Requests that attempt to place an event-based hold on an object that has anexistingretention configuration fail.

  • Requests that would simultaneously place an event-based hold on an objectand set a retention configuration for the object similarly fail.

• Object holds cannot be managed with theXML API, and the hold status ofan object is not included when using the XML API toretrieve object metadata.

  • However, attempting to delete or replace an object with the XML API stillfails if the object has a hold on it.

  • ForXML API multipart uploads, you can initiate an upload and uploadparts, but the request to complete the upload fails if it would overwritean object that has a hold on it.

• Object holds are not supported for buckets that use hierarchical namespace.

What's next

• Learn how toenable event-based holds by default and how toset individual object holds.
• Learn aboutretention policies, which protect data fromdeletion for a specified period of time.
• Learn aboutlifecycle configurations for your bucket, which canautomatically delete objects after you remove their holds.