Query Builder

The Query Builder enables you to select attributes on a node, and to group and evaluate conditions on those attributes or groups of attributes. You can follow relationships from the node and group and evaluate attributes on destination nodes in the same way. This enables you to create a list of nodes fulfilling those criteria. 

For example, you might create a list of hosts running web servers. Additionally, you can traverse from a node, using relationships to other node types, enabling you to create lists of other nodes that are related to the original nodes. For example, starting from the list of web servers mentioned previously, you might create a list of clusters containing web servers. The following example shows this.

The attributes that you select are not limited to those in the taxonomy; you can use attributes created from Technology Knowledge Update (TKU) or your own patterns. To make it easier to find the correct attributes, relationships, and traversals, only the most commonly used are displayed initially. You can reveal all for a node by clicking the Show All link, including attributes starting with a single underscore, for example, _all_cores_per_processor. Clicking Show All does not show attributes starting with a double underscore, such as __all_ip_addrs, though these can be accessed by entering them in the text search box.

To view the Query Builder, click the Customize control under the page title on a list view page.

Three pane selection tool

The three-pane selection tool enables you to select an attribute or follow relationships to other nodes from which you can select attributes. Relationships are displayed with a following right arrow (►). Scroll down the left pane and select the attribute that you require.

How traversal selection works

When you need to traverse to another node type, click the Traverse to link. The traversal selector replaces the three-pane selector. From this, you can select the node type to traverse to and select the relationship to use for the traversal. The following image shows a traversal from a host to a Discovery Access node using a failed access relationship.

SI to SI traversals

The following relationships are among those available when specifying a traversal from Software Instance (SI) to Software Instance:

• Software Instances observed to be communicating with this Software Instance
• Server Software Instances that this Software Instance is communicating with (Client to Server Comms)
• Client Software Instances that are communicating with this Software Instance (Server to Client Comms)
• Peer Software Instances that are communicating with this Software Instance (Peer to Peer Comms)

The last three relationships are explicit, meaning they are built by a discovery for later use; for example, relationships created by patterns that parse application configuration files to find communicating hosts.

The first relationship is pseudo-traversal, based on the communicatingSIs function. While a pseudo-traversal relationship might be useful when relationships corresponding to explicit relationships do not exist, you should use it with caution due to its potential impact on performance. You can create these relationships from the output of commands such as netstat.

The first relationship is available only in the Traverse to dialogue and not the Filter dialogue. You cannot use it for filtering, because it is not a key expression.

Query Viewer

The Query Viewer provides a map of the query that you are constructing. You can evaluate conditions on an attribute or group of attributes using the following conditions:

• All: True when all conditions are true
• Any: True when any of the conditions are true
• None: True when none of the conditions are true

You select these conditions using a selector in the container that holds the attribute or attributes of interest. For example, in the following illustration, two attributes have been selected from the first pane and are grouped with an All condition.

In this example, the OS Class is still being evaluated. A Software Instance has been added by scrolling down the list to Software Instance: Software Instances running on this host when this is clicked, the second pane is populated with the attributes and relationships of Software Instances. The Name attribute has been added to the query viewer by scrolling down the second pane list and clicking Name.

You can also traverse from the host.

To build a query

The following procedure provides an example of how to use the Query Builder to determine which hosts in the organization are web servers. The query should find all Windows hosts running Apache or IIS and all UNIX hosts running Apache.

1. From a host list view, click the Customize control under the page title.
2. Click the Query Constructor tab.
3. From the first pane, select OS Class from the list of host attributes.
   The OS Class attribute is added to the Query Viewer.
4. Type "Windows" in the text entry field and leave the condition entry at contains word.
   In this example, you are initially looking for Windows hosts running IIS and must create a nesting level where this first test can be performed.
5. Click Add Condition in the OS Class row.
   A new container is added; this container will be used to supply the All, Any, or None condition to be evaluated. Before you add a Software Instance, you must ensure that it is added in the correct place.
6. Click in the area of the container you just added to set the focus on the container.
   When selected, the container is highlighted in yellow.
7. Scroll down the first pane and select Software Instance: Software Instances running on this host.
   The second pane is populated with the attributes and relationships of Software Instances.
8. From the second pane, select the Name attribute.
9. In the text entry field, type "IIS" and leave the condition entry at contains word.
10. To display the results in the list view, click Refresh results.
    Now that you have a list of Windows hosts that are running IIS, you must find UNIX hosts running Apache.
11. With the root of the Query Viewer highlighted, select OS Class from the list of host attributes.
    The OS Class attribute is added to the Query Viewer outside the section of the completed query.
12. Type "UNIX" in the text entry field and leave the condition entry at contains word.
13. Click the Add Condition icon in the OS Class row.
    A new container is added; this contain will be used to supply the All, Any, or None condition to be evaluated.
14. Click the container to select it.
15. Scroll down the first pane to Software Instance: Software Instances running on this host.
16. Click the name to populate the second pane with the attributes and relationships of Software Instances.
17. From the second pane, select the Name attribute.
18. Type "Apache" in the text entry field and leave the condition entry at contains word.
19. Change the root condition entry to Any.
20. Click Refresh results to display the results in the list view.
    
    
    
    You know that some of the web servers are on hosts that are members of clusters. To list those clusters, you must traverse to the cluster nodes.
21. Click the Traverse to link.
    The Query Constructor is replaced by a Traverse via Relationship pane.
22. Click Cluster.
    The Traverse via Relationship pane is populated with the available relationships (in this case, the Cluster of which this is a member relationship).
23. Click Refresh results.
    The list of hosts is replaced with a list of clusters of which hosts in the previous hosts list are members, and the Traverse via Relationship panel is replaced with the Query Constructor pane. You can use the Query Constructor pane to filter the result set further.
24. Click Save to save the query.
    You can access saved queries by clicking Saved Queries on the Reports Tab. The list of saved queries is restricted to queries you have created; queries saved by other users are not displayed.
25. To run a query again, click through to the query and selecting Run Query from the Actions menu.