Skip to main content

Global Context

When using the local ContexQL query in a scenario, operations are applied within the context of the graph generated for the currently processed input object. For instance, if the platform is processing an object of Email type, the graph will contain information about all extracted texts, attachments, and metadata from the email message. This setup already allows for complex relationship and metadata queries. However, Contextal Platform extends its capabilities even further with the global context concept to manage more advanced cases.

Global Query​

The global query is a ContexQL query that runs outside the scope of the current input object's graph. Instead, it operates on graphs generated from other input objects processed globally by the platform, providing a broader perspective. This allows you to identify whether characteristics spotted across multiple objects in the system are relevant to the currently processed data.

To improve data processing and accuracy, the global query takes the following settings:

  • MATCHES (required)

    • Specifies the number of global graphs required to match.
    • Accepts the following values: NONE, >X, >Y%, <X, <Z%, where X is a number in the range of [0, u32::MAX], Y is a number in the range of [0, 99], Z is a number in the range of [0, 100].
    • Example: MATCHES: <10% - the query should match less than 10% of all analyzed global graphs.

  • TIME_WINDOW (required)

    • Limits analysed global graphs to a specified time window.
    • Accepts the syntax (NUMBER UNIT)+ where UNIT is one of: year(s), month(s), week(s), day(s), hour(s), minute(s).
    • Example: TIME_WINDOW: 2 months 10 days - the global query would be applied to graphs which are not older than two months and ten days.

  • MAX_NEIGHBORS (optional)

    • Limits analysed global graphs to a specified number of neighbors of the local graph.
    • Can be used to fine tune performance in high-load environments.
    • Accepts a number in the range of [0, u32::MAX].
    • Example: MAX_NEIGHBORS: 1000 - the global query would be applied to no more than 1000 of the global graphs.

LOCAL Selector​

The LOCAL selector is a powerful tool, which can be used in a global query to access data from its local counterpart. The following entires can be accessed:

  • is_entry
  • work_id
  • object_id
  • org
  • object_type
  • object_subtype
  • recursion_level
  • size
  • entropy
  • get_symbols()
  • get_names()
  • get_object_meta($key) - get value of any object metadata key
  • get_relation_meta($key) - get value of any relation metadata key

By default, all values for a specific entry are collected from a local graph. For example, LOCAL.size retrieves the sizes of all objects, while LOCAL.get_names() returns the names of all objects.

The LOCAL selector also supports the filter() function, which limits data collection to objects matching specific criteria. For example:

// Select all domain names found in a local graph
${domain_names}=LOCAL.filter(object_type == "Domain").get_names();

Use Cases​

The global context query is a powerful tool, enabling you to ask broad questions like "Have you seen specific characteristics in already processed objects, and in how many?" This technique is useful for validating local queries before triggering actions, comparing current and historical data, or for detecting large-scale phishing, malware, or spam campaigns, allowing for smarter and more effective responses to threats based on global data awareness. For more examples and creative uses, check out the Scenarios Examples section.