jsonpath: add support for .size() method

This commit adds support for the `.size()` method in JSONPath queries,
which returns the length of the array or 1 for non-array values (in lax
mode). In strict mode, it returns an error when applied to non-array
values.

This commit also sets up the rest of the JSONPath methods, adding
unimplemented errors when they are parsed.

Release note (sql change): Add support for `.size()` method in JSONPath
expressions. For example, `SELECT jsonb_path_query('[1, 2, 3]',
'$.size()');`.

Author: normanchenn

pkg/sql/logictest/testdata/logic_test/jsonb_path_query

@@ -1428,3 +1428,44 @@ SELECT jsonb_path_query('[1]', '$[-2147483648]');
 # MinInt32 - 1
 statement error pgcode 22033 pq: jsonpath array subscript is out of integer range
 SELECT jsonb_path_query('[1]', '$[-2147483649]');
+
+query T
+SELECT jsonb_path_query('[1, 2]', '$.size()');
+----
+2
+
+query T
+SELECT jsonb_path_query('[]', '$.size()');
+----
+0
+
+query T
+SELECT jsonb_path_query('{}', '$.size()');
+----
+1
+
+statement error pgcode 22039 pq: jsonpath item method .size\(\) can only be applied to an array
+SELECT jsonb_path_query('{}', 'strict $.size()');
+
+query T rowsort
+SELECT jsonb_path_query('[1,null,true,"11",[],[1],[1,2,3],{},{"a":1,"b":2}]', 'lax $[*].size()');
+----
+1
+1
+1
+1
+0
+1
+3
+1
+1
+
+statement error pgcode 22039 pq: jsonpath item method .size\(\) can only be applied to an array
+SELECT jsonb_path_query('[1,null,true,"11",[],[1],[1,2,3],{},{"a":1,"b":2}]', 'strict $[*].size()');
+
+query T rowsort
+SELECT jsonb_path_query('[12, {"a": 13}, {"b": 14}, "ccc", true]', '$[2 - 1 to $.size() - 2]');
+----
+{"a": 13}
+{"b": 14}
+"ccc"

pkg/sql/logictest/testdata/logic_test/jsonpath

@@ -159,6 +159,45 @@ SELECT 'last'::JSONPATH
 statement error pgcode 42601 pq: could not parse "@" as type jsonpath: @ is not allowed in root expressions
 SELECT '@'::JSONPATH
 
+statement error unimplemented
+SELECT '$ ? (@ like_regex ".*" flag "i")'::JSONPATH;
+
+statement error unimplemented
+SELECT '$.type()'::JSONPATH;
+
+statement error unimplemented
+SELECT '$.keyvalue()'::JSONPATH;
+
+statement error unimplemented
+SELECT '$.abs()'::JSONPATH;
+
+statement error unimplemented
+SELECT '$.ceiling()'::JSONPATH;
+
+statement error unimplemented
+SELECT '$.floor()'::JSONPATH;
+
+statement error unimplemented
+SELECT '$.bigint()'::JSONPATH;
+
+statement error unimplemented
+SELECT '$.boolean()'::JSONPATH;
+
+statement error unimplemented
+SELECT '$.date()'::JSONPATH;
+
+statement error unimplemented
+SELECT '$.double()'::JSONPATH;
+
+statement error unimplemented
+SELECT '$.integer()'::JSONPATH;
+
+statement error unimplemented
+SELECT '$.number()'::JSONPATH;
+
+statement error unimplemented
+SELECT '$.string()'::JSONPATH;
+
 ## When we allow table creation
 
 # statement ok

pkg/sql/scanner/jsonpath_scan.go

@@ -57,7 +57,7 @@ func (s *JSONPathScanner) Scan(lval ScanSymType) {
 		// With allowEscapes == false,
 		//  - String literal input "^\\$" is scanned as "^\\\\$" (two escaped backslashes)
 		if s.scanString(lval, identQuote, true /* allowEscapes */, true /* requireUTF8 */) {
-			lval.SetID(lexbase.STRING)
+			lval.SetID(lexbase.STR)
 		}
 		return
 	case '=':

pkg/util/jsonpath/BUILD.bazel

@@ -4,6 +4,7 @@ go_library(
     name = "jsonpath",
     srcs = [
         "expr.go",
+        "method.go",
         "operation.go",
         "scalar.go",
     ],

pkg/util/jsonpath/eval/BUILD.bazel

@@ -7,6 +7,7 @@ go_library(
         "eval.go",
         "filter.go",
         "key.go",
+        "method.go",
         "operation.go",
         "scalar.go",
     ],

pkg/util/jsonpath/eval/eval.go

@@ -189,6 +189,8 @@ func (ctx *jsonpathCtx) eval(
 		return ctx.evalFilter(path, jsonValue, unwrap)
 	case jsonpath.Last:
 		return ctx.evalLast()
+	case jsonpath.Method:
+		return ctx.evalMethod(path, jsonValue)
 	default:
 		return nil, errUnimplemented
 	}

pkg/util/jsonpath/eval/method.go

@@ -0,0 +1,42 @@
+// Copyright 2025 The Cockroach Authors.
+//
+// Use of this software is governed by the CockroachDB Software License
+// included in the /LICENSE file.
+
+package eval
+
+import (
+	"github.com/cockroachdb/cockroach/pkg/sql/pgwire/pgcode"
+	"github.com/cockroachdb/cockroach/pkg/sql/pgwire/pgerror"
+	"github.com/cockroachdb/cockroach/pkg/util/json"
+	"github.com/cockroachdb/cockroach/pkg/util/jsonpath"
+)
+
+var (
+	errEvalSizeNotArray = pgerror.Newf(pgcode.SQLJSONArrayNotFound, "jsonpath item method .size() can only be applied to an array")
+)
+
+func (ctx *jsonpathCtx) evalMethod(
+	method jsonpath.Method, jsonValue json.JSON,
+) ([]json.JSON, error) {
+	switch method.Type {
+	case jsonpath.SizeMethod:
+		size, err := ctx.evalSize(jsonValue)
+		if err != nil {
+			return nil, err
+		}
+		return []json.JSON{json.FromInt(size)}, nil
+	default:
+		return nil, errUnimplemented
+	}
+}
+
+func (ctx *jsonpathCtx) evalSize(jsonValue json.JSON) (int, error) {
+	if jsonValue.Type() != json.ArrayJSONType {
+		if ctx.strict {
+			return -1, errEvalSizeNotArray
+		}
+		return 1, nil
+	}
+	return jsonValue.Len(), nil
+}

pkg/util/jsonpath/method.go

@@ -0,0 +1,29 @@
+// Copyright 2025 The Cockroach Authors.
+//
+// Use of this software is governed by the CockroachDB Software License
+// included in the /LICENSE file.
+
+package jsonpath
+
+import "fmt"
+
+type MethodType int
+
+const (
+	InvalidMethod MethodType = iota
+	SizeMethod
+)
+
+var MethodTypeStrings = map[MethodType]string{
+	SizeMethod: "size",
+}
+
+type Method struct {
+	Type MethodType
+}
+
+var _ Path = Method{}
+
+func (m Method) String() string {
+	return fmt.Sprintf(".%s()", MethodTypeStrings[m.Type])
+}

pkg/util/jsonpath/parser/jsonpath.y

@@ -184,7 +184,7 @@ func regexBinaryOp(left jsonpath.Path, regex string) (jsonpath.Operation, error)
 
 %token <str> CURRENT
 
-%token <str> STRING
+%token <str> STR
 %token <str> NULL
 
 %token <str> LIKE_REGEX
@@ -197,6 +197,24 @@ func regexBinaryOp(left jsonpath.Path, regex string) (jsonpath.Operation, error)
 %token <str> STARTS
 %token <str> WITH
 
+%token <str> SIZE
+
+%token <str> TYPE
+
+%token <str> KEYVALUE
+
+%token <str> ABS
+%token <str> CEILING
+%token <str> FLOOR
+
+%token <str> BIGINT
+%token <str> BOOLEAN
+%token <str> DATE
+%token <str> DOUBLE
+%token <str> INTEGER
+%token <str> NUMBER
+%token <str> STRING
+
 %type <jsonpath.Jsonpath> jsonpath
 %type <jsonpath.Path> expr_or_predicate
 %type <jsonpath.Path> expr
@@ -209,6 +227,7 @@ func regexBinaryOp(left jsonpath.Path, regex string) (jsonpath.Operation, error)
 %type <jsonpath.Path> predicate
 %type <jsonpath.Path> delimited_predicate
 %type <jsonpath.Path> starts_with_initial
+%type <jsonpath.Path> method
 %type <[]jsonpath.Path> accessor_expr
 %type <[]jsonpath.Path> index_list
 %type <jsonpath.OperationType> comp_op
@@ -355,6 +374,10 @@ accessor_op:
   {
     $$.val = jsonpath.AnyKey{}
   }
+| '.' method '(' ')'
+  {
+    $$.val = $2.path()
+  }
 ;
 
 key:
@@ -436,15 +459,15 @@ predicate:
   {
     $$.val = binaryOp(jsonpath.OpStartsWith, $1.path(), $4.path())
   }
-| expr LIKE_REGEX STRING
+| expr LIKE_REGEX STR
   {
     regex, err := regexBinaryOp($1.path(), $3)
     if err != nil {
       return setErr(jsonpathlex, err)
     }
     $$.val = regex
   }
-| expr LIKE_REGEX STRING FLAG STRING
+| expr LIKE_REGEX STR FLAG STR
   {
     return unimplemented(jsonpathlex, "regex with flags")
   }
@@ -462,7 +485,7 @@ delimited_predicate:
 ;
 
 starts_with_initial:
-  STRING
+  STR
   {
     $$.val = jsonpath.Scalar{Type: jsonpath.ScalarString, Value: json.FromString($1)}
   }
@@ -499,6 +522,61 @@ comp_op:
   }
 ;
 
+method:
+  SIZE
+  {
+    $$.val = jsonpath.Method{Type: jsonpath.SizeMethod}
+  }
+| TYPE
+  {
+    return unimplemented(jsonpathlex, ".type()")
+  }
+| KEYVALUE
+  {
+    return unimplemented(jsonpathlex, ".keyvalue()")
+  }
+| ABS
+  {
+    return unimplemented(jsonpathlex, ".abs()")
+  }
+| CEILING
+  {
+    return unimplemented(jsonpathlex, ".ceiling()")
+  }
+| FLOOR
+  {
+    return unimplemented(jsonpathlex, ".floor()")
+  }
+| BIGINT
+  {
+    return unimplemented(jsonpathlex, ".bigint()")
+  }
+| BOOLEAN
+  {
+    return unimplemented(jsonpathlex, ".boolean()")
+  }
+| DATE
+  {
+    return unimplemented(jsonpathlex, ".date()")
+  }
+| DOUBLE
+  {
+    return unimplemented(jsonpathlex, ".double()")
+  }
+| INTEGER
+  {
+    return unimplemented(jsonpathlex, ".integer()")
+  }
+| NUMBER
+  {
+    return unimplemented(jsonpathlex, ".number()")
+  }
+| STRING
+  {
+    return unimplemented(jsonpathlex, ".string()")
+  }
+;
+
 scalar_value:
   VARIABLE
   {
@@ -532,7 +610,7 @@ scalar_value:
   {
     $$.val = jsonpath.Scalar{Type: jsonpath.ScalarBool, Value: json.FromBool(false)}
   }
-| STRING
+| STR
   {
     $$.val = jsonpath.Scalar{Type: jsonpath.ScalarString, Value: json.FromString($1)}
   }
@@ -544,23 +622,36 @@ scalar_value:
 
 any_identifier:
   IDENT
-| STRING
+| STR
 | unreserved_keyword
 ;
 
 unreserved_keyword:
-  EXISTS
+  ABS
+| BIGINT
+| BOOLEAN
+| CEILING
+| DATE
+| DOUBLE
+| EXISTS
 | FALSE
 | FLAG
+| FLOOR
+| INTEGER
 | IS
+| KEYVALUE
 | LAST
 | LAX
 | LIKE_REGEX
 | NULL
+| NUMBER
+| SIZE
 | STARTS
 | STRICT
+| STRING
 | TO
 | TRUE
+| TYPE
 | UNKNOWN
 | WITH
 ;

pkg/util/jsonpath/parser/parse.go

@@ -177,7 +177,7 @@ func walk(path jsonpath.Path, nestingLevel int, insideArraySubscript bool) error
 		}
 		return nil
 	case jsonpath.Root, jsonpath.Key, jsonpath.Wildcard, jsonpath.Regex,
-		jsonpath.AnyKey, jsonpath.Scalar:
+		jsonpath.AnyKey, jsonpath.Scalar, jsonpath.Method:
 		// These are leaf nodes that don't require any further checks.
 		return nil
 	default: