Searching with keyword lists#

You can reference a keyword list in any search query using the @ syntax. When the query runs, the platform expands the reference into the individual keywords in the list and matches each one against the searched field.

Where you can use `@list-identifier`#

You can reference a keyword list anywhere a value would normally appear in a search query:

As the value of a field — tags:@my-list matches entities whose tags contain any keyword from my-list.
As a multi-value field expression — tags:(@my-list OR @my-other-list) matches entities whose tags contain any keyword from either list. The expression must be enclosed in parentheses.
Without a field prefix — @my-list is also supported. The search runs against multiple fields at once. For better accuracy and performance, prefer scoping the reference to a specific field.

How each keyword is matched#

When the platform expands a list, every keyword is matched as one of two types, depending on whether it contains a wildcard character (* or ?):

Text keyword — no wildcard. Matched as a phrase against tokenized text fields. The platform tokenizes both the keyword and the field’s content the same way, then requires the keyword’s tokens to appear in the same order and proximity.
Wildcard keyword — contains * or ?. The platform transforms it into a substring search by wrapping it with * on both sides. As a result, apt*, *apt, and *apt* all behave identically: they match any field value containing the substring apt.

All matching is case-insensitive, regardless of keyword type.

Note

No anchored matching for wildcard keywords Wildcard keywords (those containing * or ?) always perform substring matching. Patterns like foo*, *foo, and *foo* are all treated identically — each matches any value containing foo.

This means you cannot strictly anchor a wildcard to the start or end of a field, but substring matching often serves you better in practice. For example, the keyword *@abc.com finds emails at abc.com wherever they appear in a field, including inside descriptions like “Phishing email sent from user@abc.com to internal mailbox”. An anchored “ends with” search would miss that case because the field does not literally end with @abc.com.

Choosing between text and wildcard keywords#

Use plain text keywords (e.g. acme.io) when you want precise matches and have control over the exact strings you expect to see.

Use wildcards (e.g. *acme.io, *.acme.io) when you want broader, “find anything containing this” matching at the cost of occasional false positives.

Text keyword examples#

For the text keyword apt, matches against different field values:

Field value	Match?	Why
`APT`	✓	Field tokenizes to `apt`.
`APT Groups`	✓	Tokenizes to `apt`, `groups`; contains `apt`.
`Some APT Groups`	✓	Tokenizes to `some`, `apt`, `groups`; contains `apt`.
`aptitude`	✗	Tokenizes to `aptitude` (one token); does not contain a separate `apt` token.
`RAPTURE`	✗	Tokenizes to `rapture`; does not contain `apt` as a separate token.

For the text keyword acme.io, the dot connecting alphanumeric text keeps it as a single token:

Field value	Match?	Why
`acme.io`	✓	Tokenizes to `acme.io`.
`https://acme.io/report`	✓	Tokenizes to `https`, `acme.io`, `report`; contains `acme.io`.
`user@acme.io`	✓	Tokenizes to `user`, `acme.io`; contains `acme.io`.
`prod.acme.io`	✗	Tokenizes to `prod.acme.io` (one token); `acme.io` is not a separate token.
`acme.io.uk`	✗	Tokenizes to `acme.io.uk` (one token); same reason.

To match subdomains of acme.io, use a wildcard keyword instead.

Wildcard keyword examples#

Within the substring, the wildcard characters still have meaning:

* matches zero or more characters.
? matches exactly one character.

For the wildcard keyword *apt* (or equivalently apt* or *apt — they all become substring searches):

Field value	Match?	Why
`APT`	✓	Contains `apt`.
`APT Groups`	✓	Contains `apt`.
`Some APT Groups`	✓	Contains `apt`.
`aptitude`	✓	Contains `apt`.
`RAPTURE`	✓	Contains `apt` as a substring.

This matches everything containing apt, including unintended matches like aptitude and RAPTURE. Use wildcards carefully — they often match more broadly than expected.

For the wildcard keyword *.acme.io:

Field value	Match?	Why
`acme.io`	✗	Does not contain `.acme.io` (no leading dot).
`prod.acme.io`	✓	Contains `.acme.io`.
`staging.acme.io`	✓	Contains `.acme.io`.
`acme.io.uk`	✗	Does not contain `.acme.io` as a substring.

To match acme.io and all its subdomains in one go, use either:

Two keywords in the list: acme.io and *.acme.io.
A single wildcard: *acme.io (matches anything containing acme.io, including the bare domain). Note this is broader and may match unintended values like acme.iox.com.

Query examples#

Assume a keyword list acme-assets containing keywords like acme.io, prod.acme.io, *.acme.io, 192.168.*.

Query	What it returns
`tags:@acme-assets`	Entities whose `tags` contain any keyword from the list.
`meta.title:@acme-assets`	Entities whose title matches any keyword from the list.
`data.description:@acme-assets`	Entities whose description matches any keyword from the list.
`@acme-assets`	Entities where any of the searched fields match any keyword from the list.
`tags:@acme-assets AND data.type:report`	Reports tagged with at least one keyword from the list.
`tags:(@acme-assets OR @partner-vendors)`	Entities tagged with at least one keyword from either list.