Text search operators :: Kloudfuse Docs

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"

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

_count	kube_deployment
316505	kfuse-ingress-ingress-nginx-controller

Expected output


	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"

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.

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.

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.

Syntax

"expression"
"wild*card"

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.

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.

Syntax

Regular search

key exists="facetName"

Advanced search

@facetName

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.

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"

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.

!~

Regex exclusion filter operator. Selects log lines where a label or facet value does not match the specified regular expression pattern. The match is full-value by default — the pattern is automatically anchored, so label!~"foo" excludes lines where the value is exactly "foo", not lines where it merely contains "foo".

Syntax

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

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

not-term (negated single-quote search)

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

Syntax

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

Parameters

Parameter	Required	Description
`'term'`	Yes	A single-quoted word or space-separated words. Each word is matched independently as a whole token. A log line is excluded only if it contains all listed tokens as whole words.

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 kube-healthcheck are also excluded — the hyphen is a token boundary, making healthcheck a distinct token.

=~

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

Syntax

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

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

*~

Prefix match filter operator. Selects log lines where a label or facet value begins with the specified string.