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

CODE

<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.

CODE

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.

CODE

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	Binary name	MD5 hash
60	odio.exe	f32bd724cb4b8593c9789ec584eb38dc
26	volutpat.exe	5ec62b81e594367fa20a3fbdf4e4e7f3
12	eget.exe	dc182b7939eba5ca8b1d64396b88fcd2
7	euismod.exe	2d0c540521f7e5683487c42c6ff52479
7	euismod.exe	2d0c540521f7e5683487c42c6ff52479
6	aliquet.exe	f4c4ad04db18ff1d225cbc43e864748a
6	vitae.exe	bd85d77734d35c5ee00edeffc44e1dcd

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

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

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