Object holds

Go to examples

This page discusses object holds, which you set on individual objects. When an object has a hold placed on it, it cannot be deleted or replaced.

Types of holds

Object holds are metadata flags that you place on individual objects. While an object has a hold placed on it, it cannot be deleted or replaced. You can, however, edit the metadata of an object that has a hold placed on it.

Cloud Storage offers the following types of holds:

  • Event-based holds.
  • Temporary holds.

An object can have one, both, 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.

Example

Say you have two objects - Object A and Object B - in a bucket with 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 starts from scratch 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.

What's next