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 usingWHERE
,WITH
,AND
, orOR
, followed by attributes that exist on the target data model. For example:
FIND Finding AS f WHERE f.status = "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 = "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 = "Active"
: This part of the query selects the starting data modelFinding
, assigns it an aliasf
to be used in the rest of the query, and adds a condition to limit the data. In this case, the query only returns active findings. -
THAT IS FindingDefinition AS fd
: This part extends from theFinding
data model to theFindingDefinition
data model using the relationship keywordTHAT IS
. TheFindingDefinition
data model is assigned an aliasfd
. -
WHERE fd.cvdIds CONTAINS ANY ["CVE-2017-7654"] AND fd.patchAvailable = "True"
: This part defines filtering conditions on theFindingDefinition
data model using its attributes. In this case, the query only returns finding definitions whosecveIds
attribute contains the string "CVE-2017-7645" and thepatchAvailable
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 active hosts, follow these steps:
-
Navigate to Inventory > Hosts.
-
Click the icon to the left of the search area, and then select BQL.
-
Type the following query:
FIND Host AS h WHERE h.status = "Active" and h.complianceStatus = "Compliant"
tipThe system displays a list of available objects to select from as you type your query.
-
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.
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.