Query Parameters

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

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. See Query Filter Expressions

None

filterEncoded

Specify whether the filter expression is encoded as described in RFC3986 (pct-encoded). See Encoding Filter Expressions

filterEncoded=false

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.

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.
;	`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 vCloud 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.

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.

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 addition, if you specify filterEncoded=true as part of a query that includes metadata, you must encode the % symbol as %25. For example, this query, which includes metadata would require this sort of additional encoding if you specified filterEncoded=true.

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&filterEncoded=true

If you did not specify filterEncoded=true, you would not need the additional encoding.


https://vcloud.example.com/api/query?
type=organization&format=records
&fields=metadata:rank,metadata@SYSTEM:expiry
&filter=metadata@SYSTEM:expiry=lt=DATETIME:DATETIME%3A2012-05-01T00%3A00%3A00.000-04%3A00

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