NQL include

An include clause allows you to join an inventory object table with an event table. It returns data per object even when there is no event recorded for a specific object. Use it to make sure to take into account all objects when computing metrics.

Syntax

<object table> ...
| include <event table> ...
| compute <new metric name> = <metric>.<aggregation function>
...

Example

List the binaries that triggered an execution crash and the associated number of crashes, during the last 24 hours.

binaries
| include execution.crashes during past 24h
| compute total_number_of_crashes = count()
| list total_number_of_crashes, name
| sort total_number_of_crashes desc

Number of crashes	Binary name
83	lorem.exe
20	bibendum.exe
10	imperdiet.exe
9	tempor.exe
7	egestas.exe
6	semper.exe
6	justo.exe

Using multiple ‘include’ clauses

An NQL query can contain multiple include clauses , allowing you to join the same event table with different conditions or to join several different event tables.

binaries
| include execution.crashes during past 1d
| compute total_number_of_crashes = count()
| include execution.events during past 1d
| compute sum_of_freezes = number_of_freezes.sum()
| list total_number_of_crashes, sum_of_freezes, name
| sort total_number_of_crashes desc

Number of crashes	Sum of freezes	Binary name	MD5 hash
60	0	odio.exe	f32bd724cb4b8593c9789ec584eb38dc
26	0	volutpat.exe	5ec62b81e594367fa20a3fbdf4e4e7f3
12	0	eget.exe	dc182b7939eba5ca8b1d64396b88fcd2
7	0	euismod.exe	2d0c540521f7e5683487c42c6ff52479
7	0	euismod.exe	2d0c540521f7e5683487c42c6ff52479
6	0	aliquet.exe	f4c4ad04db18ff1d225cbc43e864748a
6	0	vitae.exe	bd85d77734d35c5ee00edeffc44e1dcd

Understanding the purpose of ‘with’ and ‘include’ clauses

The include and with keywords are very similar but have very different purposes.

Keyword	Meaning	Scope	Purpose	Compute
with	Retain only those objects which have an event recorded	Modifies the scope	Filter and/or compute values for objects with events	A value is always computed and added
include	Retain all objects, including those that do not have an event recorded	Without a compute statement, no effect on scope	Only useful when a value is computed for all objects	Objects without events have no computed value