RequestSpec Data Structure in Data Service Queries

A Data Services client sends a request in the form of a
RequestSpec
object, which contains a list of
QuerySpec
objects.

QuerySpec Structure

The
name
field of a
QuerySpec
is optional. You can assign a name of your choosing, to help you identify the corresponding results. The
name
field is also useful to troubleshoot custom data providers.
A
QuerySpec
also contains a
ResourceSpec
and a
ResultSpec
.

ResourceSpec

The
ResourceSpec
specifies what properties and what objects are to be returned. It contains a list of
PropertySpec
objects and a tree of
Constraint
objects. The
PropertySpec
objects select resources and their properties, while the
Constraint
objects enable you to construct Boolean combinations of conditions to filter the set of resources from which properties are returned.

ResultSpec

The
ResultSpec
, which is optional, enables you to sort the results and to specify a chunk length and a starting index for the
ResultSet
.
The
OrderingCriteria
is a list of
OrderingPropertySpec
. Each list entry specifies the name of a sortable property and whether to sort the values in ascending or descending order.
OrderingPropertySpec
is a subclass of
PropertySpec
. The subclass adds a
SortType
field.
Sorting on custom properties can degrade performance in the client.

PropertySpec

A
PropertySpec
object is used to identify the properties to return in the
ResultSet
, or the properties used for sorting the results. In the latter usage, you can specify an optional sort order for the property by supplying an instance of
OrderingPropertySpec
, which is a subclass of
PropertySpec
. A
PropertySpec
is required in the
ResourceSpec
, but
OrderingPropertySpec
is optional.
A
PropertySpec
begins with a
type
field which contains the name of a resource type. This is typically the URI of a custom resource type, or the name of a managed object type in the case of a query that joins data across vCenter Servers. For example, to request properties of a
VirtualMachine
managed object, you must set the
type
field of a
PropertySpec
object to
"VirtualMachine"
.
A
PropertySpec
contains an array of strings identifying properties to be returned in the
ResultSet
. To identify nested properties, such as properties of nested data objects, use a period as delimiter. For example, the name of a virtual machine config file is a property of the
files
data object, which is a property of the
config
data object, which is a property of the
VirtualMachine
managed object, so you identify the chosen property with the string
"config.files.vmPathName"
.
To access properties of related resources or managed objects, such as the name of the host on which a virtual machine is currently running, use a
Constraint
object to do a join operation between the two managed object types.
The
relation
field and the
ParameterSpec
array contained in the
propertySpec
object are reserved for internal use.

Constraint

Constraint
objects enable you to specify arbitrary Boolean expressions that filter the results of your query. You can limit the results by placing conditions on property values and object identities. Your query must include a
Constraint
object.
Constraint
is an abstract class with four subclasses. You can supply a simple constraint of object identity or property value by using an
ObjectIdentityConstraint
object or a
PropertyConstraint
object. You can use a
RelationalConstraint
object to join data across resource types.
You can use a
CompositeConstraint
wherever a
Constraint
object is allowed. A
CompositeConstraint
enables you to combine a list of other constraint objects, joined by a Boolean operator. You can nest a
CompositeConstraint
within another
CompositeConstraint
, which enables you to create arbitrarily complex Boolean expressions.
A query can contain the following types of constraints, each of which is a subclass of the base
Constraint
class.
  • ObjectIdentityConstraint
    - Queries based on this constraint retrieve the properties of a known target object. For example, a query might retrieve the powered-on state of a given virtual machine. The object identifier can be a managed object type or any custom type that implements the
    IResourceReference
    interface. The identifier in this constraint includes the server GUID.
  • PropertyConstraint
    - Queries based on this constraint retrieve all objects with a given property value. For example, a query might retrieve all virtual machine objects with a power state of on. This constraint accepts the property name and comparator as strings, and the property value as an
    Object
    . This constraint is not bound to a specific server, and can be used to retrieve results from all vCenter Servers known to the client.
  • RelationalConstraint
    - Queries based on this constraint retrieve all objects that match the specified relationship with a given object. For example, a query might retrieve all virtual machine objects related to a given host object. The identifier in this constraint includes the server GUID.
  • CompositeConstraint
    - Composite queries allow the combination of multiple constraints using the
    and
    or
    or
    operator, passed as a string. The combined subconstraints in
    CompositeConstraint
    are contained in an array of
    Constraint
    objects.
Each constraint operates relative to a resource type that you specify in its
targetType
field. For instance, if you want to query the names of all virtual machines running on a given host, one way is to create a
PropertyConstraint
that specifies a
targetType
of
"HostSystem"
and a value for the
name
property, then nest that
PropertyConstraint
in the
Constraint
field of a
RelationalConstraint
that specifies a
targetType
of
"VirtualMachine"
and a
relation
field of
"runtime.host"
.