Module storm.foundation
Package st.orm.spi

Interface QueryContext

public interface QueryContext
Describes a single statement execution observed by a QueryObserver.

The operation(), dataType() and kind() properties are low-cardinality and suitable as metric tags. The statement() property is high-cardinality and is intended for trace attributes only; it must never be used as a metric tag.

Since:
1.13
See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static enum 
    QueryContext.ExecutionKind
    Classifies how a statement is executed.

  • Method Summary

    Modifier and Type
    Method
    Description
    OptionalInt
    batchSize()
    Returns the number of statements in the batch.
    Optional<Class<? extends Data>>
    dataType()
    Returns the entity or projection type primarily targeted by the statement.
    QueryContext.ExecutionKind
    kind()
    Returns how the statement is executed.
    SqlOperation
    operation()
    Classifies the kind of SQL statement being executed.
    default StatementOrigin
    origin()
    Returns what caused the statement to execute.
    default long
    shapeId()
    Returns the identity of the statement's shape: the template it was generated from, before values were bound.
    Optional<String>
    statement()
    Returns the SQL statement being executed, with all parameters replaced by placeholders.

  • Method Details

    • operation

      SqlOperation operation()
      Classifies the kind of SQL statement being executed.
      Returns:
      the SQL operation; SqlOperation.UNDEFINED when the operation is unknown.

    • dataType

      Optional<Class<? extends Data>> dataType()
      Returns the entity or projection type primarily targeted by the statement.
      Returns:
      the data type, or empty when the statement is not associated with a specific type.

    • kind

      QueryContext.ExecutionKind kind()
      Returns how the statement is executed.
      Returns:
      the execution kind.

    • origin

      default StatementOrigin origin()
      Returns what caused the statement to execute.

      A statement resolving a reference is shaped exactly like a primary key lookup the application could have written itself, so this is what makes the cost of resolving references measurable on its own.

      Returns:
      the statement origin; StatementOrigin.DIRECT unless the statement resolves a reference.

    • shapeId

      default long shapeId()
      Returns the identity of the statement's shape: the template it was generated from, before values were bound.

      Statements generated from one template share a shape whatever their parameters look like, including a collection parameter that expands to a different number of placeholders per execution. Grouping by shape therefore treats those as one statement, where the text would split them.

      Returns:
      the shape identity; 0 when unknown.

    • batchSize

      OptionalInt batchSize()
      Returns the number of statements in the batch.
      Returns:
      the batch size; present only for QueryContext.ExecutionKind.BATCH executions when the size is known at execution time.

    • statement

      Optional<String> statement()
      Returns the SQL statement being executed, with all parameters replaced by placeholders.

      Note: this value is high-cardinality; use it for trace attributes only, never as a metric tag.

      Returns:
      the SQL statement, or empty when no statement text is available.