Skip to main content

Complex Queries

In the Brinqa Platform, certain BQL queries are classified as complex queries based on specific characteristics such as multi-labeling, incoming relationships, or non-simple attribute paths. While complex queries unlock powerful querying capabilities, they have certain UI limitations: they cannot be displayed in basic search mode in List views or converted to the visual wizard in Dashboards. Understanding what makes a query complex helps you anticipate these limitations and plan your queries accordingly.

What makes a BQL query complex?​

A BQL query is considered complex if it meets any one of the following conditions:

  • The main entity in the query has more than one label.

    For example, you can use multi-labeling to query multiple data models that share common attributes using the pipe character (|):

    FIND Host|Vulnerability WHERE dataIntegrationTitles = "Qualys VM"

    Queries with multi-labeling are complex queries.

  • The query uses a generic relationship (the RELATES keyword) to represent relationships.

    For example, the following query returns vulnerabilities that relate to their definitions through any type of relationship (direct or indirect), as determined by the RELATES keyword. This qualifies it as a complex query:

    FIND Vulnerability AS v
    THAT RELATES TO VulnerabilityDefinition AS v2

  • The query includes an incoming relationship.

    Incoming relationships are relationships where a data model is referenced by another data model but doesn't define the relationship itself. For example, the Vulnerability data model's targets attribute references the Asset data model, but the Asset data model doesn't define any reciprocal relationship to Vulnerability. In this case, the relationship from Vulnerability to Asset is outgoing (sometimes represented by >> in queries), and the reverse relationship from Asset to Vulnerability is incoming (represented by <<).

    You can omit the relationship directions when writing queries. However, if you choose to include them, they must represent the correct direction. Both of the following queries are valid:

    FIND Asset AS a 
    THAT HAS Vulnerability AS v
    FIND Asset AS a 
    THAT HAS << Vulnerability AS v

    On the other hand, the following query is invalid because >> represents an outgoing relationship, which Asset doesn't define to Vulnerability:

    FIND Asset AS a 
    THAT HAS >> Vulnerability AS v

    Queries that use incoming relationship are complex queries.

  • The query targets a custom data source via the USING clause.

    For example, you can use the USING keyword to direct your query to a specific database:

    USING OLAP FIND Finding AS f
    RETURN DISTINCT f.riskRating AS "Risk rating", count(*)
    AS Count ORDER BY "Risk rating" DESC LIMIT 10

    Any query that includes the USING keyword is considered a complex query.

  • When a condition uses any of the following keywords with non-simple attribute paths:

    note

    This complexity criterion only applies to queries in List views.

    • And
    • Before
    • Between / NotBetween
    • EqualsTo
    • Exists / NotExists
    • InLast / NotInLast
    • InList / NotInList
    • InNext / NotInNext
    • Is / IsNot
    • Since
    • GreaterThanOrEqualsTo
    • LessThanOrEqualsTo
    • ContainsAnyValues / NotContainsAnyValues
    • ContainsAllValues / NotContainsAllValues
    • IsNull / IsNotNull

    A path is considered simple if:

    • It includes one or two data models. For example,

      FIND Host AS a
      WHERE a.name = "web-server-01"

    • It includes three data models and the last one is a simple property, such as a number or a single-value string. For example,

      FIND Vulnerability AS v 
      THAT HAS Asset AS a 
      THAT IS AssetProfile AS a2 
      WHERE a2.id = 1998543162276274176

    A path is considered non-simple if:

    • It includes more than three data models. For example,

      FIND Vulnerability AS v 
      THAT HAS Asset AS a 
      THAT SUPPORTS BusinessService as b 
      THAT OWNS Person as p

    • It includes three data models but ends with a non-simple property, such as a collection or an object. For example,

      FIND Vulnerability AS v 
      THAT HAS Asset AS a 
      THAT OWNS Person as p 
      WHERE p.reportsTo IN ["Manager"]

    A query is considered complex if it uses a keyword from the list above with a non-simple attribute path, or if it uses any keyword not included in the list above.

UI limitations with complex queries​

Certain UI components in the Brinqa Platform cannot display or convert complex queries. This limitation is most noticeable in List views and Dashboards.

List views​

In List views, you can typically toggle between basic search and BQL search modes. If you enter a BQL query and find that the basic search toggle becomes disabled, your query is considered complex and cannot be represented in the basic search interface.

Dashboards​

When building a dashboard, you can enter queries directly in Advanced mode. In most cases, you can switch to the wizard afterward (using the <> button) to make modifications. However, if your query is complex, the wizard toggle will be disabled and you'll need to continue using Advanced mode.

note

Currently, complex queries also prevent you from creating drill-downs on dashboard widgets. This limitation will be addressed in a future platform update.

Last updated on