Skip to main content

BQL Syntax and Style Guide

Use this guide to learn best practices for writing clear and consistent Brinqa Query Language (BQL) queries. Following a standardized syntax ensures that your queries are readable, reusable, and easier to debug.

BQL query structure​

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

  • Start with FIND followed by the data model name:

    FIND Finding

  • Assign the data model an alias using AS:

    FIND Finding AS f

  • Extend the query using THAT and a relationship verb to include related data models:

    FIND Finding AS f
    THAT IS FindingDefinition AS fd

  • Add conditions using a WHERE clause and combine them using Boolean operators:

    FIND Finding AS f
    THAT IS FindingDefinition AS fd
    WHERE f.status = "Confirmed active"
    AND 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:

      Selects the Finding data model and assigns it the alias f so it can be referenced throughout the query.

    • THAT IS FindingDefinition AS fd:

      Traverses the relationship between Finding and FindingDefinition, assigning fd as the alias for FindingDefinition.

    • WHERE f.status = "Confirmed active":

      Filters the findings to include only those with a status of Confirmed active.

    • AND fd.cvdIds CONTAINS ANY ["CVE-2017-7654"]:

      Filters the related finding definitions to include only those that reference CVE-2017-7654.

    • AND fd.patchAvailable = "True":

      Further filters the results to only include finding definitions with a patch available.

For additional information, see the following:

BQL styling best practices​

The following conventions provide guidance to assist you in writing clean, readable, and maintainable BQL queries.

Casing​

BQL is partially case-sensitive. Using consistent casing throughout your queries improves clarity and can reduce the chance of subtle errors.

Keywords​

Keywords like FIND, WHERE, and THAT are case-insensitive. You can use find, FiNd, or FIND, and your query will still work.

Valid:

find Finding
FiNd Finding
FIND Finding

Data model names​

Data model names are case-sensitive. You must use the correct casing, such as Finding, not finding or FINDING.

Valid:

FIND Finding

Invalid:

FIND finding
FIND FINDING

As you type a data model name in the search bar when using BQL, a drop-down appears to help you select the correct spelling and casing. You can select the data model from the list to avoid capitalization errors:

Data model name drop-down

Aliases​

Aliases must be referenced using the same case you used when assigning them. If you assign AS f, you must use f consistently throughout the rest of the query—not F, and vice versa.

Valid:

FIND Finding AS f
WHERE f.status = "Confirmed active"
FIND Finding AS F
WHERE F.status = "Confirmed active"

Invalid:

FIND Finding AS f
WHERE F.status = "Confirmed active"

Data model attribute names​

Data model attribute names are case-sensitive. You must use the correct casing, such as status, not Status or STATUS.

Valid:

FIND Asset AS a
WHERE a.status = "Confirmed active"

Invalid:

FIND Asset AS a
WHERE a.STATUS = "Confirmed active"

You can see the correct casing of the attribute names in the data model reference pages, under the Attribute Name column.

Strings​

String values are case-sensitive. You must match the value exactly as it appears in the data for the specific attribute you're querying. For example, if f.riskRating stores "Critical", using "critical" or "CRITICAL" will not return results.

Valid:

FIND Finding AS f
WHERE f.riskRating = "Critical"

Invalid:

FIND Finding AS f
WHERE f.riskRating = "critical"

Line breaks​

Breaking your query across lines improves readability and makes it easier to identify and debug issues—especially in longer queries with multiple relationships or conditions.

Avoid writing long one-liners:

FIND Vulnerability AS v THAT HAS Asset AS a AND a THAT OWNS_REMEDIATION RemediationOwner AS ro WHERE v.riskRating = "Critical" AND ro.name LIKE "Windows Workstation Remediation Team"

Instead, use line breaks (Shift + Enter or Shift + Return on your keyboard) to separate each clause and condition:

FIND Vulnerability AS v
THAT HAS Asset AS a
AND a THAT OWNS_REMEDIATION RemediationOwner AS ro
WHERE v.riskRating = "Critical"
AND ro.name LIKE "Windows Workstation Remediation Team"

Quotations​

Use double quotes (" ") when referencing string values in your BQL queries. This includes names, statuses, risk levels, and other string-based attribute values.

Valid:

FIND Finding AS f
WHERE f.status = "Confirmed active"

Invalid:

FIND Finding AS f
WHERE f.status = 'Confirmed active'
FIND Finding AS f
WHERE f.status = Confirmed active

Do not use quotes for:

  • Boolean values (TRUE, FALSE)
  • Numbers (100, 5.0, etc.)
  • Dates (2025-05-01)

Valid:

FIND Finding AS f
WHERE f.riskScore > 5
FIND VulnerabilityDefinition AS v
WHERE v.patchAvailable = TRUE
FIND Host AS h
WHERE h.lastSeen SINCE 2025-05-01

Invalid:

FIND Finding AS f
WHERE f.riskScore > "5"
FIND VulnerabilityDefinition AS v
WHERE v.patchAvailable = "True"
FIND Host AS h
WHERE h.lastSeen SINCE "2025-05-01"
note

Even though the above invalid queries pass the BQL syntax checker, they do not return any results. Wrap only string values in quotes.

Spacing​

For visual clarity, add spaces around comparison and logical operators such as =, <, >=, etc.

Avoid writing queries like this:

FIND Asset AS a
WHERE a.name="Workstation-001"
AND a.status="Confirmed active"

Instead, add a space before and after each operator:

FIND Asset AS a
WHERE a.name = "Workstation-001"
AND a.status = "Confirmed active"

While both versions of the query are valid and return the same results, using spaces improves readability and aligns with standard formatting across most query and programming languages.

In addition to spaces after operators, you should also include a space after commas when writing lists.

Avoid writing queries like this:

FIND Finding AS f
WHERE f.severity IN ["Critical","High","Medium"]

Instead, add a space between the commas in the list:

FIND Finding AS f
WHERE f.severity IN ["Critical", "High", "Medium"]

This keeps your queries more readable, especially when you're working with longer lists of values.

Wildcards​

The asterisk (*) wildcard is supported in BQL when used with the LIKE, LIKE ANY, NOT LIKE, and NOT LIKE ANY operators. Wildcards enable you to match string patterns instead of exact values and matching is case-insensitive.

Valid:

FIND Asset AS a
WHERE a.name LIKE "demo*"

The above query returns any assets whose name begins with "demo", such as "demo-app-1", or "demoServer".

FIND Asset AS a
WHERE a.name LIKE "*bucket*"

The above query uses wildcards on both sides of the string (*bucket*) and returns any asset names that contain the substring "bucket" at any position, such as "Bitbucket" or "cloud-bucket". Since wildcard matching is case-insensitive, "*bucket* and *Bucket* return the same results.

Invalid:

FIND Asset AS a
WHERE a.name = "demo*"

The above query is invalid because wildcards are not supported with =.

FIND Asset AS a
WHERE a.name CONTAINS "*bucket*"

The above query is invalid because the CONTAINS operator does not support wildcards.

note

Even though the above invalid queries pass the BQL syntax checker, they do not return any results.

Last updated on