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

Starting from Brinqa Platform version 11.33.98, drill-downs are supported for complex queries in the following scenarios:

  • The query uses parent data models (Asset, Finding, or Ticket) in a relationship. For example: FIND Asset THAT HAS Finding.

  • The query uses child data models (e.g., Vulnerability extends Finding) in a relationship and you drill down to the child data model using its attributes. For example: FIND Asset THAT HAS Vulnerability, and you drill down to Vulnerability using vulnerability attributes.

  • The query uses child data models in a relationship and you drill down to the source (primary) data model. For example: FIND Asset THAT HAS Vulnerability, and you drill down to Asset.

Other complex query scenarios may not support drill-downs. Full support for all complex query types is planned for a future release.

Last updated on