This page discusses the metadata fields that are stored along with objects in Cloud Storage.
Objects stored in Cloud Storage have metadata associated with them.
Metadata identifies properties of the object, as well as specifies how the
object should be handled when it's accessed. Metadata exists as key:value
pairs. For example, the storage class of an object is represented
by the metadata entry
storageClass is the key
for the metadata, and all objects have such a key associated with them.
STANDARD specifies the value this specific object has, and the value varies
from object to object.
The mutability of metadata varies: some metadata you can edit at any time, some
metadata you can only set at the time the object is created, and some metadata
you can only view. For example, you can edit the value of the
metadata at any time, but you can only assign the
storageClass metadata when
the object is created or rewritten, and you cannot directly edit the value
generation metadata, though the
generation value changes when
the object is replaced.
There are two categories of metadata that users can change for objects:
Fixed-key metadata: Metadata whose keys are set, but for which you can specify a value.
Custom metadata: Metadata that you add by specifying both a key and a value associated with the key.
When editing metadata, you should generally avoid non-ascii characters, because they are not permitted in HTTP headers, which the XML API uses. When using the XML API, there is also a 16 KB limit to the combined size of the request URL and HTTP headers, so the total size of your metadata should take this limit into account.
You can edit the following metadata for objects, though you must have sufficient permission to do so:
- Access control metadata
- Object holds
Access control metadata
Cloud Storage uses Identity and Access Management (IAM) and Access Control Lists (ACLs) to control access to objects. Use these links to learn about these access control methods and associated metadata.
Cache-Control metadata can specify two different aspects
of how data is served from Cloud Storage: whether the data can be
cached and whether the data can be transformed.
Cache-Control metadata allows you to control whether and for how long
browser and Internet caches are allowed to cache your objects, which can then
be served to satisfy future requests.
Cache-Control only applies when
accessing objects that:
Cloud Storage respects standard values for
Cache-Control, such as the following:
public: the object can be cached anywhere.
private: the object can be cached in a requester's local cache.
no-cache: the object can be cached, but cannot be used to satisfy future requests unless first validated by Cloud Storage.
no-store: the object can't be cached.
max-age=TIME_IN_SECONDS: the length of time an object may be cached before it's considered stale. You can set
max-ageto any length of time. Stale objects are not served from caches, except in special circumstances.
If an applicable object doesn't have a
Cache-Control metadata entry,
Cloud Storage uses the default value of:
If you allow caching, downloads may continue to receive older versions of
an object, even after uploading a newer version. This is because the older
version remains "fresh" in the cache for a period of time determined by
max-age. Additionally, because objects can be cached at various places on the
Internet, there is no way to force a cached object to expire globally. If you
want to prevent serving cached versions of publicly readable objects, set
Cache-Control: no-store on the object.
For more information about caching with Cloud Storage and Cloud CDN, see Caching.
If you need greater control over cache behavior, you can configure Cloud CDN in front of your bucket.
Cache-Control metadata also allows you to serve objects as they are stored,
without applying any transformations to the data, such as removing gzip
content-encoding for incompatible clients. To serve an object as-is, set
Content-Disposition metadata specifies presentation
information about the data being transmitted. Setting
allows you to control presentation style of the content, for example
determining whether an attachment should be automatically displayed or whether
some form of action from the user should be required to open it. See
https://datatracker.ietf.org/doc/html/rfc6266 for the
Content-Encoding metadata can be used to indicate that an object is
compressed, while still maintaining the object's underlying
For example, a text file that is gzip compressed can have the fact that
it's a text file indicated in
Content-Type and the fact that it's
gzip compressed indicated in
Content-Encoding. You should ensure that
files are, in fact, compressed using the specified
uploading them, or else unexpected behavior can occur when attempting to
download the objects. For more information, see the Transcoding page.
For compressible content, such as text, using
Content-Encoding: gzip saves
network and storage costs and improves content serving performance. However,
for content that is already inherently compressed, such as archives and many
media formats, applying another level of compression and marking it in the
Content-Encoding metadata is typically detrimental to both object size and
performance and should be avoided.
Content-Language metadata indicates the language(s) that
the object is intended for. Refer to ISO 639-1 language codes
for the supported values of this metadata.
The most commonly set metadata is
Content-Type (also known as media type),
which lets browsers render the object properly. All objects have a value
specified in their
Content-Type metadata, but this value does not have to
match the underlying type of the object. For example, if the
not specified by the uploader and cannot be determined, it is set to
application/x-www-form-urlencoded, depending on
how you uploaded the object. For a list of valid content types, see the
IANA Media Types page.
Custom-Time metadata is a user-specified date and time represented in
the RFC 3339 format
YYYY-MM-DD'T'HH:MM:SS'Z' when milliseconds are zero. This metadata is
typically set in order to use the
DaysSinceCustomTime condition in
Object Lifecycle Management.
You cannot remove
Custom-Time once it's been set on an object. Additionally,
the value for
Custom-Time cannot decrease. That is, you cannot set
Custom-Time to be an earlier date/time than the existing
can, however, effectively remove or reset the
rewriting the object.
Use metadata flags to place object holds, which prevent objects from being deleted or replaced. For more information, see the Object holds page.
Custom metadata is metadata for which you define both the key and the value. To
create custom metadata, you specify both a key and a value. After you have
created a custom metadata
key:value pair, you can delete the key or change the
value. Custom metadata is subject to a size limit and incurs
The Viewing and Editing Metadata page includes information about setting custom metadata.
The XML API sets and retrieves object metadata using request headers. In
order to clearly distinguish custom metadata headers from standard request
headers, the XML API prefixes custom metadata headers with
Some tools that use the XML API also apply this convention. For example, when
setting custom metadata with gsutil, you must include the
Note that gsutil removes the prefix when you use it to view an object's
Some metadata cannot be edited directly. This metadata is set at the time of object creation or rewrite. As part of the object creation or rewrite, you can set some such metadata, such as the storage class of the object or customer-managed encryption keys. Other metadata is automatically added and can only be viewed, such the generation number of the object or the time of creation.
Generation and metageneration numbers
As part of its metadata, every Cloud Storage object has a
property and a
metageneration property that uniquely identifies the object:
||Identifies the version of an object, and exists for every object, regardless of whether a bucket uses Object Versioning.
||Identifies the metadata version, and increases every time the metadata of a given
metageneration properties are used in the following
When using preconditions in requests: Preconditions cause the request to fail if the precondition isn't satisfied. Failing in this manner prevents the request from applying to an unexpected version of an object, such as retrieving the wrong object data or modifying the wrong state of an object's metadata.
When listing, accessing, restoring, and deleting noncurrent object versions: Noncurrent object versions are specifically relevant in buckets that use or previously used Object Versioning.