A Data Services client sends a request in the form of a RequestSpec object, which contains a list of QuerySpec objects.
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.
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.
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.
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.
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.
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".