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.

Note

You must use a metadata@SYSTEM parameter to specify metadata keys in the SYSTEM domain. Metadata in the GENERAL domain does not require a qualifier. Up to eight metadata parameters can be included in a query.

Procedure
1

Create the filter expression.

2

Add a fields parameter that specifies metadata.

The syntax for specifying a metadata field is: 

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

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.

Example: A Query With a Metadata Filter

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.

Request: 

GET https://vcloud.example.com/api/query?type=vApp&format=records
&fields=metadata:PenTested&filter="metadata:PenTested==false"

Note

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

Related tasks