Compose objects

Overview

This page shows you how to compose multiple Cloud Storage objects into a single object. A compose request takes between 1 and 32 objects and creates a new, composite object. The composite object is a concatenation of the source objects in the order they were specified in the request.

The source objects are unaffected unless you decide to delete them during the composition process.

Cost considerations for temporary objects

If the source objects are meant to be temporary, note the following cost considerations when composing objects:

  • Source objects are subject to minimum storage durations, depending on the storage class, and might incur early deletion fees.

  • If soft delete or Object Versioning is enabled, deleting the source objects after the composition has finished can result in the source objects becoming soft-deleted or noncurrent, which might incur additional storage charges.

  • To minimize billing for temporary objects, hard delete the temporary objects during the composition process by using the deleteSourceObjects option. Objects that are deleted with this option aren't subject to early deletion fees. Also, objects that are deleted with this option aren't preserved by soft delete or Object Versioning because the data is preserved in the composite object.

Required roles

To get the permissions that you need to compose objects, ask your administrator to grant you the Storage Object User (roles/storage.objectUser) IAM role on the bucket. This predefined role contains the permissions required to compose objects. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

  • storage.objects.create
  • storage.objects.delete
    • This permission is only required if you want to give the object you compose the same name as an object that already exists in the bucket.
  • storage.objects.get
  • storage.objects.list
    • This permission is only required if you want to use wildcards to compose objects with a common prefix without having to list each object separately in your Google Cloud CLI command.

If you want to set a retention configuration for the object you compose, you'll also need the storage.objects.setRetention permission. To get this permission, ask your administrator to grant you the Storage Object Admin (roles/storage.objectAdmin) role instead of the Storage Object User (roles/storage.objectUser) role.

You can also get these permissions with other predefined roles or custom roles.

For information about granting roles on buckets, see Set and manage IAM policies on buckets.

Create a composite object

Command line

Use the gcloud storage objects compose command:

gcloud storage objects compose \
    gs://BUCKET_NAME/SOURCE_OBJECT_1 gs://BUCKET_NAME/SOURCE_OBJECT_2 \
    gs://BUCKET_NAME/COMPOSITE_OBJECT_NAME

Where: