All packaged queries and most typed queries return object metadata if it exists for an object in the result set. You can add metadata-specific filter criteria to a query.

To query an object's metadata, add a metadata field specifier to the query. This specifier follows the fields parameter and consists of the string metadata: followed by the name of a metadata key.


Up to eight metadata parameters can be included in a query.


Create the filter expression.


Add a fields parameter that specifies metadata.

The syntax for specifying a metadata field is:

fields=metadata:key-name [, metadata:key-name ] ...

Add a filter expression to the query.

All of the standard filter expressions are supported for metadata queries. In addition, a set of numeric comparisons are available for values of type NUMBER or DATETIME.

Assume that the vApps in your organization have metadata like that shown in Example: Update a Metadata Element. To retrieve a list of all the vApps that have a key named PenTested whose value is false, use a query and filter like this one.




When a filter expression includes metadata, you must encode both the key and the value as described in RFC3986. See Encoding Filter Expressions.