More > Developer Reference > Using APIs > HPE Universal CMDB Web Service API > Query the CMDB

Query the CMDB

The CMDB is queried using the APIs described in UCMDB Query Methods. The queries and the returned CMDB elements always contain real UCMDB IDs. For examples of using query methods, see Query Example.

ClosedJust In Time Response Calculation

For all query methods, the UCMDB server calculates the values requested by the query method when the request is received, and returns results based on the latest data. The result is always calculated at the time the request is received, even if the TQL query is active and there is a previously calculated result. Therefore, the results of running a query returned to the client application may be different from the results of the same query displayed on the user interface.

Tip If your application uses the results of a given query more than once and the data is not expected to change significantly between uses of the result data, you can improve performance by having the client application store the data rather than repeatedly running the query.

ClosedProcessing Large Responses

The response to a query always includes the structures for the data requested by the query method, even if no actual data is being transmitted. For many methods where the data is a collection or map, the response also includes the ChunkInfo structure, comprised of chunksKey and numberOfChunks. The numberOfChunks field indicates the number of chunks containing data that must be retrieved.

The maximum transmission size of data is set by the system administrator. If the data returned from the query is larger than the maximum size, the data structures in the first response contain no meaningful information, and the value of the numberOfChunks field is 2 or greater. If the data is not larger than the maximum, the numberOfChunks field is 0 (zero), and the data is transmitted in the first response. Therefore, in processing a response, check the numberOfChunks value first. If it is greater than 1, discard the data in the transmission and request the chunks of data. Otherwise, use the data in the response.

For information on handling chunked data, see pullTopologyMapChunks and releaseChunks in the UCMDB Module Query Methods topic, and the schema documentation for ChunkInfo.

ClosedSpecifying Properties to Return

CIs and relations generally have many properties. Some methods that return collections or graphs of these items accept input parameters that specify which property values to return with each item that matches the query. The CMDB does not return empty properties. Therefore, the response to a query may have fewer properties than requested in the query.

This section describes the types of sets used to specify the properties to return. For more information, see the documentation on the PropertiesSets schema.

Properties can be referenced in two ways:

  • By their names

  • By using names of predefined properties rules. Predefined properties rules are used by the CMDB to create a list of real property names.

When an application references properties by name, it passes a PropertiesList element.

Tip Whenever possible, use PropertiesList to specify the names of the properties in which you are interested, rather than a rule-based set. The use of predefined properties rules usually results in returning more properties than needed, and incurs a price in performance.

There are two types of predefined properties: qualifier properties and simple properties.

  • Qualifier properties. Use this when the client application should pass a QualifierProperties element (a list of qualifiers that can be applied to properties). The CMDB converts the list of qualifiers passed by the client application to the list of the properties to which at least one of the qualifiers applies. The values of these properties are returned with the CI or Relation elements.

  • Simple properties. To use simple rule-based properties, the client application passes a SimplePredefinedProperty or SimpleTypedPredefinedProperty element. These elements contain the name of the rule by which the CMDB generates the list of properties to return. The rules that can be specified in a SimplePredefinedProperty or SimpleTypedPredefinedProperty element are CONCRETE, DERIVED, and NAMING.

ClosedConcrete Properties

Concrete properties are the set of properties defined for the specified CIT. The properties added by derived classes are not returned for instances of those derived classes.

A collection of instances returned by a method may consist of instances of a CIT specified in the method invocation and instances of CITs that inherit from that CIT. The derived CITs inherit the properties of the specified CIT. In addition, the derived CITs extend the parent CIT by adding properties.

Example of Concrete Properties:

CIT T1 has properties P1 and P2. CIT T11 inherits from T1 and extends T1 with properties P21 and P22.

The collection of CIs of type T1 includes the instances of T1 and T11. The concrete properties of all instances in this collection are P1 and P2.

ClosedDerived Properties

Derived properties are the set of properties defined for the specified CIT and, for each derived CIT, the properties added by the derived CIT.

Example of Derived Properties:

Continuing the example from concrete properties, the derived properties of instances of T1 are P1 and P2. The derived properties of instances of T11 are P1, P2, P21, and P22.

ClosedNaming Properties

The naming properties are display_label and data_name.

ClosedOther Property Specification Elements

  • PredefinedProperties

    PredefinedProperties can contain a QualifierProperties element and a SimplePredefinedProperty element for each of the other possible rules. A PredefinedProperties set does not necessarily contain all types of lists.

  • PredefinedTypedProperties

    PredefinedTypedProperties is used to apply a different set of properties to each CIT. PredefinedTypedProperties can contain a QualifierProperties element and a SimpleTypedPredefinedProperty element for each of the other applicable rules. Because PredefinedTypedProperties is applied to each CIT individually, derived properties are not relevant. A PredefinedProperties set does not necessarily contain all applicable types of lists.

  • CustomProperties

    CustomProperties can contain any combination of the basic PropertiesList and the rule-based property lists. The properties filter is the union of all the properties returned by all the lists.

  • CustomTypedProperties

    CustomTypedProperties can contain any combination of the basic PropertiesList and the applicable rule-based property lists. The properties filter is the union of all the properties returned by all the lists.

  • TypedProperties

    TypedProperties is used to pass a different set of properties for each CIT. TypedProperties is a collection of pairs composed of type names and properties sets of all types. Each properties set is applied only to the corresponding type.