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.

   

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.

Use regular expressions (regex) in BQL

Regular expressions (regex) in BQL enable you to streamline complex queries by combining multiple conditions into a single pattern match.

If you are new to regex or want to test and understand regex better, you can use tools like regex101 to help get you started. regex101 provides an interactive environment to create, test, and debug regex patterns, ensuring that the regex is valid.

note

BQL supports the Java flavor of regex. You must use the Java 8 regex flavor with the Match function for the most accurate representation.

Regex example

When querying for strings that follow specific naming conventions, you might end up writing multiple STARTS WITH, ENDS WITH, or CONTAINS conditions. This can quickly become difficult to manage as the conditions grow.

Consider the following BQL query that is aimed at retrieving hosts with names that fit a particular pattern:

FIND Host AS h WHERE 
h.name STARTS WITH "Alpha" OR 
h.name STARTS WITH "Bravo" OR 
h.name STARTS WITH "Zebra" AND
h.name CONTAINS ANY ["1", "2", "3"] AND
h.name ENDS WITH "d1234" OR h.name ENDS WITH "n5678"

As the number of host names with different starting letters, number requirements, and patterns increases, this query can become difficult to manage. The above BQL query can be translated into a single regex pattern:

FIND Host AS h WHERE h.name =~ "^[A-Za-z]{5}\d[dn]\d{4}$"

Let's breakdown the regex condition:

• =~: The regex match operator. It is used to indicate that the attribute (e.g., h.name) should be evaluated against the regex pattern that follows.

• ^: Asserts the start of the string. In this example, the ^ ensures the match begins with exactly five letters, satisfying the [A-Za-z]{5} portion of the pattern.

• [A-Za-z]{5}: Matches exactly five letters, uppercase, lowercase, or both. This ensures that the retrieved host names start with exactly five letters.

• \d: Matches a single digit (0-9). This digit must immediately follow the five starting letters of the host name.

• [dn]: Matches either the letter 'd' or 'n' after the initial five letters and single digit. This provides flexibility for different naming conventions by restricting the next character to either d or n.

• \d{4}: Matches exactly four digits. These digits must appear directly after the d or n, forming the final part of the host name.

• $: Asserts the end of the string. This ensures that no additional characters appear after the four digits, enforcing that the string strictly follows the pattern.

  The following screenshot illustrates how the regex accurately matches example test strings to ensure the regex achieves the same results as the lengthy BQL query:

  

Important

While regex is supported in BQL queries, its use is not encouraged. Using regex in BQL can put a strain on the underlying graph database and lead to performance issues.