This page describes objects, a resource in Cloud Storage. For a general overview of how Cloud Storage works, see Introduction to Cloud Storage.
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.
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
/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
For information on how to name an object, see the object naming guidelines.
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.