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.

In the schema reference, find your query, then open the query reference page.
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.