Package com.hp.ucmdb.api.topology

Interface QueryDefinition

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:
    1. A "host_key" property starts with "T" ('%' is used as a wildcard), case insensitive.
    2. 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 Details

    • 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:

    • baseQueryName

      @NotFinalAPI String baseQueryName()
      Returns:
      the base query name for this query definition, or null if no base query was set.
      See Also:

    • 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.