Add SQL:2023 non-static method invocation

SQL:2023 specifies <method invocation>, expr.method(args), as a sibling
of <static method invocation>. Where T::method(args) namespaces a
function under a type, expr.method(args) dispatches on the runtime type
of the receiver and passes it as the implicit self argument.

Functions tagged with the new @instancemethod SPI annotation register
with a receiver type taken from their first @SqlType parameter and
become callable only as expr.method(args). A plain method(args) call
cannot resolve to an instance method, mirroring the static-method
namespace separation.

The receiver expression form (expr).method(args) parses unambiguously
as a method call. The bare A.B(args) form (where A is in scope as a
column) keeps parsing as a routine invocation but, per SQL:2023 6.3
Syntax Rule 2, the analyzer treats it as a method invocation when one
applies and only falls back to function resolution otherwise.

Author: martint

core/trino-grammar/src/main/antlr4/io/trino/grammar/sql/SqlBase.g4

@@ -606,6 +606,7 @@ primaryExpression
     | processingMode? qualifiedName '(' (setQuantifier? expression (',' expression)*)?
         orderBy? ')' filter? (nullTreatment? over)?                                       #functionCall
     | qualifiedName '::' identifier '(' (expression (',' expression)*)? ')'               #staticMethodCall
+    | primaryExpression '.' identifier '(' (expression (',' expression)*)? ')'            #methodCall
     | identifier over                                                                     #measure
     | identifier '->' expression                                                          #lambda
     | '(' (identifier (',' identifier)*)? ')' '->' expression                             #lambda

core/trino-main/src/main/java/io/trino/metadata/FunctionResolver.java

@@ -146,7 +146,8 @@ public ResolvedFunction resolveStaticMethod(
                 parameterTypes,
                 catalogSchemaFunctionName -> filterCandidates(
                         metadata.getFunctions(session, catalogSchemaFunctionName),
-                        candidate -> candidate.functionMetadata().getReceiverType()
+                        candidate -> !candidate.functionMetadata().isInstanceMethod()
+                                && candidate.functionMetadata().getReceiverType()
                                 .map(TypeSignature::getBase).equals(Optional.of(receiver))),
                 accessControl);
 
@@ -158,6 +159,33 @@ public ResolvedFunction resolveStaticMethod(
         return resolve(session, catalogFunctionBinding, accessControl);
     }
 
+    public ResolvedFunction resolveInstanceMethod(
+            Session session,
+            TypeSignature receiverType,
+            QualifiedName methodName,
+            List<TypeSignatureProvider> parameterTypes,
+            AccessControl accessControl)
+    {
+        String receiver = receiverType.getBase();
+        CatalogFunctionBinding catalogFunctionBinding = bindFunction(
+                session,
+                methodName,
+                parameterTypes,
+                catalogSchemaFunctionName -> filterCandidates(
+                        metadata.getFunctions(session, catalogSchemaFunctionName),
+                        candidate -> candidate.functionMetadata().isInstanceMethod()
+                                && candidate.functionMetadata().getReceiverType()
+                                .map(TypeSignature::getBase).equals(Optional.of(receiver))),
+                accessControl);
+
+        FunctionMetadata functionMetadata = catalogFunctionBinding.boundFunctionMetadata();
+        if (functionMetadata.isDeprecated()) {
+            warningCollector.add(new TrinoWarning(DEPRECATED_FUNCTION, "Use of deprecated function: %s.%s: %s".formatted(receiverType, methodName, functionMetadata.getDescription())));
+        }
+
+        return resolve(session, catalogFunctionBinding, accessControl);
+    }
+
     private static Collection<CatalogFunctionMetadata> filterCandidates(
             Collection<CatalogFunctionMetadata> candidates,
             Predicate<CatalogFunctionMetadata> predicate)

core/trino-main/src/main/java/io/trino/operator/scalar/ParametricScalar.java

@@ -81,7 +81,14 @@ private static FunctionMetadata createFunctionMetadata(Signature signature, Scal
         if (deprecated) {
             functionMetadata.deprecated();
         }
-        details.getReceiverType().ifPresent(functionMetadata::receiverType);
+        if (details.isInstanceMethod()) {
+            checkCondition(!signature.getArgumentTypes().isEmpty(), FUNCTION_IMPLEMENTATION_ERROR, "Instance method %s must declare a self argument", details.getName());
+            functionMetadata.receiverType(signature.getArgumentTypes().getFirst());
+            functionMetadata.instanceMethod();
+        }
+        else {
+            details.getReceiverType().ifPresent(functionMetadata::receiverType);
+        }
 
         if (functionNullability.isReturnNullable()) {
             functionMetadata.nullable();

core/trino-main/src/main/java/io/trino/operator/scalar/ScalarHeader.java

@@ -15,6 +15,7 @@
 
 import com.google.common.collect.ImmutableList;
 import com.google.common.collect.ImmutableSet;
+import io.trino.spi.function.InstanceMethod;
 import io.trino.spi.function.OperatorType;
 import io.trino.spi.function.ScalarFunction;
 import io.trino.spi.function.ScalarOperator;
@@ -45,13 +46,14 @@ public class ScalarHeader
     private final boolean deterministic;
     private final boolean neverFails;
     private final Optional<TypeSignature> receiverType;
+    private final boolean instanceMethod;
 
     public ScalarHeader(String name, Set<String> aliases, Optional<String> description, boolean hidden, boolean deterministic, boolean neverFails)
     {
-        this(name, aliases, description, hidden, deterministic, neverFails, Optional.empty());
+        this(name, aliases, description, hidden, deterministic, neverFails, Optional.empty(), false);
     }
 
-    public ScalarHeader(String name, Set<String> aliases, Optional<String> description, boolean hidden, boolean deterministic, boolean neverFails, Optional<TypeSignature> receiverType)
+    public ScalarHeader(String name, Set<String> aliases, Optional<String> description, boolean hidden, boolean deterministic, boolean neverFails, Optional<TypeSignature> receiverType, boolean instanceMethod)
     {
         this.name = requireNonNull(name, "name is null");
         checkArgument(!name.isEmpty());
@@ -63,6 +65,8 @@ public ScalarHeader(String name, Set<String> aliases, Optional<String> descripti
         this.deterministic = deterministic;
         this.neverFails = neverFails;
         this.receiverType = requireNonNull(receiverType, "receiverType is null");
+        checkArgument(!instanceMethod || receiverType.isEmpty(), "instance method receiver type is inferred from the first argument");
+        this.instanceMethod = instanceMethod;
     }
 
     public ScalarHeader(OperatorType operatorType, Optional<String> description)
@@ -75,30 +79,36 @@ public ScalarHeader(OperatorType operatorType, Optional<String> description)
         this.deterministic = true;
         this.neverFails = false;
         this.receiverType = Optional.empty();
+        this.instanceMethod = false;
     }
 
     public static List<ScalarHeader> fromAnnotatedElement(AnnotatedElement annotated)
     {
         ScalarFunction scalarFunction = annotated.getAnnotation(ScalarFunction.class);
         ScalarOperator scalarOperator = annotated.getAnnotation(ScalarOperator.class);
         StaticMethod staticMethod = annotated.getAnnotation(StaticMethod.class);
+        InstanceMethod instanceMethod = annotated.getAnnotation(InstanceMethod.class);
         Optional<String> description = parseDescription(annotated);
 
         ImmutableList.Builder<ScalarHeader> builder = ImmutableList.builder();
 
         if (scalarFunction != null) {
+            checkArgument(staticMethod == null || instanceMethod == null, "@StaticMethod and @InstanceMethod are mutually exclusive on %s", annotated);
             String baseName = scalarFunction.value().isEmpty() ? camelToSnake(annotatedName(annotated)) : scalarFunction.value();
             Optional<TypeSignature> receiverType = Optional.empty();
             if (staticMethod != null) {
                 TypeSignature parsed = parseTypeSignature(staticMethod.value(), ImmutableSet.of());
                 checkArgument(parsed.getParameters().isEmpty(), "@StaticMethod receiver type must not have parameters: %s", staticMethod.value());
                 receiverType = Optional.of(parsed);
             }
-            builder.add(new ScalarHeader(baseName, ImmutableSet.copyOf(scalarFunction.alias()), description, scalarFunction.hidden(), scalarFunction.deterministic(), scalarFunction.neverFails(), receiverType));
+            builder.add(new ScalarHeader(baseName, ImmutableSet.copyOf(scalarFunction.alias()), description, scalarFunction.hidden(), scalarFunction.deterministic(), scalarFunction.neverFails(), receiverType, instanceMethod != null));
         }
         else if (staticMethod != null) {
             throw new IllegalArgumentException("@StaticMethod requires @ScalarFunction on " + annotated);
         }
+        else if (instanceMethod != null) {
+            throw new IllegalArgumentException("@InstanceMethod requires @ScalarFunction on " + annotated);
+        }
 
         if (scalarOperator != null) {
             builder.add(new ScalarHeader(scalarOperator.value(), description));
@@ -165,4 +175,9 @@ public Optional<TypeSignature> getReceiverType()
     {
         return receiverType;
     }
+
+    public boolean isInstanceMethod()
+    {
+        return instanceMethod;
+    }
 }

core/trino-main/src/main/java/io/trino/sql/analyzer/Analysis.java

@@ -225,6 +225,7 @@ public class Analysis
     private final Map<NodeRef<Expression>, ResolvedFunction> frameBoundCalculations = new LinkedHashMap<>();
     private final Map<NodeRef<Relation>, List<Type>> relationCoercions = new LinkedHashMap<>();
     private final Map<NodeRef<Node>, RoutineEntry> resolvedFunctions = new LinkedHashMap<>();
+    private final Map<NodeRef<FunctionCall>, Identifier> methodCallReceivers = new LinkedHashMap<>();
     private final Map<NodeRef<Identifier>, LambdaArgumentDeclaration> lambdaArgumentReferences = new LinkedHashMap<>();
 
     private final Map<Field, ColumnHandle> columns = new LinkedHashMap<>();
@@ -720,6 +721,16 @@ public void addResolvedFunction(Node node, ResolvedFunction function, String aut
         resolvedFunctions.put(NodeRef.of(node), new RoutineEntry(function, authorization));
     }
 
+    public void addMethodCallReceiver(FunctionCall node, Identifier receiver)
+    {
+        methodCallReceivers.put(NodeRef.of(node), receiver);
+    }
+
+    public Optional<Identifier> getMethodCallReceiver(FunctionCall node)
+    {
+        return Optional.ofNullable(methodCallReceivers.get(NodeRef.of(node)));
+    }
+
     public Set<NodeRef<Expression>> getColumnReferences()
     {
         return unmodifiableSet(columnReferences.keySet());

core/trino-main/src/main/java/io/trino/sql/analyzer/ExpressionAnalyzer.java

@@ -129,6 +129,7 @@
 import io.trino.sql.tree.LogicalExpression;
 import io.trino.sql.tree.LongLiteral;
 import io.trino.sql.tree.MeasureDefinition;
+import io.trino.sql.tree.MethodCall;
 import io.trino.sql.tree.Node;
 import io.trino.sql.tree.NodeRef;
 import io.trino.sql.tree.NotExpression;
@@ -329,6 +330,7 @@ public class ExpressionAnalyzer
     private final Cache<String, Type> varcharCastableTypeCache = buildNonEvictableCache(CacheBuilder.newBuilder().maximumSize(1000));
 
     private final Map<NodeRef<Node>, ResolvedFunction> resolvedFunctions = new LinkedHashMap<>();
+    private final Map<NodeRef<FunctionCall>, Identifier> methodCallReceivers = new LinkedHashMap<>();
     private final Set<NodeRef<SubqueryExpression>> subqueries = new LinkedHashSet<>();
     private final Set<NodeRef<ExistsPredicate>> existsSubqueries = new LinkedHashSet<>();
     private final Map<NodeRef<Expression>, Type> expressionCoercions = new LinkedHashMap<>();
@@ -437,6 +439,11 @@ public Map<NodeRef<Node>, ResolvedFunction> getResolvedFunctions()
         return unmodifiableMap(resolvedFunctions);
     }
 
+    public Map<NodeRef<FunctionCall>, Identifier> getMethodCallReceivers()
+    {
+        return unmodifiableMap(methodCallReceivers);
+    }
+
     public Map<NodeRef<Expression>, Type> getExpressionTypes()
     {
         return unmodifiableMap(expressionTypes);
@@ -1309,6 +1316,14 @@ protected Type visitNullLiteral(NullLiteral node, Context context)
         @Override
         protected Type visitFunctionCall(FunctionCall node, Context context)
         {
+            // SQL:2023 6.3 Syntax Rule 2: a non-parenthesized value expression primary
+            // of the form A.B(args) is treated as a method invocation if it satisfies
+            // the rules for one; otherwise it is a routine invocation.
+            Optional<Type> asMethod = tryResolveAsInstanceMethod(node, context);
+            if (asMethod.isPresent()) {
+                return asMethod.get();
+            }
+
             boolean isAggregation = functionResolver.isAggregationFunction(session, node.getName(), accessControl);
             boolean isRowPatternCount = context.isPatternRecognition() &&
                     isAggregation &&
@@ -1460,6 +1475,123 @@ else if (isAggregation) {
             return setExpressionType(node, type);
         }
 
+        private Optional<Type> tryResolveAsInstanceMethod(FunctionCall node, Context context)
+        {
+            QualifiedName name = node.getName();
+            if (name.getParts().size() != 2) {
+                return Optional.empty();
+            }
+            if (node.isDistinct()
+                    || node.getFilter().isPresent()
+                    || node.getOrderBy().isPresent()
+                    || node.getWindow().isPresent()
+                    || node.getProcessingMode().isPresent()
+                    || node.getNullTreatment().isPresent()) {
+                return Optional.empty();
+            }
+            if (context.isPatternRecognition() || context.isInWindow()) {
+                return Optional.empty();
+            }
+
+            Identifier receiver = name.getOriginalParts().get(0);
+            Identifier method = name.getOriginalParts().get(1);
+
+            // Method-call interpretation only applies when the receiver resolves
+            // as a field in the current scope. tryResolveField has no side effects
+            // so a non-match leaves the analyzer state untouched.
+            Optional<ResolvedField> resolvedReceiver = context.getScope()
+                    .tryResolveField(receiver, QualifiedName.of(receiver.getValue()));
+            if (resolvedReceiver.isEmpty()) {
+                return Optional.empty();
+            }
+            Type receiverType = resolvedReceiver.get().getField().getType();
+
+            MethodResolution resolution;
+            try {
+                resolution = resolveInstanceMethodCall(receiverType, method.getValue(), node.getArguments(), context);
+            }
+            catch (TrinoException e) {
+                return Optional.empty();
+            }
+
+            // Commit to method-call interpretation: record the receiver field reference.
+            process(receiver, context);
+
+            Type result = analyzeInstanceMethodInvocation(node, receiver, receiverType, method.getValue(), node.getArguments(), resolution, context);
+            methodCallReceivers.put(NodeRef.of(node), receiver);
+            return Optional.of(result);
+        }
+
+        @Override
+        protected Type visitMethodCall(MethodCall node, Context context)
+        {
+            Type receiverType = process(node.getReceiver(), context);
+            String methodName = node.getMethod().getValue();
+
+            MethodResolution resolution;
+            try {
+                resolution = resolveInstanceMethodCall(receiverType, methodName, node.getArguments(), context);
+            }
+            catch (TrinoException e) {
+                if (e.getLocation().isPresent()) {
+                    throw e;
+                }
+                throw new TrinoException(e::getErrorCode, extractLocation(node), e.getMessage(), e);
+            }
+
+            return analyzeInstanceMethodInvocation(node, node.getReceiver(), receiverType, methodName, node.getArguments(), resolution, context);
+        }
+
+        private MethodResolution resolveInstanceMethodCall(Type receiverType, String methodName, List<Expression> arguments, Context context)
+        {
+            List<TypeSignatureProvider> argumentTypes = ImmutableList.<TypeSignatureProvider>builder()
+                    .add(new TypeSignatureProvider(receiverType.getTypeSignature()))
+                    .addAll(getCallArgumentTypes(arguments, context))
+                    .build();
+            ResolvedFunction function = functionResolver.resolveInstanceMethod(
+                    session,
+                    receiverType.getTypeSignature(),
+                    QualifiedName.of(methodName),
+                    argumentTypes,
+                    accessControl);
+            return new MethodResolution(function, argumentTypes);
+        }
+
+        private Type analyzeInstanceMethodInvocation(
+                Expression node,
+                Expression receiver,
+                Type receiverType,
+                String methodName,
+                List<Expression> arguments,
+                MethodResolution resolution,
+                Context context)
+        {
+            if (arguments.size() + 1 > 127) {
+                throw semanticException(TOO_MANY_ARGUMENTS, node, "Too many arguments for method call .%s()", methodName);
+            }
+
+            BoundSignature signature = resolution.function().signature();
+            Type expectedReceiverType = signature.getArgumentTypes().getFirst();
+            coerceType(receiver, receiverType, expectedReceiverType, format("Method .%s receiver", methodName));
+            // Slot 0 of the signature is the receiver (self), so user-visible argument i maps to signature slot i + 1.
+            for (int i = 0; i < arguments.size(); i++) {
+                Expression expression = arguments.get(i);
+                Type expectedType = signature.getArgumentTypes().get(i + 1);
+                if (resolution.argumentTypes().get(i + 1).hasDependency()) {
+                    FunctionType expectedFunctionType = (FunctionType) expectedType;
+                    process(expression, context.expectingLambda(expectedFunctionType.getArgumentTypes()));
+                }
+                else {
+                    Type actualType = plannerContext.getTypeManager().getType(resolution.argumentTypes().get(i + 1).getTypeSignature());
+                    coerceType(expression, actualType, expectedType, format("Method .%s argument %d", methodName, i));
+                }
+            }
+            resolvedFunctions.put(NodeRef.of(node), resolution.function());
+            return setExpressionType(node, signature.getReturnType());
+        }
+
+        private record MethodResolution(ResolvedFunction function, List<TypeSignatureProvider> argumentTypes) {}
+
         @Override
         protected Type visitStaticMethodCall(StaticMethodCall node, Context context)
         {
@@ -3948,6 +4080,7 @@ private static void updateAnalysis(Analysis analysis, ExpressionAnalyzer analyze
                 analyzer.getSortKeyCoercionsForFrameBoundComparison());
         analysis.addFrameBoundCalculations(analyzer.getFrameBoundCalculations());
         analyzer.getResolvedFunctions().forEach((key, value) -> analysis.addResolvedFunction(key.getNode(), value, session.getUser()));
+        analyzer.getMethodCallReceivers().forEach((key, value) -> analysis.addMethodCallReceiver(key.getNode(), value));
         analysis.addColumnReferences(analyzer.getColumnReferences());
         analysis.addLambdaArgumentReferences(analyzer.getLambdaArgumentReferences());
         analysis.addTableColumnReferences(accessControl, session.getIdentity(), analyzer.getTableColumnReferences());