Class LogQL

java.lang.Object
codes.grow.packages.loki.LogQL

public final class LogQL extends Object
Immutable LogQL query builder with safe escaping. Every method returns a new builder.

 LogQL.selector(Map.of("app", "x")).lineContains("err").json().where("status", ">=", 500).build()
 // {app="x"} |= "err" | json | status >= 500
 

String literals are double-quoted with Go/JSON escaping (verified against Loki 3.7).

  • Method Details

    • selector

      public static LogQL selector(Map<String,String> labels)
      Starts a query from equality matchers ({app="x", env="prod"}, names sorted).
      Parameters:
      labels - label name → value
      Returns:
      the builder
    • quote

      public static String quote(String value)
      Quotes a LogQL string literal with Go/JSON escaping (", \, control characters); other Unicode stays as is.
      Parameters:
      value - text
      Returns:
      the quoted literal
    • label

      public LogQL label(String name, String op, String value)
      Adds a stream-selector matcher.
      Parameters:
      name - label name
      op - =, !=, =~ or !~
      value - value or RE2 regex
      Returns:
      a new builder
    • lineContains

      public LogQL lineContains(String text)
      Line filter |= "text" (case-sensitive substring).
      Parameters:
      text - text
      Returns:
      a new builder
    • lineNotContains

      public LogQL lineNotContains(String text)
      Line filter != "text".
      Parameters:
      text - text
      Returns:
      a new builder
    • lineMatches

      public LogQL lineMatches(String regex)
      Line filter |~ "regex" (RE2; prefix (?i) for case-insensitive).
      Parameters:
      regex - regex
      Returns:
      a new builder
    • lineNotMatches

      public LogQL lineNotMatches(String regex)
      Line filter !~ "regex".
      Parameters:
      regex - regex
      Returns:
      a new builder
    • json

      public LogQL json()
      Parser stage | json.
      Returns:
      a new builder
    • logfmt

      public LogQL logfmt()
      Parser stage | logfmt.
      Returns:
      a new builder
    • unpack

      public LogQL unpack()
      Parser stage | unpack.
      Returns:
      a new builder
    • regexp

      public LogQL regexp(String pattern)
      Parser stage | regexp "<re>" with named capture groups.
      Parameters:
      pattern - RE2 pattern
      Returns:
      a new builder
    • pattern

      public LogQL pattern(String pattern)
      Parser stage | pattern "<pattern>".
      Parameters:
      pattern - pattern expression
      Returns:
      a new builder
    • lineFormat

      public LogQL lineFormat(String template)
      Formatting stage | line_format "<template>".
      Parameters:
      template - Go template
      Returns:
      a new builder
    • where

      public LogQL where(String field, String op, String value)
      Label filter on an extracted label or structured-metadata key, comparing strings with =, !=, =~, !~.
      Parameters:
      field - label name
      op - operator
      value - value
      Returns:
      a new builder
    • where

      public LogQL where(String field, String op, double value)
      Numeric label filter with ==, !=, >, >=, <, <=.
      Parameters:
      field - label name
      op - operator
      value - finite number
      Returns:
      a new builder
    • pipe

      public LogQL pipe(String stage)
      Appends a raw pipeline stage (| <stage>), e.g. drop level.
      Parameters:
      stage - stage text without the leading pipe
      Returns:
      a new builder
    • build

      public String build()
      Renders the query.
      Returns:
      LogQL text
      Throws:
      ValidationException - when the selector is empty or every matcher also matches the empty value (Loki rejects such selectors)
    • toString

      public String toString()
      Same as build().
      Overrides:
      toString in class Object
      Returns:
      LogQL text