Skip to main content

BQL Search

This article details how to use the Brinqa Query Language (BQL) to search for your data.

What is BQL?​

BQL is a Brinqa specific query language designed to traverse your data and provide results. BQL defines a means of searching your data and attempts to resemble a natural language for simpler query construction.

For more information on how to use BQL extensively, including keywords, operators, functions, relationships, and specific use cases, see Brinqa Query Language.

BQL query structure​

The basic structure for a valid BQL query is as follows:

  • Start with FIND followed by the data model name you want to target. For example:
FIND Finding
  • Assign the targeted data model an alias using AS to be used in the rest of the query, and then add additional conditions using WHERE, WITH, AND, or OR, followed by attributes that exist on the target data model. For example:
FIND Finding AS f WHERE f.status = "Confirmed active"
  • Build on the query further by providing relationships with THAT followed by a relationship verb. For example:
FIND Finding AS f WHERE f.status = "Confirmed active" THAT IS FindingDefinition AS fd WHERE fd.cveIds CONTAINS ANY ["CVE-2017-7654"] AND fd.patchAvailable = "True"

Let's break down the components of the above BQL query to better understand how it's constructed:

  • FIND Finding AS f WHERE f.status = "Confirmed active": This part of the query selects the starting data model Finding, assigns it an alias f to be used in the rest of the query, and adds a condition to limit the data. In this case, the query only returns confirmed active findings.

  • THAT IS FindingDefinition AS fd: This part extends from the Finding data model to the FindingDefinition data model using the relationship keyword THAT IS. The FindingDefinition data model is assigned an alias fd.

  • WHERE fd.cvdIds CONTAINS ANY ["CVE-2017-7654"] AND fd.patchAvailable = "True": This part defines filtering conditions on the FindingDefinition data model using its attributes. In this case, the query only returns finding definitions whose cveIds attribute contains the string "CVE-2017-7645" and the patchAvailable attribute is set to "True".

Refer to BQL keywords for details about basic keywords that make up the clauses of a query statement and query for relationships in BQL for details about how to query your data using the relationships between data models.

Tutorial: Use BQL to find all active hosts​

Many pages in your Brinqa Platform support the use of BQL, including the pages under Inventory, Findings, Explorer, or Remediation. For example, to use BQL to find all of your compliant and confirmed active hosts, follow these steps:

  1. Navigate to Inventory > Hosts.

  2. Click the icon to the left of the search area, and then select BQL.

    query switcher

  3. Type the following query:

    FIND Host AS h WHERE h.status = "Confirmed active" and h.complianceStatus = "Compliant"
    tip

    The system displays a list of available objects to select from as you type your query.

  4. Press Enter or Return to execute the query.

If your query is valid, a green checkmark displays; if your query is invalid, a red exclamation mark displays. Hold your pointer over the mark to see the explanation on why the query is invalid. After verifying the validity of the query and running it successfully, you can save it for future use. To learn more, see Save and reuse queries.

It is important to take note of the page you are on before you attempt to execute a query, otherwise your query may not return any data even when it is valid. Take the following query for example:

Find User as u Where u.authMethod = "SAML"

The above query returns all users who authenticate using the Security Assertion Markup Language (SAML) method. The query is valid. If you are on Explorer or Inventory > Human Resources > People, the query runs successfully because Explorer is a global page that covers all data in your Brinqa Platform, and Human Resources > People lists employees working in your organization. However, if you try to execute the same query on Findings, which does not contain any data on users, the query does not return any data.

tip

If a query is valid but does not return the expected data or results in an error, try the same query on a page that supports the data model you are querying. Or better yet, use Explorer, as it is a global search page and supports all data models.

Last updated on