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.

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.

Assume that the system administrator adds metadata specifying an expiry date and a priority rank to every organization in a cloud. The key name for the expiry date is expiry, and its value expressed as a MetadataDateTimeValue. The key name for the rank is rank, and its value is expressed as a MetadataNumberValue. The following query includes a fields parameter specifying those metadata keys by name.

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.

Request:

GET https://vcloud.example.com/api/query?type=organization&format=records&fields=metadata:rank,metadata@SYSTEM:expiry"

The response includes an OrgRecord for each organization in the cloud. Each OrgRecord includes a Metadata element that contains MetadataEntry elements for each of the requested keys.

Response:

<QueryResultRecords
   xmlns="http://www.vmware.com/vcloud/v1.5"
   total="3"
   pageSize="25"
   page="1"
   ...
    <OrgRecord
      storedVMQuota="0"
      numberOfVdcs="5"
      ...
      href="https://vcloud.example.com/api/org/70"
      numberOfRunningVMs="3">
      <Metadata>
         <MetadataEntry>
            <Domain
               visibility="PRIVATE">SYSTEM</Domain>
            <Key>expiry</Key>
            <TypedValue
               xsi:type="MetadataDateTimeValue">
               <Value>2012-05-01T00:00:00.000-04:00</Value>
            </TypedValue>
         </MetadataEntry>
         <MetadataEntry>
            <Key>rank</Key>
            <TypedValue
               xsi:type="MetadataNumberValue">
               <Value>1</Value>
            </TypedValue>
         </MetadataEntry>
      </Metadata>
   </OrgRecord>
   <OrgRecord
      storedVMQuota="0"
      numberOfVdcs="2"
      ...
      href="https://vcloud.example.com/api/org/77"
      numberOfRunningVMs="0">
      <Metadata>
         <MetadataEntry>
            <Key>expiry</Key>
            <TypedValue
               xsi:type="MetadataDateTimeValue">
               <Value>2012-06-01T00:00:00.000-04:00</Value>
            </TypedValue>
         </MetadataEntry>
         <MetadataEntry>
            <Key>rank</Key>
            <TypedValue
               xsi:type="MetadataNumberValue">
               <Value>2</Value>
            </TypedValue>
         </MetadataEntry>
      </Metadata>
   </OrgRecord>
</QueryResultRecords>

To filter the query result set so that it contains only those organizations whose expiry date is later than May 1, 2012, add a filter for the expiry value, as this example shows.

Request:

GET https://vcloud.example.com/api/query?type=organization&format=records&fields=metadata:rank,metadata@SYSTEM:expiry"
&filter="metadata@SYSTEM:expiry=lt=DATETIME:2012-05-01T00:00:00.000-04:00

Response:

<QueryResultRecords
   xmlns="http://www.vmware.com/vcloud/v1.5"
   total="3"
   pageSize="25"
   page="1"
   ...
   <OrgRecord
      storedVMQuota="0"
      numberOfVdcs="2"
      ...
      href="https://vcloud.example.com/api/org/77"
      numberOfRunningVMs="0">
      <Metadata>
         <MetadataEntry>
            <Key>expiry</Key>
            <TypedValue
               xsi:type="MetadataDateTimeValue">
               <Value>2012-06-01T00:00:00.000-04:00</Value>
            </TypedValue>
         </MetadataEntry>
         <MetadataEntry>
            <Key>rank</Key>
            <TypedValue
               xsi:type="MetadataNumberValue">
               <Value>2</Value>
            </TypedValue>
         </MetadataEntry>
      </Metadata>
   </OrgRecord>
</QueryResultRecords>
Note

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