Text search operators

FuseQL text search operators match against the raw log message body or structured field values using patterns, substrings, regular expressions, or token lookups. They must appear before the first pipe (|) in a query. Choose the right operator based on what is indexed: use term for token lookups (fast, index-backed), "phrase" (grep) for literal substring scans, =~ for regex on label and facet values, * / ~ / ~* for substring or prefix or suffix matches, and @facet or key exists to test field presence.

**

Substring filter operator. Selects log lines where a label or facet value contains the specified string anywhere within it. The match is case-sensitive and does not require the string to appear at the start or end.

Syntax

label**"value"
@facet**"value"
none

Parameters

Parameter Required Description

label or @facet

Yes

The label key or (with @ prefix) facet name to filter on.

"value"

Yes

The substring that must appear anywhere in the field value.

Example

Return nginx logs for deployments whose name contains the string ingress-ingress.

source="nginx" and kube_deployment**"ingress-ingress" | count by kube_deployment
Expected output
_count kube_deployment

316505

kfuse-ingress-ingress-nginx-controller

Use * when you know a substring but not the full value. For prefix matching use ~; for suffix matching use ~*; for exact matching use =. The match is case-sensitive.

~*

Suffix match filter operator. Selects log lines where a label or facet value ends with the specified string. This is a faster alternative to a regex anchor (=~"suffix$") for simple suffix checks.

Syntax

label~*"suffix"
@facet~*"suffix"
none

Parameters

Parameter Required Description

label or @facet

Yes

The label or facet name to match against.

"suffix"

Yes

The string that the field value must end with.

Example

Return logs from services whose name ends with service.

source="nginx" @resource_service_name~*"service"
Effect

Returns log lines from the nginx source where resource_service_name ends with service, such as api-service or auth-service.

The ~ operator is case-sensitive. For case-insensitive suffix matching, use the regex operator with the (?i) flag: label=~"(?i)suffix$". Prefer ~ over a regex suffix pattern when the match is a plain literal string.

grep (double-quote search)

Literal substring search operator. Searches for an exact character sequence in the raw log body. Unlike term search (single quotes), which queries an inverted index of whole words, grep scans the reconstructed log body character-by-character — so it can match partial words, camelCase substrings, and multi-word phrases in a specific order.

How it works

Kloudfuse stores each log line as a fingerprint (the structural template) plus a list of extracted variable values. At query time, grep reconstructs the full log message from these parts and scans the result as a character sequence using the kf_log_grep_match function inside the query engine. No inverted index is used for plain substring greps.

For regex greps (patterns containing * or ? wildcards, or =~ on labels/facets), the engine applies an optimization: a literal prefix is extracted from the pattern and used to pre-filter candidate lines via the Lucene text index, and then a per-row RE2 regex check validates the exact match. This makes regex greps faster than a pure scan, but they are still slower than term searches for whole-word lookups.

Key properties:

  • Matches are case-sensitive — "Error" does not match error.

  • Partial-word matches succeed — "error" matches errored, errors, and error_count.

  • Multi-word phrases must appear in the exact character sequence — "connection refused" only matches lines where those two words appear adjacent and in that order.

  • Wildcards (any characters) and ? (any single character) are supported — "err" matches error, errored, errors.

Grep vs. term search

Property Grep ("…") Term search ('…')

Match type

Literal character substring in the reconstructed log body

Whole words from the Lucene inverted index on log_line

Token boundaries

No — "error" matches errored, errors, error_count as character sequences

Yes — 'error' does not match errored; does match error_count (underscore is a delimiter)

Case sensitivity

Case-sensitive

Case-insensitive (Lucene lowercases at ingest)

Wildcards

Yes — "err*" and "err?r" are supported

No

Speed

Slower — per-row body reconstruction and scan

Faster — index lookup

Multi-word

Exact ordered phrase

Both words present anywhere in the line (AND, any order)

Use grep when you need an exact phrase match, need to match a partial word or camelCase substring, or need wildcard patterns. Use term search for whole-word lookups where speed matters.

Syntax

"expression"
"wild*card"
none

Parameters

Parameter Required Description

"expression"

Yes

A double-quoted literal string or wildcard pattern to match as a character sequence in the raw log body. The match is case-sensitive. Use * for zero or more characters and ? for any single character.

Example

Return logs whose body contains the exact phrase Connection refused:

"Connection refused"
Effect

Returns log lines where the character sequence Connection refused appears in the raw log body. connection refused (different case) and Connection: refused (colon inserted) do not match.

Return nginx access logs for any path under /api/:

source="nginx" "GET /api/*"
Effect

Returns nginx log lines whose body matches the pattern — for example, GET /api/orders and GET /api/users both match.

key exists

Facet presence filter operator. Selects log lines where a specific facet key is present in the log entry, regardless of the value it holds. In regular search, use the key exists keyword syntax; in advanced search, reference the facet name with the @ prefix alone.

Syntax

key exists="facetName"
none

Parameters

Parameter Required Description

facetName

Yes

The name of the facet whose presence to check. In regular search, quoted as a string value; in advanced search, prefixed with @.

Example

Return log lines that have a user_agent_original facet (any value), to filter for requests that include a user-agent header.

source="nginx" @user_agent_original
Effect

Returns log lines from the nginx source where the user_agent_original facet is present, regardless of its value.

Use key exists to identify log lines that were enriched with a specific facet, or to find entries from agents or integrations that emit a particular field. Combine with value operators to further narrow results: @user_agent_original and @user_agent_original!~".bot.".

not-grep (negated double-quote search)

Literal substring exclusion operator. Excludes log lines whose raw log body contains the specified exact character sequence. This is the logical complement of the grep ("expression") operator — everything that grep would match is excluded. Wildcards are supported.

Syntax

!"expression"
!"wild*card"
none

Parameters

Parameter Required Description

"expression"

Yes

A double-quoted literal string or wildcard pattern; any log line whose raw body contains a match is excluded. The match is case-sensitive. Use * for zero or more characters and ? for any single character.

Example

Exclude health-check noise from nginx logs:

source="nginx" !"GET /health*"
Effect

Returns all nginx log lines except those whose body matches the pattern GET /health* — for example, GET /health and GET /healthz are both excluded.

!"expression" (not-grep) scans for substrings in the raw log body and is case-sensitive. It is distinct from !'term' (not-terms-exist), which queries the Lucene inverted index for whole-word tokens and is case-insensitive. Use not-grep when you need to exclude a partial word, an exact phrase, or a case-specific sequence. Use !'term' when you want to exclude log lines containing a specific whole word.

!~

Regex exclusion filter operator. Selects log lines where a label or facet value does not match the specified regular expression pattern. This is the logical complement of =~. As with =~, patterns are automatically anchored — label!~"foo" excludes lines where the value is exactly "foo", not lines where it merely contains "foo".

Syntax

label!~"pattern"
@facetName!~"pattern"
none

Parameters

Parameter Required Description

label or @facetName

Yes

The label or facet name to match against.

"pattern"

Yes

A RE2-compliant regular expression string; lines where the value matches this pattern are excluded.

Example

Return nginx logs from namespaces that do not contain kfuse.

source="nginx" kube_namespace!~"kfuse.*"
Effect

Returns log lines from the nginx source where kube_namespace does not match kfuse.*.

Patterns are automatically anchored, so explicit ^ and $ are not needed. To exclude lines where a value merely contains a substring, use . around your pattern: label!~".*foo.". Combine !~ with =~ to build allow-and-deny filter lists.

not-term (negated single-quote search)

Token exclusion operator. Excludes log lines whose raw log body contains the specified whole word or all of the specified words. This is the logical complement of the term search ('term') operator — it queries the Lucene inverted index and excludes any line where all the specified tokens are present as whole words.

Syntax

!'term'
NOT 'term'
!'term1 term2'
none

Parameters

Parameter Required Description

'term'

Yes

A single-quoted word or space-separated words. A log line is excluded if it contains all listed tokens as whole words. A line is included if any listed token is absent.

Example

Suppress high-volume polling traffic that would otherwise dominate results:

!'healthcheck'
Effect

Excludes log lines where healthcheck appears as a whole token. Lines containing healthcheck_endpoint or kube-healthcheck are also excluded — underscores and dashes are token boundaries, so healthcheck is a distinct token in those strings. Lines containing healthchecking (no boundary after healthcheck) are not excluded.

!'term' (not-terms-exist) is token-based and case-insensitive. It excludes a line only when the term appears as a complete token — delimited by whitespace or punctuation. !'error' excludes lines containing error, Error, or error_count (underscore boundary), but not lines containing only errored or errors (no boundary). For substring exclusion regardless of boundaries, use !"expression" (not-grep).

=~

Regex match filter operator. Selects log lines where a label or facet value matches the specified regular expression pattern. The match is full-value by default — the pattern is automatically anchored, so label=~"foo" matches only "foo", not "foobar". Use . around your pattern if you want a substring match: label=~".*foo.".

Syntax

label=~"pattern"
@facetName=~"pattern"
none

Parameters

Parameter Required Description

label or @facetName

Yes

The label or facet name to match against.

"pattern"

Yes

A RE2-compliant regular expression string.

Example

Return nginx logs from any namespace whose name starts with kfuse.

source="nginx" kube_namespace=~"kfuse.*"
Effect

Returns log lines from the nginx source where the kube_namespace label matches the pattern kfuse.* (any value beginning with kfuse).

The regex engine does not support look-ahead or look-behind assertions. For case-insensitive matching, use the inline flag (?i): label=~"(?i)nginx". Because patterns are automatically anchored, adding explicit ^ and $ anchors is unnecessary and results in double-anchoring.

*~

Prefix match filter operator. Selects log lines where a label or facet value begins with the specified string. This is a faster alternative to a regex anchor (=~"^prefix") for simple prefix checks.

Syntax

label*~"prefix"
@facet*~"prefix"
none

Parameters

Parameter Required Description

label or @facet

Yes

The label or facet name to match against.

"prefix"

Yes

The string that the field value must start with.

Example

Return logs from containers whose name starts with kfuse.

source="nginx" kube_container_name*~"kfuse"
Effect

Returns log lines from the nginx source where kube_container_name begins with kfuse, such as kfuse-api-server or kfuse-ingress.

The ~ operator is case-sensitive. For case-insensitive prefix matching, use the regex operator with the (?i) flag: label=~"(?i)^prefix". Prefer ~ over a regex prefix pattern when the match is purely literal — it is more readable and may execute faster.

term (single-quote search)

Token search operator. Selects log lines whose raw log body contains the specified token or all of the specified tokens. Unlike grep (double quotes), which scans reconstructed character sequences, term search queries the Lucene inverted index built from the raw log_line column at ingest time — making it faster for whole-token lookups.

How it works

At ingest, the raw log line is tokenized by Pinot’s Lucene analyzer: text is split on whitespace and punctuation (spaces, dashes, underscores, slashes, braces, and similar characters), and each token is lower-cased. These tokens are stored in an inverted index that maps each token to the set of log lines containing it.

A term search looks up the token in that index directly — no per-row reconstruction or scanning of raw log bodies occurs. This means:

  • 'error' matches a line containing error, Error, or ERROR (case-insensitive), and also matches error_count or error-rate because punctuation creates a token boundary — but not errored or errors, where no boundary exists after error.

  • 'connection refused' (two words) requires both tokens to be present in the same log line. They can appear in any order and at any position in the line (logical AND, not a phrase search).

  • Wildcards are not supported — use grep for wildcard patterns.

  • Term search is not supported on view queries (_view=…).

Term search vs. grep

Property Term search ('…') Grep ("…")

Match type

Whole words from the Lucene inverted index on log_line

Literal character substring in the reconstructed log body

Token boundaries

Yes — 'error' does not match errored; does match error_count (underscore is a delimiter)

No — "error" matches errored, errors, error_count as character sequences

Case sensitivity

Case-insensitive

Case-sensitive

Wildcards

No

Yes — * and ? supported

Speed

Faster — index lookup

Slower — per-row body reconstruction and scan

Multi-word

Both words present anywhere in the line (AND, any order)

Exact ordered phrase

Use term search when you want whole-word matching and speed. Use grep when you need to match a specific character sequence, a partial word, a camelCase substring, or a wildcard pattern.

Syntax

'term'
'term1 term2'
none

Parameters

Parameter Required Description

term

Yes

A single-quoted word or space-separated words. Each word is matched as a whole lower-cased token from the Lucene index. When multiple words are given, all must appear in the log line (logical AND, any order).

Example

Return log lines that contain the whole word timeout (not timeouts or timed_out):

'timeout'

Return log lines that contain both the word connection and the word refused, in any order:

'connection refused'
Effect

Returns log lines where both connection and refused appear as whole tokens anywhere in the log body. A line such as the connection was refused by the server matches; connection-refused also matches (dash is a token boundary); connectionRefused (no boundary) does not.