Deploying and Retrieving Metadata with the Zip File

The deploy() and retrieve() calls are used to deploy and retrieve a .zip file. Within the .zip file is a project manifest (package.xml) that lists what to retrieve or deploy, and one or more XML components that are organized into folders.

A component is an instance of a metadata type. For example, CustomObject is a metadata type for custom objects, and the MyCustomObject__c component is an instance of a custom object.

Note

The files that are retrieved or deployed in a .zip file might be unpackaged components that reside in your org (such as standard objects) or packaged components that reside within named packages.

You can deploy or retrieve up to 10,000 files at once. AppExchange packages use different limits. In API version 43.0 and 44.0, AppExchange packages can contain up to 12,500 files. In API version 45.0, AppExchange packages can contain up to 17,500 files. In API version 46.0, AppExchange packages can contain up to 22,000 files. In API version 47.0 and later, AppExchange packages can contain up to 30,000 files. The maximum size of the deployed or retrieved .zip file is 39 MB. If the files are uncompressed in an unzipped folder, the size limit is 400 MB.

If using the Ant Migration Tool to deploy an unzipped folder, all files in the folder are compressed first. The maximum size of uncompressed components in an unzipped folder is 400 MB or less depending on the compression ratio. If the files have a high compression ratio, you can migrate a total of approximately 400 MB because the compressed size would be under 39 MB. However, if the components can't be compressed much, like binary static resources, you can migrate less than 400 MB.
Metadata API base-64 encodes components after they’re compressed. The resulting .zip file can't exceed 50 MB, which is the limit for SOAP messages. Base-64 encoding increases the size of the payload, so your compressed payload can't exceed approximately 39 MB before encoding.
You can perform a retrieve() call for a big object only if its index is defined. If a big object is created in Setup and doesn’t yet have an index defined, you can’t retrieve it.

Note

Every .zip file contains a project manifest, a file that’s named package.xml, and a set of directories that contain the components. The manifest file defines the components that you’re trying to retrieve or deploy in the .zip file. The manifest also defines the API version that’s used for the deployment or retrieval.

You can edit the project manifest, but be careful if you modify the list of components it contains. When you deploy or retrieve components, Metadata API references the components listed in the manifest, not the directories in the .zip file.

Note

The following is a sample package.xml file. You can retrieve an individual component for a metadata type by specifying its fullName field value in a members element. You can also retrieve all components of a metadata type by using <members>*</members>.

1<?xml version="1.0" encoding="UTF-8"?>
2<Package xmlns="http://soap.sforce.com/2006/04/metadata">
3    <types>
4        <members>MyCustomObject__c</members>
5        <name>CustomObject</name>
6    </types>
7    <types>
8        <members>*</members>
9        <name>CustomTab</name>
10    </types>
11    <types>
12        <members>Standard</members>
13        <name>Profile</name>
14    </types>
15    <version>48.0</version>
16</Package>

The following elements can be defined in package.xml.

<fullName> contains the name of the server-side package. If no <fullName> exists, the package.xml defines a client-side unpackaged package.
<types> contains the name of the metadata type (for example, CustomObject) and the named members (for example, myCustomObject__c) to be retrieved or deployed. You can add multiple <types> elements in a manifest file.
<members> contains the fullName of the component, for example MyCustomObject__c. The listMetadata() call is useful for determining the fullName for components of a particular metadata type if you want to retrieve an individual component. For many metadata types, you can replace the value in members with the wildcard character * (asterisk) instead of listing each member separately. See the reference topic for a specific type to determine whether that type supports wildcards.
You specify Security in the <members> element and Settings in the name element when retrieving the SecuritySettings component type.
Note
<name> contains the metadata type, for example CustomObject or Profile. There is one name defined for each metadata type in the directory. Any metadata type that extends Metadata is a valid value. The name that’s entered must match a metadata type that’s defined in the Metadata API WSDL. See Metadata Types for a list.
<version> is the API version number that’s used when the .zip file is deployed or retrieved. Currently the valid value is 48.0.

For more sample package.xml manifest files that show you how to work with different subsets of metadata, see Sample package.xml Manifest Files.

To delete components, see Deleting Components from an Organization.

Metadata API Developer Guide

Deploying and Retrieving Metadata with the Zip File

See Also