QueryDefinition (api-interfaces 11.6.11.220 API)

All Superinterfaces:: BundledResource<QueryDefinition>

public interface QueryDefinition
extends BundledResource<QueryDefinition>

Definition of a UCMDB TQL query.

Examples of simple queries:

Query host CIs by list of IDs.
```
 QueryDefinition queryDefinition =
      topologyQueryFactory.createQueryDefinition("Get Hosts by IDs");
 QueryNode queryNode = queryDefinition.addNode("Hosts").ofType("host").withIds(ids);
 queryNode.queryPropertiesWithQualifier("COMPARABLE").queryProperties("host_key", "host_iscomplete"); 
```
Full description: Retrieve all CIs of type "host" or a descendant type, using "ids". ids is assumed as a parameter for the code. Also retrieves all properties marked "comparable" and the properties "host_key" and "host_iscomplete" for all CIs in the result topology.

Query CIs by their properties

 QueryDefinition queryDefinition =
      topologyQueryFactory.createQueryDefinition("Get Hosts");
 QueryNode queryNode = queryDefinition.addNode("Hosts").ofType("host");
 queryNode.property("host_key").like("T%").caseInsensitive();
 queryNode.property("host_iscomplete").isNull();
 queryNode.queryKeyProperties();

Full description: Retrieve all CIs of type "host" or a descendant where:

A "host_key" property starts with "T" ('%' is used as a wildcard), case insensitive.
A "host_iscomplete" property is empty.

Also retrieves all key properties of the CIs in the result topology.

Query CIs' neighbors

 QueryDefinition queryDefinition =
      topologyQueryFactory.createQueryDefinition("Get hosts' neighbors");
 QueryNode cisNode =
      queryDefinition.addNode("CIs").ofType("host").withIdsOf(hosts_ids).invisible();
 QueryNode neighborsNode = queryDefinition.addNode("Neighbors").ofType("configuration_item");
 neighborsNode.queryKeyProperties();
 cisNode.linkedTo(neighborsNode).ofITWorldType().invisible();

Full description: Retreive all CIs that are neighbours if hosts with the given ids. host_ids assumed as a parameter the code. Both the host CIs and the link between the hosts and their neighbours are invisible - they do not return in the result topology. Also retrieves the key property for these neighbours CIs.

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`QueryNode`	`addNode(String nodeName)` Adds a new node to the query.
`QueryNode`	`addNode(String nodeName, Integer nodeNumber)`
`String`	`baseQueryName()`
`QueryResultConsumingType`	`consumingType()` Returns the setting for the consuming type and notification setting of the query..
`String`	`debugDescription()` Returns a human-readable full description of this query definition to be used debugging the query definition.
`String`	`description()`
`QueryDefinitionFirstLoadStrategy`	`firstLoadStrategy()` Returns the setting for when a saved query should first be loaded and calculated.
`QueryLink`	`getLink(String linkName)` Returns the query link with the specified name or null if node does not exist.
`QueryNode`	`getNode(String nodeName)` Returns the node with the specified name or null if node does not exist.
`Map<String,? extends QueryLink>`	`links()` Returns the links defined in this query as a map of names to links.
`String`	`name()`
`Map<String,? extends QueryNode>`	`nodes()` Returns the nodes defined in this query as a map of names to nodes.
`QueryDefinitionRecalcPriority`	`recalcPriority()` Returns the setting for how soon a saved query is recalculated after data change.
`boolean`	`removeLink(String linkName)` Removes the named link from this query definition.
`boolean`	`removeNode(String nodeName)` Removes the named node from this query definition.
`ExecutableQuery`	`toExecutable()` Converts this query definition into an executable query object for passing to `TopologyQueryService.executeQuery(ExecutableQuery)`.
`QueryDefinition`	`withBaseQueryName(String baseQueryName)` Sets this query to run over the result of another query.
`QueryDefinition`	`withDescription(String description)` Sets a human-readable description of the query definition purpose.
`QueryDefinition`	`withFirstLoadStrategy(QueryDefinitionFirstLoadStrategy firstLoadStrategy)` Sets when a saved query should first be loaded and calculated.
`QueryDefinition`	`withFullyCachedStoring()` Sets how a query should be saved and which of notifications are required.
`NonCachedQueryResultConsumingType`	`withNonCachedStoring()` Sets that a query result will not be cached in result-repository Note: The default behavior for saved query id FULLY-CACHED.
`PartiallyCachedQueryResultConsumingType`	`withPartiallyCachedStoring()` Sets that a query result will not be partially cached in result-repository.
`QueryDefinition`	`withRecalcPriority(QueryDefinitionRecalcPriority recalcPriority)` Sets how soon a saved query is recalculated after data change.

Methods inherited from interface com.hp.ucmdb.api.bundles.BundledResource
bundleNames, withBundles

- Method Detail
  - name
```
String name()
```
    Returns:
    
    The name of the query definition.
  - description
```
String description()
```
    Returns:
    
    A human-readable description of the query definition purpose.
  - withDescription
```
QueryDefinition withDescription(String description)
```
    Sets a human-readable description of the query definition purpose.
    
    Parameters:
    
    description - the description.
    
    Returns:
    
    this object for method chaining.
  - addNode
```
QueryNode addNode(String nodeName)
```
    Adds a new node to the query. The resulting object can be used for specifying conditions on IDs, properties, and links, and for specifying which properties are queried for the CIs matched.
    The type of the node must be specified or the query is invalid. Specify the type with the ofType or the strictlyOfType method.
    
    Parameters:
    
    nodeName - name of this node. The name must be unique in this query.
  - addNode
```
QueryNode addNode(String nodeName,
                  Integer nodeNumber)
```
  - getNode
```
QueryNode getNode(String nodeName)
```
    Returns the node with the specified name or null if node does not exist.
  - getLink
```
QueryLink getLink(String linkName)
```
    Returns the query link with the specified name or null if node does not exist.
  - nodes
```
Map<String,? extends QueryNode> nodes()
```
    Returns the nodes defined in this query as a map of names to nodes.
  - links
```
Map<String,? extends QueryLink> links()
```
    Returns the links defined in this query as a map of names to links.
  - toExecutable
```
ExecutableQuery toExecutable()
```
    Converts this query definition into an executable query object for passing to TopologyQueryService.executeQuery(ExecutableQuery).
  - recalcPriority
```
QueryDefinitionRecalcPriority recalcPriority()
```
    Returns the setting for how soon a saved query is recalculated after data change.
  - withRecalcPriority
```
QueryDefinition withRecalcPriority(QueryDefinitionRecalcPriority recalcPriority)
```
    Sets how soon a saved query is recalculated after data change.
    Note: This is relevant only to saved queries. Query definitions that are executed ad-hoc ignore this parameter.
    The default is QueryDefinitionRecalcPriority.LOW.
  - firstLoadStrategy
```
QueryDefinitionFirstLoadStrategy firstLoadStrategy()
```
    Returns the setting for when a saved query should first be loaded and calculated.
  - withFirstLoadStrategy
```
QueryDefinition withFirstLoadStrategy(QueryDefinitionFirstLoadStrategy firstLoadStrategy)
```
    Sets when a saved query should first be loaded and calculated.
    Note: This is relevant only to saved queries. Query definitions that are executed ad-hoc ignore this parameter.
    The default is QueryDefinitionFirstLoadStrategy.LOAD_ON_FIRST_REQUEST.
  - consumingType
```
QueryResultConsumingType consumingType()
```
    Returns the setting for the consuming type and notification setting of the query..
  - withFullyCachedStoring
```
QueryDefinition withFullyCachedStoring()
```
    Sets how a query should be saved and which of notifications are required.
    Note: This is relevant only to saved queries. Query definitions that are executed ad-hoc ignore this parameter.
  - withNonCachedStoring
```
NonCachedQueryResultConsumingType withNonCachedStoring()
```
    Sets that a query result will not be cached in result-repository
    Note: The default behavior for saved query id FULLY-CACHED. Use this option to avoid memory issues in case of very large queries. Notice that this will cause overhead to query calculation process.
    
    Note: This is relevant only to saved queries. Query definitions that are executed ad-hoc ignore this parameter.
  - withPartiallyCachedStoring
```
PartiallyCachedQueryResultConsumingType withPartiallyCachedStoring()
```
    Sets that a query result will not be partially cached in result-repository. This setting enables you to define which elements in the query will be cached and which will not be cached.
    Note: The default behavior for saved query id FULLY-CACHED. Use this option to avoid memory issues in case of very large queries. Notice that this will cause overhead to query calculation process.
    
    Note: This is relevant only to saved queries. Query definitions that are executed ad-hoc ignore this parameter.
  - debugDescription
```
String debugDescription()
```
    Returns a human-readable full description of this query definition to be used debugging the query definition.
    
    Returns:
    
    the full description of this query definition.
  - withBaseQueryName
```
@NotFinalAPI
QueryDefinition withBaseQueryName(String baseQueryName)
```
    Sets this query to run over the result of another query. The scope of the query is not the whole universe but over the subset defined by the a result of another query.
    Limitations (not final):
    - The base query must have been calculated and a result exists in the result repository before this query definition can be saved or executed. This forces the base query to be active and, unless special measures are taken, it is loaded on server start.
    - This query must be loaded on server start. This flag will be set automatically when calling this method.
    - You cannot change the base query name of an already saved query.
    These limitations do not affect ExecutableQuery#onTopOfQuery.
    If a value is set with ExecutableQuery#onTopOfQuery, it overrides the value set here.
    Parameters:
    
    baseQueryName - name of the query that specifies the "universe" for this query to run on, or null to disable this feature. May not be empty string.
    
    Returns:
    
    this object for method chaining.
    
    See Also:
    
    ExecutableQuery.onTopOfQuery(java.lang.String)
  - baseQueryName
```
@NotFinalAPI
String baseQueryName()
```
    Returns:
    
    the base query name for this query definition, or null if no base query was set.
    
    See Also:
    
    withBaseQueryName(String)
  - removeLink
```
@NotFinalAPI
boolean removeLink(String linkName)
```
    Removes the named link from this query definition.
    This method also removes the link from all query link conditions on all nodes.
    
    Parameters:
    
    linkName - the name of the link to remove.
    
    Returns:
    
    true on removal success. false if a link by the given name was not found.
  - removeNode
```
@NotFinalAPI
boolean removeNode(String nodeName)
```
    Removes the named node from this query definition.
    This method also removes all of the node's attached links.
    
    Parameters:
    
    nodeName - the name of the node to remove.
    
    Returns:
    
    true on removal success. false if there is no node with the specified name.

Interface QueryDefinition

Method Summary

Methods inherited from interface com.hp.ucmdb.api.bundles.BundledResource

Method Detail

name

description

withDescription

addNode

addNode

getNode

getLink

nodes

links

toExecutable

recalcPriority

withRecalcPriority

firstLoadStrategy

withFirstLoadStrategy

consumingType

withFullyCachedStoring

withNonCachedStoring

withPartiallyCachedStoring

debugDescription

withBaseQueryName

baseQueryName

removeLink

removeNode