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

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

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.

sortAsc=attribute-name

Sort results by attribute-name in ascending order. attribute-name cannot include metadata. See the vCloud API Schema Reference for infomation about which attributes can be used with sortDesc.

Sorted by database ID

sortDesc=attribute-name

Sort results by attribute-name in descending order. attribute-name cannot include metadata. See the vCloud API Schema Reference for infomation about which attributes can be used with sortDesc.

Sorted by database ID

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

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

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.

offset

Integer value specifying the first record to return. Record numbers < offset are not returned.

offset=0

filterEncoded

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

filterEncoded=false

filter

Filter expression. See Query Filter Expressions

None

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.

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

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

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)

Several parameters and all filter expressions require you to specify an attribute name. You can use the schema reference to find the attribute names included in a particular result set.

1

In the vCloud API Schema Reference, select All Queries.

2

Type the query name (or any part of it) in the Quick Index window, then open the query reference page.

3

On the query reference page, click the link in the Record Result section 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 sortAsc or sortDesc have a YES in the SORT column.