jerryshao commented on code in PR #9551: URL: https://github.com/apache/gravitino/pull/9551#discussion_r2659490291
########## api/src/main/java/org/apache/gravitino/function/Function.java: ########## @@ -0,0 +1,89 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.gravitino.function; + +import javax.annotation.Nullable; +import org.apache.gravitino.Auditable; +import org.apache.gravitino.annotation.Evolving; +import org.apache.gravitino.rel.types.Type; + +/** Represents a user-defined function registered in Gravitino. */ +@Evolving +public interface Function extends Auditable { + /** An empty array of {@link FunctionColumn}. */ + FunctionColumn[] EMPTY = new FunctionColumn[0]; + + /** + * @return The function name. + */ + String name(); + + /** + * @return The function type. + */ + FunctionType functionType(); + + /** + * @return Whether the function is deterministic. + */ + boolean deterministic(); + + /** + * @return The optional comment of the function. + */ + @Nullable + default String comment() { + return null; + } + + /** + * The return type for scalar or aggregate functions. + * + * @return The return type, null if this is a table-valued function. + */ + @Nullable + default Type returnType() { + return null; + } + + /** + * The output columns for a table-valued function. + * + * @return The output columns of a table-valued function, or an empty array for scalar or + * aggregate functions. + */ + default FunctionColumn[] returnColumns() { + return EMPTY; + } + + /** + * @return The definitions of the function. + */ + FunctionDefinition[] definitions(); + + /** + * Returns the internal revision version of the function. + * + * <p>This version is a 0-based counter, where {@code 0} represents the initial definition of the + * function, and the value is incremented by 1 on each later alteration. + * + * @return The 0-based revision version of the function. + */ + int version(); Review Comment: Do we support storing and getting the specific version of function? ########## api/src/main/java/org/apache/gravitino/function/FunctionCatalog.java: ########## @@ -0,0 +1,157 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.gravitino.function; + +import org.apache.gravitino.NameIdentifier; +import org.apache.gravitino.Namespace; +import org.apache.gravitino.annotation.Evolving; +import org.apache.gravitino.exceptions.FunctionAlreadyExistsException; +import org.apache.gravitino.exceptions.NoSuchFunctionException; +import org.apache.gravitino.exceptions.NoSuchFunctionVersionException; +import org.apache.gravitino.exceptions.NoSuchSchemaException; +import org.apache.gravitino.rel.types.Type; + +/** The FunctionCatalog interface defines the public API for managing functions in a schema. */ +@Evolving +public interface FunctionCatalog { + + /** + * List the functions in a namespace from the catalog. + * + * @param namespace A namespace. + * @return An array of function identifiers in the namespace. + * @throws NoSuchSchemaException If the schema does not exist. + */ + NameIdentifier[] listFunctions(Namespace namespace) throws NoSuchSchemaException; + + /** + * List the functions with details in a namespace from the catalog. + * + * @param namespace A namespace. + * @return An array of functions in the namespace. + * @throws NoSuchSchemaException If the schema does not exist. + */ + Function[] listFunctionInfos(Namespace namespace) throws NoSuchSchemaException; + + /** + * Get a function by {@link NameIdentifier} from the catalog. The identifier only contains the + * schema and function name. A function may include multiple definitions (overloads) in the + * result. This method returns the latest version of the function. + * + * @param ident A function identifier. + * @return The latest version of the function with the given name. + * @throws NoSuchFunctionException If the function does not exist. + */ + Function getFunction(NameIdentifier ident) throws NoSuchFunctionException; + + /** + * Get a function by {@link NameIdentifier} and version from the catalog. The identifier only + * contains the schema and function name. A function may include multiple definitions (overloads) + * in the result. + * + * @param ident A function identifier. + * @param version The zero-based function version index (0 for the first created version), as + * returned by {@link Function#version()}. + * @return The function with the given name and version. + * @throws NoSuchFunctionException If the function does not exist. + * @throws NoSuchFunctionVersionException If the function version does not exist. + */ + Function getFunction(NameIdentifier ident, int version) + throws NoSuchFunctionException, NoSuchFunctionVersionException; + + /** + * Check if a function with the given name exists in the catalog. + * + * @param ident The function identifier. + * @return True if the function exists, false otherwise. + */ + default boolean functionExists(NameIdentifier ident) { + try { + getFunction(ident); + return true; + } catch (NoSuchFunctionException e) { + return false; + } + } + + /** + * Register a scalar or aggregate function with one or more definitions (overloads). + * + * @param ident The function identifier. + * @param comment The optional function comment. + * @param functionType The function type. + * @param deterministic Whether the function is deterministic. + * @param returnType The return type. + * @param definitions The function definitions. + * @return The registered function. + * @throws NoSuchSchemaException If the schema does not exist. + * @throws FunctionAlreadyExistsException If the function already exists. + */ + Function registerFunction( + NameIdentifier ident, + String comment, + FunctionType functionType, + boolean deterministic, + Type returnType, + FunctionDefinition[] definitions) + throws NoSuchSchemaException, FunctionAlreadyExistsException; + + /** + * Register a table-valued function with one or more definitions (overloads). + * + * @param ident The function identifier. + * @param comment The optional function comment. + * @param deterministic Whether the function is deterministic. + * @param returnColumns The return columns. + * @param definitions The function definitions. + * @return The registered function. + * @throws NoSuchSchemaException If the schema does not exist. + * @throws FunctionAlreadyExistsException If the function already exists. + */ + Function registerFunction( + NameIdentifier ident, + String comment, + boolean deterministic, + FunctionColumn[] returnColumns, + FunctionDefinition[] definitions) + throws NoSuchSchemaException, FunctionAlreadyExistsException; Review Comment: We have two definitions of `registerFunction`, can we use the above one as a specific implementation of this one? ########## api/src/main/java/org/apache/gravitino/function/FunctionChange.java: ########## @@ -0,0 +1,393 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.gravitino.function; + +import com.google.common.base.Preconditions; +import java.util.Arrays; +import java.util.Objects; +import org.apache.gravitino.annotation.Evolving; + +/** Represents a change that can be applied to a function. */ +@Evolving +public interface FunctionChange { + + /** + * Create a {@link FunctionChange} to update the comment of a function. + * + * @param newComment The new comment value. + * @return The change instance. + */ + static FunctionChange updateComment(String newComment) { + return new UpdateComment(newComment); + } + + /** + * Create a {@link FunctionChange} to add a new definition (overload) to a function. + * + * @param definition The new definition to add. + * @return The change instance. + */ + static FunctionChange addDefinition(FunctionDefinition definition) { + return new AddDefinition(definition); + } + + /** + * Create a {@link FunctionChange} to remove an existing definition (overload) from a function. + * + * @param parameters The parameters that identify the definition to remove. + * @return The change instance. + */ + static FunctionChange removeDefinition(FunctionParam[] parameters) { Review Comment: Will the ordering of the parameters be considered as another overload? ########## api/src/main/java/org/apache/gravitino/function/FunctionDefinition.java: ########## @@ -0,0 +1,40 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.gravitino.function; + +import org.apache.gravitino.annotation.Evolving; + +/** + * A function definition that pairs a specific parameter list with its implementations. A single + * function can include multiple definitions (overloads), each with distinct parameters and + * implementations. + */ +@Evolving +public interface FunctionDefinition { + + /** + * @return The parameters for this definition. Maybe an empty array for a no-arg definition. + */ + FunctionParam[] parameters(); + + /** + * @return The implementations associated with this definition. + */ + FunctionImpl[] impls(); Review Comment: Why are there multiple implementations for one definition? ########## api/src/main/java/org/apache/gravitino/function/FunctionChange.java: ########## @@ -0,0 +1,393 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.gravitino.function; + +import com.google.common.base.Preconditions; +import java.util.Arrays; +import java.util.Objects; +import org.apache.gravitino.annotation.Evolving; + +/** Represents a change that can be applied to a function. */ +@Evolving +public interface FunctionChange { + + /** + * Create a {@link FunctionChange} to update the comment of a function. + * + * @param newComment The new comment value. + * @return The change instance. + */ + static FunctionChange updateComment(String newComment) { + return new UpdateComment(newComment); + } + + /** + * Create a {@link FunctionChange} to add a new definition (overload) to a function. + * + * @param definition The new definition to add. + * @return The change instance. + */ + static FunctionChange addDefinition(FunctionDefinition definition) { Review Comment: What's the relationship between `definition` and `implementation`? ########## api/src/main/java/org/apache/gravitino/function/FunctionChange.java: ########## @@ -0,0 +1,393 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.gravitino.function; + +import com.google.common.base.Preconditions; +import java.util.Arrays; +import java.util.Objects; +import org.apache.gravitino.annotation.Evolving; + +/** Represents a change that can be applied to a function. */ +@Evolving +public interface FunctionChange { Review Comment: Can we rename the function? -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
