chore(engine): Add first stage of physical query planning

pkg/engine/internal/types/column.go

@@ -0,0 +1,32 @@
+package types
+
+import "fmt"
+
+// ColumnType denotes the column type for a [ColumnRef].
+type ColumnType int
+
+// Recognized values of [ColumnType].
+const (
+	// ColumnTypeInvalid indicates an invalid column type.
+	ColumnTypeInvalid ColumnType = iota
+
+	ColumnTypeBuiltin  // ColumnTypeBuiltin represents a builtin column (such as timestamp).
+	ColumnTypeLabel    // ColumnTypeLabel represents a column from a stream label.
+	ColumnTypeMetadata // ColumnTypeMetadata represents a column from a log metadata.
+)
+
+// String returns a human-readable representation of the column type.
+func (ct ColumnType) String() string {
+	switch ct {
+	case ColumnTypeInvalid:
+		return typeInvalid
+	case ColumnTypeBuiltin:
+		return "builtin"
+	case ColumnTypeLabel:
+		return "label"
+	case ColumnTypeMetadata:
+		return "metadata"
+	default:
+		return fmt.Sprintf("ColumnType(%d)", ct)
+	}
+}

pkg/engine/internal/types/literal.go

@@ -0,0 +1,38 @@
+package types
+
+import "fmt"
+
+// LiteralKind denotes the kind of [Literal] value.
+type LiteralKind int
+
+// Recognized values of [LiteralKind].
+const (
+	// LiteralKindInvalid indicates an invalid literal value.
+	LiteralKindInvalid LiteralKind = iota
+
+	LiteralKindNull      // NULL literal value.
+	LiteralKindString    // String literal value.
+	LiteralKindInt64     // 64-bit integer literal value.
+	LiteralKindUint64    // 64-bit unsigned integer literal value.
+	LiteralKindByteArray // Byte array literal value.
+)
+
+// String returns the string representation of the LiteralKind.
+func (k LiteralKind) String() string {
+	switch k {
+	case LiteralKindInvalid:
+		return typeInvalid
+	case LiteralKindNull:
+		return "null"
+	case LiteralKindString:
+		return "string"
+	case LiteralKindInt64:
+		return "int64"
+	case LiteralKindUint64:
+		return "uint64"
+	case LiteralKindByteArray:
+		return "[]byte"
+	default:
+		return fmt.Sprintf("LiteralKind(%d)", k)
+	}
+}

pkg/engine/internal/types/operators.go

@@ -0,0 +1,108 @@
+package types
+
+import "fmt"
+
+// UnaryOp denotes the kind of [UnaryOp] operation to perform.
+type UnaryOp uint32
+
+// Recognized values of [UnaryOp].
+const (
+	// UnaryOpKindInvalid indicates an invalid unary operation.
+	UnaryOpInvalid UnaryOp = iota
+
+	UnaryOpNot // Logical NOT operation (!).
+	UnaryOpAbs // Mathematical absolute operation (abs).
+)
+
+// String returns the string representation of the UnaryOp.
+func (t UnaryOp) String() string {
+	switch t {
+	case UnaryOpInvalid:
+		return typeInvalid
+	case UnaryOpNot:
+		return "NOT"
+	case UnaryOpAbs:
+		return "ABS"
+	default:
+		panic(fmt.Sprintf("unknown unary operator %d", t))
+	}
+}
+
+// BinaryOp denotes the kind of [BinaryOp] operation to perform.
+type BinaryOp uint32
+
+// Recognized values of [BinaryOp].
+const (
+	// BinaryOpInvalid indicates an invalid binary operation.
+	BinaryOpInvalid BinaryOp = iota
+
+	BinaryOpEq  // Equality comparison (==).
+	BinaryOpNeq // Inequality comparison (!=).
+	BinaryOpGt  // Greater than comparison (>).
+	BinaryOpGte // Greater than or equal comparison (>=).
+	BinaryOpLt  // Less than comparison (<).
+	BinaryOpLte // Less than or equal comparison (<=).
+	BinaryOpAnd // Logical AND operation (&&).
+	BinaryOpOr  // Logical OR operation (||).
+	BinaryOpXor // Logical XOR operation (^).
+	BinaryOpNot // Logical NOT operation (!).
+
+	BinaryOpAdd // Addition operation (+).
+	BinaryOpSub // Subtraction operation (-).
+	BinaryOpMul // Multiplication operation (*).
+	BinaryOpDiv // Division operation (/).
+	BinaryOpMod // Modulo operation (%).
+
+	BinaryOpMatchStr    // String matching operation (|=).
+	BinaryOpNotMatchStr // String non-matching operation (!=).
+	BinaryOpMatchRe     // Regular expression matching operation (|~).
+	BinaryOpNotMatchRe  // Regular expression non-matching operation (!~).
+)
+
+// String returns a human-readable representation of the binary operation kind.
+func (t BinaryOp) String() string {
+	switch t {
+	case BinaryOpInvalid:
+		return typeInvalid
+	case BinaryOpEq:
+		return "EQ"
+	case BinaryOpNeq:
+		return "NEQ" // convenience for NOT(EQ(expr))
+	case BinaryOpGt:
+		return "GT"
+	case BinaryOpGte:
+		return "GTE"
+	case BinaryOpLt:
+		return "LT" // convenience for NOT(GTE(expr))
+	case BinaryOpLte:
+		return "LTE" // convenience for NOT(GT(expr))
+	case BinaryOpAnd:
+		return "AND"
+	case BinaryOpOr:
+		return "OR"
+	case BinaryOpXor:
+		return "XOR"
+	case BinaryOpNot:
+		return "NOT"
+	case BinaryOpAdd:
+		return "ADD"
+	case BinaryOpSub:
+		return "SUB"
+	case BinaryOpMul:
+		return "MUL"
+	case BinaryOpDiv:
+		return "DIV"
+	case BinaryOpMod:
+		return "MOD"
+	case BinaryOpMatchStr:
+		return "MATCH_STR"
+	case BinaryOpNotMatchStr:
+		return "NOT_MATCH_STR" // convenience for NOT(MATCH_STR(...))
+	case BinaryOpMatchRe:
+		return "MATCH_RE"
+	case BinaryOpNotMatchRe:
+		return "NOT_MATCH_RE" // convenience for NOT(MATCH_RE(...))
+	default:
+		panic(fmt.Sprintf("unknown binary operator %d", t))
+	}
+}

pkg/engine/internal/types/value.go

@@ -0,0 +1,19 @@
+package types
+
+const (
+	typeInvalid = "invalid"
+)
+
+// ValueType represents the type of a value, which can either be a literal value, or a column value.
+type ValueType uint32
+
+const (
+	ValueTypeInvalid ValueType = iota // zero-value is an invalid type
+
+	ValueTypeNull      // NULL value.
+	ValueTypeBool      // Boolean value
+	ValueTypeInt       // Signed 64bit integer value
+	ValueTypeTimestamp // Unsigned 64bit integer value (nanosecond timestamp)
+	ValueTypeStr       // String value
+	ValueTypeBytes     // Byte-slice value
+)

pkg/engine/planner/logical/column_ref.go

@@ -3,43 +3,15 @@ package logical
 import (
 	"fmt"
 
+	"github.com/grafana/loki/v3/pkg/engine/internal/types"
 	"github.com/grafana/loki/v3/pkg/engine/planner/schema"
 )
 
-// ColumnType denotes the column type for a [ColumnRef].
-type ColumnType int
-
-// Recognized values of [ColumnType].
-const (
-	// ColumnTypeInvalid indicates an invalid column type.
-	ColumnTypeInvalid ColumnType = iota
-
-	ColumnTypeBuiltin  // ColumnTypeBuiltin represents a builtin column (such as timestamp).
-	ColumnTypeLabel    // ColumnTypeLabel represents a column from a stream label.
-	ColumnTypeMetadata // ColumnTypeMetadata represents a column from a log metadata.
-)
-
-// String returns a human-readable representation of the column type.
-func (ct ColumnType) String() string {
-	switch ct {
-	case ColumnTypeInvalid:
-		return "invalid"
-	case ColumnTypeBuiltin:
-		return "builtin"
-	case ColumnTypeLabel:
-		return "label"
-	case ColumnTypeMetadata:
-		return "metadata"
-	default:
-		return fmt.Sprintf("ColumnType(%d)", ct)
-	}
-}
-
 // A ColumnRef referenes a column within a table relation. ColumnRef only
 // implements [Value].
 type ColumnRef struct {
-	Column string     // Name of the column being referenced.
-	Type   ColumnType // Type of the column being referenced.
+	Column string           // Name of the column being referenced.
+	Type   types.ColumnType // Type of the column being referenced.
 }
 
 var (

pkg/engine/planner/logical/format_tree_test.go

@@ -6,6 +6,7 @@ import (
 
 	"github.com/stretchr/testify/require"
 
+	"github.com/grafana/loki/v3/pkg/engine/internal/types"
 	"github.com/grafana/loki/v3/pkg/engine/planner/schema"
 )
 
@@ -23,16 +24,16 @@ func TestFormatSimpleQuery(t *testing.T) {
 	b := NewBuilder(
 		&MakeTable{
 			Selector: &BinOp{
-				Left:  &ColumnRef{Column: "app", Type: ColumnTypeLabel},
+				Left:  &ColumnRef{Column: "app", Type: types.ColumnTypeLabel},
 				Right: LiteralString("users"),
-				Op:    BinOpKindEq,
+				Op:    types.BinaryOpEq,
 			},
 		},
 	).Select(
 		&BinOp{
-			Left:  &ColumnRef{Column: "age", Type: ColumnTypeMetadata},
+			Left:  &ColumnRef{Column: "age", Type: types.ColumnTypeMetadata},
 			Right: LiteralInt64(21),
-			Op:    BinOpKindGt,
+			Op:    types.BinaryOpGt,
 		},
 	)
 
@@ -63,18 +64,18 @@ func TestFormatSortQuery(t *testing.T) {
 	b := NewBuilder(
 		&MakeTable{
 			Selector: &BinOp{
-				Left:  &ColumnRef{Column: "app", Type: ColumnTypeLabel},
+				Left:  &ColumnRef{Column: "app", Type: types.ColumnTypeLabel},
 				Right: LiteralString("users"),
-				Op:    BinOpKindEq,
+				Op:    types.BinaryOpEq,
 			},
 		},
 	).Select(
 		&BinOp{
-			Left:  &ColumnRef{Column: "age", Type: ColumnTypeMetadata},
+			Left:  &ColumnRef{Column: "age", Type: types.ColumnTypeMetadata},
 			Right: LiteralInt64(21),
-			Op:    BinOpKindGt,
+			Op:    types.BinaryOpGt,
 		},
-	).Sort(ColumnRef{Column: "age", Type: ColumnTypeMetadata}, true, false)
+	).Sort(ColumnRef{Column: "age", Type: types.ColumnTypeMetadata}, true, false)
 
 	var sb strings.Builder
 	PrintTree(&sb, b.Value())

pkg/engine/planner/logical/logical_test.go

@@ -6,6 +6,8 @@ import (
 	"testing"
 
 	"github.com/stretchr/testify/require"
+
+	"github.com/grafana/loki/v3/pkg/engine/internal/types"
 )
 
 func TestPlan_String(t *testing.T) {
@@ -15,18 +17,18 @@ func TestPlan_String(t *testing.T) {
 	b := NewBuilder(
 		&MakeTable{
 			Selector: &BinOp{
-				Left:  &ColumnRef{Column: "app", Type: ColumnTypeLabel},
+				Left:  &ColumnRef{Column: "app", Type: types.ColumnTypeLabel},
 				Right: LiteralString("users"),
-				Op:    BinOpKindEq,
+				Op:    types.BinaryOpEq,
 			},
 		},
 	).Select(
 		&BinOp{
-			Left:  &ColumnRef{Column: "age", Type: ColumnTypeMetadata},
+			Left:  &ColumnRef{Column: "age", Type: types.ColumnTypeMetadata},
 			Right: LiteralInt64(21),
-			Op:    BinOpKindGt,
+			Op:    types.BinaryOpGt,
 		},
-	).Sort(ColumnRef{Column: "age", Type: ColumnTypeMetadata}, true, false)
+	).Sort(ColumnRef{Column: "age", Type: types.ColumnTypeMetadata}, true, false)
 
 	// Convert to SSA
 	ssaForm, err := b.ToPlan()