Merge #149912

149912: sql: add LTREE util package r=paulniziolek a=paulniziolek

#### sql: add ltree util pkg with basic functionality

The newly introduced ltree pkg introduces the basic underlying LTREE internals
for when the LTREE type is to be introduced into CRDB, such as the data
structure, ltree parsing and validation, and accessory methods.

Informs: #44657
Epic: CRDB-148

Release note: None


Co-authored-by: Paul Niziolek <[email protected]>

Author: craig[bot]

.github/CODEOWNERS

@@ -618,6 +618,7 @@
 /pkg/util/intsets/           @cockroachdb/sql-queries-prs
 /pkg/util/json/              @cockroachdb/sql-queries-prs
 /pkg/util/jsonpath/          @cockroachdb/sql-queries-prs
+/pkg/util/ltree/             @cockroachdb/sql-queries-prs
 /pkg/util/log/               @cockroachdb/obs-prs @cockroachdb/obs-india-prs
 /pkg/util/metric/            @cockroachdb/obs-prs @cockroachdb/obs-india-prs
 /pkg/util/mon                @cockroachdb/sql-queries-prs

pkg/BUILD.bazel

@@ -767,6 +767,7 @@ ALL_TESTS = [
     "//pkg/util/log/logmetrics:logmetrics_test",
     "//pkg/util/log/testshout:testshout_test",
     "//pkg/util/log:log_test",
+    "//pkg/util/ltree:ltree_test",
     "//pkg/util/metamorphic:metamorphic_test",
     "//pkg/util/metric/aggmetric:aggmetric_test",
     "//pkg/util/metric:metric_test",
@@ -2671,6 +2672,8 @@ GO_TARGETS = [
     "//pkg/util/log/testshout:testshout_test",
     "//pkg/util/log:log",
     "//pkg/util/log:log_test",
+    "//pkg/util/ltree:ltree",
+    "//pkg/util/ltree:ltree_test",
     "//pkg/util/memzipper:memzipper",
     "//pkg/util/metamorphic/metamorphicutil:metamorphicutil",
     "//pkg/util/metamorphic:metamorphic",

pkg/util/ltree/BUILD.bazel

@@ -0,0 +1,19 @@
+load("@io_bazel_rules_go//go:def.bzl", "go_library", "go_test")
+
+go_library(
+    name = "ltree",
+    srcs = ["ltree.go"],
+    importpath = "github.com/cockroachdb/cockroach/pkg/util/ltree",
+    visibility = ["//visibility:public"],
+    deps = [
+        "//pkg/sql/pgwire/pgcode",
+        "//pkg/sql/pgwire/pgerror",
+        "@com_github_cockroachdb_errors//:errors",
+    ],
+)
+
+go_test(
+    name = "ltree_test",
+    srcs = ["ltree_test.go"],
+    embed = [":ltree"],
+)

pkg/util/ltree/ltree.go

@@ -0,0 +1,215 @@
+// Copyright 2025 The Cockroach Authors.
+//
+// Use of this software is governed by the CockroachDB Software License
+// included in the /LICENSE file.
+
+package ltree
+
+import (
+	"bytes"
+	"strings"
+
+	"github.com/cockroachdb/cockroach/pkg/sql/pgwire/pgcode"
+	"github.com/cockroachdb/cockroach/pkg/sql/pgwire/pgerror"
+	"github.com/cockroachdb/errors"
+)
+
+const (
+	PathSeparator = "."
+	// Postgres imposes a 65535 limit on the number of labels in a ltree.
+	maxNumOfLabels = 65535
+	// Postgres docs mention labels must be less than 256 bytes, but in practice,
+	// Postgres has a limit on up to 1000 characters.
+	maxLabelLength = 1000
+)
+
+var (
+	// Empty represents the LTree path "".
+	Empty         = T{}
+	errEmptyLabel = pgerror.New(pgcode.Syntax, "label cannot be empty")
+)
+
+// T represents a LTREE path.
+type T struct {
+	// path is an ordered slice of string labels that make up a path in a LTREE column.
+	path []string
+}
+
+// ParseLTree parses a string representation of a path into a T struct.
+func ParseLTree(pathStr string) (T, error) {
+	labels := strings.Split(pathStr, PathSeparator)
+	if len(labels) > maxNumOfLabels {
+		return T{}, pgerror.Newf(pgcode.ProgramLimitExceeded, "number of ltree labels (%d) exceeds the maximum allowed (%d)", len(labels), maxNumOfLabels)
+	}
+	for _, label := range labels {
+		err := validateLabel(label)
+		if err != nil {
+			if errors.Is(err, errEmptyLabel) && len(labels) == 1 {
+				// If the only label is empty, we treat it as a valid empty path.
+				return Empty, nil
+			}
+			return Empty, err
+		}
+	}
+	return T{path: labels}, nil
+}
+
+// String returns the string representation of T.
+func (lt T) String() string {
+	var b bytes.Buffer
+	lt.FormatToBuffer(&b)
+	return b.String()
+}
+
+// FormatToBuffer formats the LTREE path into a bytes.Buffer,
+// using the PathSeparator.
+func (lt T) FormatToBuffer(buf *bytes.Buffer) {
+	for i, l := range lt.path {
+		if i > 0 {
+			buf.WriteString(PathSeparator)
+		}
+		buf.WriteString(l)
+	}
+}
+
+// ByteSize returns the size of the T in bytes, which is the sum of the label
+// lengths and their path separators.
+func (lt T) ByteSize() int {
+	size := 0
+	for i, l := range lt.path {
+		if i > 0 {
+			size += len(PathSeparator)
+		}
+		size += len(l)
+	}
+	return size
+}
+
+// ForEachLabel iterates over each label in the LTREE path,
+// calling the provided function with the index and label.
+func (lt T) ForEachLabel(fn func(int, string)) {
+	for i, l := range lt.path {
+		fn(i, l)
+	}
+}
+
+// LabelAt returns the label at the specified index in an LTree path.
+func (lt T) LabelAt(idx int) (string, error) {
+	if idx < 0 || idx >= lt.Len() {
+		return "", pgerror.Newf(pgcode.InvalidParameterValue, "index %d out of bounds", idx)
+	}
+	return lt.path[idx], nil
+}
+
+// Compare compares two LTrees lexicographically based on their labels.
+func (lt T) Compare(other T) int {
+	minLen := min(lt.Len(), other.Len())
+
+	for i := 0; i < minLen; i++ {
+		if cmp := strings.Compare(lt.path[i], other.path[i]); cmp != 0 {
+			return cmp
+		}
+	}
+
+	if lt.Len() < other.Len() {
+		return -1
+	} else if lt.Len() > other.Len() {
+		return 1
+	}
+	return 0
+}
+
+// Len returns the number of labels in the T.
+func (lt T) Len() int {
+	return len(lt.path)
+}
+
+// Copy creates a copy of T.
+func (lt T) Copy() T {
+	copiedLabels := make([]string, lt.Len())
+	copy(copiedLabels, lt.path)
+	return T{path: copiedLabels}
+}
+
+// Prev returns the lexicographically previous LTree and a bool
+// indicating whether it exists.
+func (lt T) Prev() (T, bool) {
+	if lt.Len() == 0 {
+		return Empty, false
+	}
+
+	lastLabel := lt.path[lt.Len()-1]
+	if l := prevLabel(lastLabel); l != "" {
+		result := lt.Copy()
+		result.path[lt.Len()-1] = l
+		return result, true
+	}
+
+	if lt.Len() > 1 {
+		return T{path: lt.path[:lt.Len()-1]}, true
+	}
+
+	return Empty, true
+}
+
+// validateLabel checks if a label is valid and returns an error if it is not,
+// otherwise, it returns nil.
+// A label is valid if it:
+// - is not empty
+// - does not exceed the maximum length
+// - contains only valid characters: '-', '0'-'9', 'A'-'Z', '_', 'a'-'z'
+func validateLabel(l string) error {
+	if len(l) > maxLabelLength {
+		return pgerror.Newf(pgcode.NameTooLong, "label length is %d, must be at most %d", len(l), maxLabelLength)
+	}
+	if l == "" {
+		return errEmptyLabel
+	}
+	for _, c := range l {
+		if !isValidChar(byte(c)) {
+			return pgerror.Newf(pgcode.Syntax, "label contains invalid character %c", c)
+		}
+	}
+	return nil
+}
+
+// prevLabel returns the lexicographically previous label or empty string if
+// none exists.
+func prevLabel(s string) string {
+	if len(s) == 0 {
+		return ""
+	}
+
+	lastChar := s[len(s)-1]
+	if prev := prevChar(lastChar); prev != 0 {
+		return s[:len(s)-1] + string(prev)
+	}
+
+	if len(s) > 1 {
+		return s[:len(s)-1]
+	}
+
+	return ""
+}
+
+// isValidChar returns true if the character is valid in an LTree label.
+func isValidChar(c byte) bool {
+	return (c >= '0' && c <= '9') || (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z') || (c == '_') || (c == '-')
+}
+
+var prevCharMap = map[byte]byte{
+	'-': 0,
+	'0': '-',
+	'A': '9',
+	'_': 'Z',
+	'a': '_',
+}
+
+// prevChar returns the previous valid character assuming a given valid
+// character, or 0 if none exists.
+func prevChar(c byte) byte {
+	if prev, ok := prevCharMap[c]; ok {
+		return prev
+	}
+	return c - 1
+}