Thank you for your feedback.
Form temporarily unavailable. Please try again or contact docfeedback@servicenow.com to submit your comments.

Build a CMDB query using the CMDB Query Builder

Log in to subscribe to topics and get notified when content changes.

Build a CMDB query using the CMDB Query Builder

A CMDB query type queries the infrastructure for CI classes and optionally a non-CMDB table, and the relationships and references that connect them.

Before you begin

The UI16 plugin (com.glide.ui.ui16) must be activated.

Role required: cmdb_query_builder_read to only view and run saved queries, and cmdb_query_builder (contained for itil, itil_admin, and asset) to create and save queries, modify saved queries, and run queries.

Authorized users can update and delete a query created by another user.

About this task

Build the query by dragging the CI classes and a non-CMDB table that you want to include in the query. Then dropping them as nodes on the canvas, and defining relationship properties between them. You can filter on the attributes of any node to narrow down the results to a specific set of CIs of that class or to a single specific CI. You can also select which property columns appear in the query results.

As you step through building a query, list options and other user interface elements of the CMDB Query Builder, are dynamically filtered as appropriate to your selections.

Procedure

  1. Navigate to Configuration and click CMDB Query Builder.
  2. On the CMDB Query Builder page do either of the following steps:
    • Click Create new. Type in a Name, choose CMDB Query as the Query type, and then click Create.
    • Click a widget of a saved query to continue building an existing query. Search saved queries first if needed.
    • Point to the upper right corner of a saved query widget, and click the Duplicate Query icon to edit a copy of a saved query. The default name of the new query contains the string 'copy'.
  3. On the canvas, you can do any of the following operations:
    • Add CI classes to the query: Select classes from the CMDB Classes hierarchy list and drag them to the canvas.
    • Add a non-CMDB table to the query: Select a table from the Non-CMDB Tables list and drag it to the canvas.
      Note: A non-CMDB table cannot be the start node in the query, and you cannot connect a CMDB class to two non-CMDB tables of the same type.
    • Add connections (relationships) between two nodes on the canvas:
      1. On the first node in the relationship, click the small square at the center of the right side.
      2. On the second node in the relationship, click the small square at the center of the left side to create the connection.
      3. In Connection Properties on the right-side bar, configure the following settings (click the connection line if necessary):
        • In the Relationship Direction section, select the Parent node (the Child node automatically adjusts).
        • In the Relationship Levels section, set Level to First level relationships if the CIs are directly connected. Or, Up to 2nd level relationships if the CIs are connected either directly or indirectly through another CI.

        • In the Relationship Types and Related Items section, select either option:
          Option Description
          No Relationships To query for CIs with no connecting relationships, such as All Tomcat WAR CIs which are not connected to a Windows Server.
          Add Relationship Types To select specific or any relationship type.
          Add a Related Item To query for related CIs between the nodes.
        • (Applies only to a non-CMDB table). In the CI Reference Column section, select the column with a reference to a class from the Reference column to a CI to query on list. If there is only one option, it is automatically selected.
      Table 1. Relationship UI Notations
      Notation Description
      Full line A relationship in a CMDB query.
      Red asterisk at the center of the connection line Information such as relationship type is missing, invalidating the query.
      Levels:<n> Types:<n> or a <Reference type> notation on the connection line

      As applicable: The number of relationship levels and the number of relationship types included for the connection. Or, a reference type for a relationship that is a reference.

    • Add filters to a class node: Apply filters to narrow down a class query to a specific set of CIs or to a single specific CI.
      1. Point to the node to add a filter to, and then click the Apply filters icon that pops up above the node.
      2. In the Filters section, add attribute and related list conditions.
      3. Close the Filters section.
      For example: Add a filter for database location to query for databases located in Seattle.

      Click Applied Filters in the right-side bar to view all filters for each node on the canvas.

    • Add And/Or operators to the query:
      1. Connect one node to two other nodes.
      2. Click the And box that appears on the connection line, to toggle between the And/Or operators.
      For example: C1 is Tomcat WAR, C2 is Linux Server, and C3 is Windows Server. Query for All Tomcat WAR CIs which are connected either to Linux Server Or to a Windows Server.
    • Add property columns for a node, to appear in the query results:
      Note: For a relationship, the query results include the parent, child, and type columns. You cannot add any other columns from the [cmdb_rel_ci] table.
      1. Click Properties in the right-side pane.
      2. Click a node once or twice, so that the Report Columns section appears in the right-side bar, and then click Add Columns.
      3. Select properties and then click outside the properties list to close it.
    • Create a combination query by integrating a Service Mapping query into a CMDB query:
      1. When building a CMDB query, click Saved Service Queries in the left-side bar.
      2. Select and then drag a Service Mapping query to the canvas.
      This query returns all CIs that satisfy the CMDB query, and that are included in the services returned by the embedded Service Mapping query.
    • Add a search tag that can then be used as a search criteria for saved queries:
      1. Click the Add Tags icon at the top of the canvas.
      2. Click Add Tag and in the Query Tags dialog box enter one or more tag strings.
      3. Click the Add Tags icon again to close the Query Tags dialog box.
  4. Click Save.

    On the Saved Queries tab, point to a saved query widget and click Query Information. Query details such as the query type, last update date, CMDB groups associated with the query, and the query schedules appear.

What to do next

  • Click Run.

    Only the first 100 results of the query appear in the results pane.
    • Click Load More Results to view the next set of 100 results.
    • Click Load All Results to view the rest of the query results, up to the number specified by the glide.cmdb.query.max_results_limit system property (10,000 by default).

    Click a CI to open its CI form, and on the CI form click Dashboard to view CI health in the CI dashboard.

    Note:
    • If Level is set to Up to 2nd level relationships, then the relationship type does not appear in the query results.
    • When a query is running, wait for it to complete or to time out before opening or running another query.
  • Modify Query Builder settings: Click the Settings icon. (Settings) icon to open the Query Builder Settings dialog box.
  • Copy and share the URL of a saved query with users that have access to the CMDB Query Builder. Pasting the shared URL in a new internet browser window, directly opens the saved query in the CMDB Query Builder.
  • Create a report from CMDB query results.
  • Create a schedule to run the query at a future time, and to email the results to interested parties.
  • Export query results:

    Click the Query Results context menu and select Export. Even if the Load More Results button is visible, indicating that there are additional query results, only the results that are visible are exported.

  • Export and import a CMDB query to port a query definition between instances.
  • Populate a CMDB group using a saved query.
Feedback