Query Parameters

Query parameters specify result set properties such as pagination, sort order, and filter criteria.

Query Parameters

Entered queries must include a type parameter, which specifies the type of query to run. Packaged queries cannot specify a type parameter. All other parameters are optional. If a parameter is omitted, a default value is assumed.

Table 1. Query Parameters
Parameter Name Parameter Description Default
fields Comma-separated list of attribute names or metadata key names to return. For example, fields=name,isEnabled or fields=metadata:rank. See Specifying Metadata in a Query or a Filter Expression. Returns all static attribute names. Returns metadata only if the object has a non-empty Metadata element.
filter Filter expression. The filter expression must always be encoded to comply with RFC3986 (pct-encoded). If your filter values contain special characters, such as ( ) , ; \, you must escape the special characters with a backslash (\). For example, in filter=name==VM\,1, the name to search for is VM,1, and in filter=name==VM\,%201, the name to search for is VM, 1 because it has both encoded and escaped characters. See Query Filter Expressions and Encoding Filter Expressions. None
format One of the following types:
references
Returns a reference to each object, including its name, type, and href attributes.
records
Returns all database records for each object, with each record as an attribute.
idrecords
Identical to the records format, except that object references are returned in id format rather than href format.
format=records
links Boolean value specifying whether to include Link elements in the result set for certain object types. links=false
offset Integer value specifying the first record to return. Record numbers < offset are not returned. offset=0
page If the query results span multiple pages, return this page. page=1
pageSize Number of results per page, to a maximum of 128. pageSize=25
sortAsc=attribute-name Sort results by attribute-name in ascending order. attribute-name cannot include metadata. For information about the attributes that can be used with sortAsc, see Attribute Names and Values. Sorted by database ID
sortDesc=attribute-name Sort results by attribute-name in descending order. attribute-name cannot include metadata. For information about the attributes that can be used with sortDesc, see Attribute Names and Values. Sorted by database ID
type The type of the query. Type names are case-sensitive. See Query Types. None. This parameter is required for all typed queries, and is not allowed for any packaged query.

Filter Expressions

For queries that do not examine object metadata, you can filter results using string matching or numeric comparison operations. A filter comprises one or more subexpressions drawn from the following set of operators.

Table 2. Query Filter Expressions
Operator Example Operation
== attribute==value Matches. The example evaluates to true if attribute has a value that matches value in a case-sensitive comparison.
Note: Asterisk (*) characters that appear anywhere in value are treated as wildcards that match any character string. When value includes wildcards, the comparison with attribute becomes case-insensitive.
!= attribute!=value Does not match. The example evaluates to true if attribute has a value that does not match value in a case-sensitive comparison. Wildcard characters are not allowed. You must include filterEncoded=true when adding a filter that includes an inequality check.
; attribute1==value1;attribute2!=value2 Logical AND. The example evaluates to true only if attribute1 has a value that matches value1 and attribute2 has a value that does not match value2 in a case-sensitive comparison.
, attribute1==value1,attribute2==value2 Logical OR. The example evaluates to true if attribute1 has a value that matches value1 or attribute2 has a value that matches value2 in a case-sensitive comparison.
=gt= attribute=gt=value Greater than. The example evaluates to true if attribute has a value that is greater than value. Both attribute and value must be of type int, long, or dateTime.
=lt= attribute=lt=value Less than. The example evaluates to true if attribute has a value that is less than value. Both attribute and value must be of type int, long, or dateTime.
=ge= attribute=ge=value Greater than or equal to. The example evaluates to true if attribute has a value that is greater than or equal to value. Both attribute and value must be of type int, long, or dateTime.
=le= attribute=le=value Less than or equal to. The example evaluates to true if attribute has a value that is less than or equal to value. Both attribute and value must be of type int, long, or dateTime.

Not all attributes can be used in a filter expression. For details, see the reference pages for query result types in the VMware Cloud Director API Schema Reference.

Specifying Metadata in a Query or a Filter Expression

Because metadata values are dynamic and metadata names have an optional domain qualifier queries that filter metadata must specify a qualified name, a value, and the type of the value.

  • The domain must be specified for any MetadataEntry that is in the SYSTEM domain. If no DOMAIN is specified, the query returns the value for key name in the GENERAL domain, if it exists.
  • The type of the value must be specified, using one of the following keywords.
    Table 3. Metadata Type Specifiers in Query Filters
    Type Name as Specified in TypedValue Type Name as a Filter Expression Keyword
    MetadataStringValue STRING
    MetadataNumberValue NUMBER
    MetadataDateTimeValue DATETIME
    MetadataBooleanValue BOOLEAN

For queries that examine object metadata, you can filter query results using numeric comparison operations when a metadata value has type NUMBER or DATETIME. Because object metadata types are dynamic, filter expressions for metadata queries require additional parameters that define the attribute part of the expression as metadata, and specify the type of the value part of the expression.

Table 4. Metadata Query Filter Expressions
Operator Example Operation
=gt= metadata:attribute=gt=[NUMBER | DATETIME]:value Greater than. The example evaluates to true if value is of type NUMBER or DATETIME and the value of the metadata key named attribute is greater than value.
=lt= metadata:attribute=lt=[NUMBER | DATETIME]:value Less than. The example evaluates to true if value is of type NUMBER or DATETIME and the value of the metadata key named attribute is less than value.
=ge= metadata:attribute=ge=[NUMBER | DATETIME]:value Greater than or equal to. The example evaluates to true if value is of type NUMBER or DATETIME and the value of the metadata key named attribute is greater than or equal to value.
=le= metadata:attribute=le=[NUMBER | DATETIME]:value Less than or equal to. The example evaluates to true if value is of type NUMBER or DATETIME and the value of the metadata key named attribute is less than or equal to value.

You can specify up to 8 metadata fields in a single query. You cannot use a metadata value as a sort key when sorting query output.

The syntax for specifying metadata in a fields parameter is: 
fields=metadata[@SYSTEM]:key-name
For example: 
fields=metadata:rank
fields=metadata@SYSTEM:expiry
The syntax for specifying a metadata field in a filter expression is: 
metadata[@SYSTEM]:key-name operator type-keyword:value
For example: 
metadata:rank=ge=NUMBER:1
metadata@SYSTEM:expiry=le=DATETIME:2012-06-18T12:00:00-05:00

Encoding Filter Expressions

When you are comparing a key with a literal value that includes characters that might be subject to interpretation when used in a URL (often termed unsafe characters), the value must be encoded as described in RFC3986 (pct-encoded). For example, to create a filter expression to match a hostName property whose value is 12&345, encode the value as shown here: 
filter=hostName==12%26345

When a filter expression includes metadata, you must encode both the key and the value this way. In queries, you must encode the % symbol as %25. For example, this query, which includes metadata, would require this sort of additional encoding. 

https://vcloud.example.com/api/query?
type=organization&format=records
&fields=metadata:rank,metadata@SYSTEM:expiry
&filter=metadata%40SYSTEM%3Aexpiry%3Dlt%3DDATETIME%3ADATETIME%253A2012-05-01T00%253A00%253A00.000-04%253A00DATETIME%253A2012-05-01T00%253A00%253A00.000-04%253A00

Grouping Filter Subexpressions

Group filter subexpressions with parentheses. Separate grouped subexpressions with a semicolon (no spaces). 

(attribute1==value1;attribute2!=value2);(attribute3==value3;attribute4!=value4)...
For example: 
https://vcloud.example.com/api/query?type=providerVdcResourcePoolRelation&format=records&filter=(numberOfVMs!=0;isPrimary==true)

Attribute Names and Values

Several parameters and all filter expressions require you to specify an attribute name. To understand the attribute names included in a particular result set, you can use the VMware Cloud Director API Schema Reference available at https://code.vmware.com.
  1. In the schema reference, find your query, then open the query reference page.
  2. In the Record Result section, click the link to open a page that shows the name, type, description, and other information for each attribute returned by the query.

    Attributes that can be used in a filter expression have a YES in the FILTER column.

    Attributes that can be used with the sortAsc or sortDesc parameter have a YES in the SORT column.