About Cloud Storage objects

Stay organized with collections Save and categorize content based on your preferences.

This page describes objects, a resource in Cloud Storage. For a general overview of how Cloud Storage works, see Introduction to Cloud Storage.

Objects

Objects are the individual pieces of data that you store in Cloud Storage.

  • There is no limit on the number of objects that you can create in a bucket.

Objects have two components: object data and object metadata. Object data is typically a file that you want to store in Cloud Storage and is completely opaque to Cloud Storage. Object metadata is a collection of name-value pairs that describe various object qualities.

Object names

An object's name is treated as a piece of object metadata in Cloud Storage. Object names can contain any combination of Unicode characters (UTF-8 encoded), must be less than 1024 bytes in length, and must be unique within a bucket.

Cloud Storage uses a flat namespace to store objects, which means that Cloud Storage sees all objects in a given bucket as independent with no hierarchical relationship. For convenience, tools such as Google Cloud console as well as Google Cloud CLI commands work with objects that use the slash (/) character as if they were stored in a virtual hierarchy.

For example, you could name one object /europe/france/paris.jpg and another object /europe/france/cannes.jpg. When using the Google Cloud console you can then navigate to these objects as if they were in a hierarchical directory structure under the folders europe and france.

For information on how to name an object, see the object naming guidelines.

Object immutability

Objects are immutable, which means that an uploaded object cannot change throughout its storage lifetime. An object's storage lifetime is the time between successful object creation, such as uploading, and successful object deletion. In practice, this means that you cannot make incremental changes to objects, such as append operations or truncate operations. However, it is possible to replace objects that are stored in Cloud Storage, and doing so happens atomically: until the new upload completes, the old version of the object is served to readers, and after the upload completes the new version of the object is served to readers. So a single replacement operation simply marks the end of one immutable object's lifetime and the beginning of a new immutable object's lifetime.

The generation number for an object changes each time you replace the object's data. Thus, the generation number uniquely identifies an immutable object.

Note that there is a once-per-second limit for rapidly replacing the same object. Replacing the same object more frequently might result in 429 Too Many Requests errors. You should design your application to upload data for a particular object no more than once per second and handle occasional 429 Too Many Requests errors using truncated exponential backoff.

What's next

Learn how to upload and download objects.