Syntax
nPL search syntax: keywords, field comparisons, wildcards, regex, IN lists, CIDR ranges, ioc terms, precedence, comments, time modifiers and query limits.
Use this reference to write your nPL search expression and connect it to pipeline commands. An nPL query contains a search expression followed by zero or more piped commands:
<search expression> | <command> | <command> ...The search expression selects events. Each command transforms the rows that the previous stage produced. This page covers the search expression and the rules that apply to the whole query. Each command has its own page; see the command list or the quick reference.
Fields are OCSF 1.9 dotted paths such as src_endpoint.ip or actor.user.name. See OCSF schema and the OCSF field reference.
Keywords
A bare word is a token search over the event's message and raw_data. Several words must all match. Quote a phrase to match the words together.
mimikatz
failed password
"access denied"*alone matches every event.- A wildcard keyword such as
*svchost*is a case-insensitive substring match onmessageandraw_data. - Keyword matching is case-insensitive.
- A field filter is faster and more precise than a keyword. Prefer
process.name=mimikatz.exeovermimikatzwhen you know the field.
Field comparisons
user.name=administrator
http_response.code>=500
dst_endpoint.port!=443
severity_id>=4| Operator | Meaning |
|---|---|
= / != | Equal / not equal. String comparisons are case-insensitive. |
> < >= <= | Numeric (or time) comparison |
Quote values that contain spaces or special characters: process.file.path="C:\Program Files\app.exe". Inside quotes a backslash never escapes the closing quote, so a Windows path ending in \ works. Use single quotes to match a literal ".
Unquoted values may contain letters, digits and _ - . * ? / : @ \ +, so URLs, paths and IPv6 addresses can usually be written without quotes.
Wildcards
* matches any run of characters and ? matches one character. With = or != a wildcard value is a case-insensitive pattern match.
user.name=adm*
process.name=*.ps1
user.name=adm?nExistence: field=*
field=* matches events where the field is present and not empty. It is not "match all". field!=* matches events where the field is missing or empty.
class_uid=3002 user.name=*
class_uid=4002 http_request.user_agent!=*Regular expressions
Write a regex between slashes, or use the =~ / !~ operators. Regex matching is unanchored and case-insensitive.
process.cmd_line=/-enc(odedcommand)?\s+[A-Za-z0-9+\/=]{40,}/
process.cmd_line =~ "-enc"
http_request.url.hostname !~ "\.(com|net|org)$"IN lists
class_uid IN (3002, 3003)
user.name IN ("administrator", "root", "admin")
dst_endpoint.port NOT IN (80, 443)CIDR ranges
An IP field compared with a CIDR matches addresses in the range. IN CIDR(...) takes a list.
src_endpoint.ip=10.0.0.0/8
src_endpoint.ip!=10.0.0.0/8
dst_endpoint.ip IN CIDR("10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16")
dst_endpoint.ip NOT IN CIDR("10.0.0.0/8", "192.168.0.0/16")Word operators
| Operator | Example |
|---|---|
LIKE (% and _ wildcards) | process.name LIKE "%.exe" |
CONTAINS | process.cmd_line CONTAINS "downloadstring" |
STARTSWITH | http_request.url.hostname STARTSWITH "login." |
ENDSWITH | file.name ENDSWITH ".lnk" |
Each also takes NOT, for example process.name NOT LIKE "%.exe".
Functions in a filter
A function can sit on the left of a comparison, and several boolean functions work as a filter on their own:
lower(user.name)="administrator"
len(user.name) < 3
is_public_ip(src_endpoint.ip) class_uid=3002
cidr_match(dst_endpoint.ip, "10.0.0.0/8")
isnotnull(actor.process.cmd_line)The boolean functions allowed on their own are isnull, isnotnull, like, match, cidr_match, is_private_ip, is_public_ip, has, in, isnum, isint, isstr, isbool, and searchmatch. See Functions for the full list.
Indicators: ioc
ioc matches an indicator in whichever observable field it could appear in, so you don't have to name the field. nano picks the fields from the value's type: an IP checks src_endpoint.ip and dst_endpoint.ip, a hash checks file.hashes.value, process.file.hashes.value and actor.process.file.hashes.value, and a domain checks the HTTP, URL, DNS and destination host names.
ioc=203.0.113.50
ioc=44d88612fea8a8f36de82e1278abb02f
ioc in [203.0.113.50, evil.example]
ioc=203.0.113.50 | stats count by metadata.log_source, class_nameioc also accepts a threat feed (ioc in feed("name"), or a feed function such as threatfox(...)), a lookup table (ioc in lookup("table", "column")) or an inline table (ioc in [inputlookup table]). Pair it with retro to sweep history.
Boolean logic and precedence
Terms separated by spaces are ANDed. AND/&&, OR/|| and NOT combine them, and parentheses group.
The precedence differs between the search expression and where / eval:
| Where | Precedence (tightest first) | a b OR c means |
|---|---|---|
Search expression and piped search | NOT, then OR, then AND | a AND (b OR c) |
where and eval | NOT, then AND, then OR | n/a: x OR y AND z means x OR (y AND z) |
The search rule follows the common SIEM convention. When in doubt, add parentheses.
class_uid=3002 (user.name=administrator OR user.name=root) status_id=2
class_uid=1007 NOT process.name=svchost.exe
* | where (user.name="administrator" OR user.name="root") AND status_id=2Pipes and commands
Each | starts a command that receives the previous stage's rows. Command names and keywords are case-insensitive.
class_uid=3002 status_id=2 | stats count by user.name, src_endpoint.ip | where count > 20 | sort -countStarting with a command
A query can start with a pipe. The search expression is then *:
| stats count by metadata.log_sourceYou can also leave out the pipe for these commands: stats, chart, timechart, streamstats, eventstats, top, rare and inputlookup. The command must take arguments and use the whole segment.
stats count by class_name
top dst_endpoint.portTo search for those words as keywords instead, quote them ("top user") or start with the search keyword (search top user). A leading search keyword is otherwise optional: search class_uid=3002 is the same as class_uid=3002.
Comments
Use // for a comment to the end of the line and /* ... */ for a block. Text inside quotes is never treated as a comment. # is not a comment character and causes a syntax error.
class_uid=3002 status_id=2 // failed logons only
/* brute force */ class_uid=3002 status_id=2 | stats count by src_endpoint.ipNewlines are treated as spaces, so you can break a long query across lines.
Time range
The time picker sets the search window. You can also set it in the query with earliest= and latest=. Units are s, m, h, d, w, M (months) and y.
class_uid=3002 status_id=2 earliest=-24h
metadata.log_source=aws_cloudtrail earliest=-7d latest=-1dSnap-to modifiers such as @d are not supported. Don't add them: earliest=-7d@d uses a plain 7-day offset (not midnight), and the leftover @d is searched as a keyword, which silently drops most events.
Filter on time with the time picker or earliest=/latest=. A BETWEEN clause is not part of nPL: time BETWEEN 1 AND 2 is read as four keywords, not a range.
Subsearches
A subsearch in square brackets supplies values to the outer query. Use it with IN, join and append:
class_uid=1007 device.hostname IN [search class_uid=3002 status_id=2 | return device.hostname]An IN [...] subsearch may contain only a search expression and an optional return of one field. It supplies up to 10,000 distinct values; a count on return is ignored here. To filter on aggregates first, use join.
A subsearch can read another dataset: start it with dataset=spans or dataset=metrics (for example IN [dataset=spans ...] or join ... [dataset=metrics ...]) to match against OpenTelemetry traces or metrics. Without dataset=, a subsearch reads the same dataset as the outer search.
Post-processing after nano-side stages
lookup, prevalence, inputlookup, resolve_identity, ai and lateral run in nano itself, after ClickHouse returns rows. Everything after the first of these stages runs in post-processing, where only these commands work: where, head, tail, sort, table, stats, dedup, rename, fields, top, rare, fillnull, eval, timechart, rex, risk, reverse, and tree. Put every other command before the first such stage.
Limits
| Limit | Value |
|---|---|
| Piped commands per query | 25 |
| Nesting depth (parentheses and subsearches) | 50 |
| Terms in one AND/OR chain | 1,024 |
| Query length | 1 MiB |
Search admission, concurrency and execution limits are deployment settings; see Settings → Search.
What's next
- Functions: eval and where functions, aggregations
- where: filter rows with expressions
- search: apply search syntax later in the pipeline
- Best practices: writing fast hunts