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.

Sorted by database ID

sortDesc=attribute-name

Sort results by attribute-name in descending order. attribute-name cannot include metadata.

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

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.

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

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. Use the schema reference to find the attribute names included in a particular result set. For most queries, the name of the element that holds a result is derived form the name and format of the query. For example, the result of an adminGroup query in records format is an AdminGroupRecord element. You can search for result set elements by entering the element name in the Quick Index window. For each result set element, the reference page includes a table of attribute names, with their types and descriptions.