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 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.