Object holds

Usage

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 does not have a retention configuration and is stored in a bucket without a retention policy, both hold types behave exactly the same. The following table describes how each hold type behaves if an object has a retention configuration or is stored in a bucket with a retention policy:

Object has an event-based hold Object has a temporary hold
Object has a retention configuration Not applicable: Objects cannot simultaneously have an event-based hold and a retention configuration Releasing a temporary hold does not affect the object's retain-until time
Object is stored in a bucket with a retention policy Releasing an event-based hold resets the object's time in the bucket for the purposes of the retention period Releasing a temporary hold does not affect the object's time in the bucket for the purposes of the retention period

Event-based hold example

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.

At this point, you release the hold from both objects. For Object A, which was using an event-based hold, 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, which was using a temporary hold, can immediately be deleted or replaced, because the temporary hold has no effect on when the object fulfilled its retention time.

This behavior lets you 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 the 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.

Restrictions

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

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

  • 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.

What's next