Query Service Overview

The Query Service is a generic service for listing or filtering large sets of results.

Using the Query Service

The query service supports two types of querying: paged and virtual list.

• A paged query creates a cursor for iterating though query results efficiently. Subsequent pages can be retrieved by requesting the next page from the server. This query type consumes resources on the server to track the query state. The query should be explicitly deleted when it is no longer needed to free the server resources. If a query is never deleted, it will expire after a predefined time and the server will reclaim the resources.
  • To use the paging model, create a query with the QueryService_Create method, get successive results with the QueryService_GetNext method, then release server-side resources with the QueryService_Delete method.

  Note: only 5 active paged queries can exist at a time on a single connection. Attempting to create additional queries when that limit is reached will result in an error.

• A virtual list query will only return one page of results to the client and will not consume any server resources after returning the results. If more results are desired these can be retrieved by modifying the result controls, but successive queries may be significantly less performant as a result.
  • To use the "virtual list" model, use the QueryService_Query method to get one page of results at the offset of your choice.

Filtering

The Query Service provides the ability to filter on properties of the resulting data object. The exact list of supported filters is detailed in the left pane. Further restrictions on which properties can be used as part of a filter will be specified as part of the documentation on that specific data object or the specific filter. Not all fields can be used to filter. In particular, the "id" field of any data object cannot be used as a field to filter upon.

Result controls

There are various types of controls that can be used to control the result set. These are documented in the QueryDefinition.

Examples

Here are a few examples of using the Query Service.

Example: Enumerating all Farms

This example demonstrates how to handle the results from the QueryResults object. This will be omitted in the remaining examples.

$queryService = New-Object VMware.Hv.QueryServiceService
$defn = New-Object VMware.Hv.QueryDefinition
$defn.queryEntityType = 'FarmSummaryView'
$queryResults = $queryService.QueryService_Create($hvServices, $defn)

# Handle results
try {
   while ($queryResults.results -ne $null) {
      foreach ($result in $queryResults.Results) {
         [VMware.Hvi.FarmSummaryView]$farmSummaryView = $result
         # Do work.
      }

      # Fetch next page
      if ($queryResults.id -eq $null) {
         break;
      }
      $queryResults = $queryService.QueryService_GetNext($hvServices, $queryResults.id)
   }
} finally {
   if ($queryResults.id -ne $null) {
      $queryService.QueryService_Delete($hvServices, $queryResults.id)
   }
}

Example: List enabled RDS Servers

$queryService = New-Object VMware.Hv.QueryServiceService
$defn = New-Object VMware.Hv.QueryDefinition
$defn.queryEntityType = 'RDSServerInfo'
defn.setFilter = New-Object VMware.Hv.QueryFilterEquals -property @{'memberName'='settings.enabled'; 'value' ='$true'}
$queryResults = $queryService.QueryService_Create($hvServices, $defn)
# Handle results

Example: List desktops (by name in descending order)

$queryService = New-Object VMware.Hv.QueryServiceService
$defn = New-Object VMware.Hv.QueryDefinition
$defn.queryEntityType = 'DesktopSummaryView'
$defn.sortBy = 'desktopSummaryData.name'
$defn.sortDescending = $true
QueryResults queryResults = queryService.create($hvServices, $defn);
# Handle results

Example: Virtual List query

This example will retrieve the third page of 10 ApplicationInfo objects, without needing to access the first two pages.

$queryService = New-Object VMware.Hv.QueryServiceService
$defn = New-Object VMware.Hv.QueryDefinition
$defn.queryEntityType = 'ApplicationInfo'
$defn.startingOffset = 20
$defn.limit = 10
$queryResults = $queryService.QueryService_Query($hvServices, $defn)

# Handle results.  Don't need to delete query as there is no server side clean-up needed.

Example: Count persistent disks with names starting with "a"

QueryDefinition defn = new QueryDefinition();
$queryService = New-Object VMware.Hv.QueryServiceService
$defn = New-Object VMware.Hv.QueryDefinition
$defn.queryEntityType = 'PersistentDiskInfo'
defn.setFilter = New-Object VMware.Hv.QueryFilterStartsWith -property @{'memberName'='general.name'; 'value' ='a'}
$count = $queryService.QueryService_GetCount($hvServices, $defn)