catalyst/expressions/ExpressionDescription.java

0001 /*
0002  * Licensed to the Apache Software Foundation (ASF) under one or more
0003  * contributor license agreements.  See the NOTICE file distributed with
0004  * this work for additional information regarding copyright ownership.
0005  * The ASF licenses this file to You under the Apache License, Version 2.0
0006  * (the "License"); you may not use this file except in compliance with
0007  * the License.  You may obtain a copy of the License at
0008  *
0009  *    http://www.apache.org/licenses/LICENSE-2.0
0010  *
0011  * Unless required by applicable law or agreed to in writing, software
0012  * distributed under the License is distributed on an "AS IS" BASIS,
0013  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
0014  * See the License for the specific language governing permissions and
0015  * limitations under the License.
0016  */
0017
0018 package org.apache.spark.sql.catalyst.expressions;
0019
0020 import org.apache.spark.annotation.DeveloperApi;
0021
0022 import java.lang.annotation.Retention;
0023 import java.lang.annotation.RetentionPolicy;
0024
0025 /**
0026  * ::DeveloperApi::
0027  *
0028  * A function description type which can be recognized by FunctionRegistry, and will be used to
0029  * show the usage of the function in human language.
0030  *
0031  * `usage()` will be used for the function usage in brief way.
0032  *
0033  * These below are concatenated and used for the function usage in verbose way, suppose arguments,
0034  * examples, note, group, since and deprecated will be provided.
0035  *
0036  * `arguments()` describes arguments for the expression.
0037  *
0038  * `examples()` describes examples for the expression.
0039  *
0040  * `note()` contains some notes for the expression optionally.
0041  *
0042  * `group()` describes the category that the expression belongs to. The valid value is
0043  * "agg_funcs", "array_funcs", "datetime_funcs", "json_funcs", "map_funcs" and "window_funcs".
0044  *
0045  * `since()` contains version information for the expression. Version is specified by,
0046  * for example, "2.2.0".
0047  *
0048  * `deprecated()` contains deprecation information for the expression optionally, for example,
0049  * "Deprecated since 2.2.0. Use something else instead".
0050  *
0051  * The format, in particular for `arguments()`, `examples()`,`note()`, `group()`, `since()` and
0052  * `deprecated()`, should strictly be as follows.
0053  *
0054  * <pre>
0055  * <code>@ExpressionDescription(
0056  *   ...
0057  *   arguments = """
0058  *     Arguments:
0059  *       * arg0 - ...
0060  *           ....
0061  *       * arg1 - ...
0062  *           ....
0063  *   """,
0064  *   examples = """
0065  *     Examples:
0066  *       > SELECT ...;
0067  *        ...
0068  *       > SELECT ...;
0069  *        ...
0070  *   """,
0071  *   note = """
0072  *     ...
0073  *   """,
0074  *   group = "agg_funcs",
0075  *   since = "3.0.0",
0076  *   deprecated = """
0077  *     ...
0078  *   """)
0079  * </code>
0080  * </pre>
0081  *
0082  *  We can refer the function name by `_FUNC_`, in `usage()`, `arguments()`, `examples()` and
0083  *  `note()` as it is registered in `FunctionRegistry`.
0084  *
0085  *  Note that, if `extended()` is defined, `arguments()`, `examples()`, `note()`, `group()`,
0086  *  `since()` and `deprecated()` should be not defined together. `extended()` exists
0087  *  for backward compatibility.
0088  *
0089  *  Note this contents are used in the SparkSQL documentation for built-in functions. The contents
0090  *  here are considered as a Markdown text and then rendered.
0091  */
0092 @DeveloperApi
0093 @Retention(RetentionPolicy.RUNTIME)
0094 public @interface ExpressionDescription {
0095     String usage() default "";
0096     /**
0097      * @deprecated This field is deprecated as of Spark 3.0. Use {@link #arguments},
0098      *   {@link #examples}, {@link #note}, {@link #since} and {@link #deprecated} instead
0099      *   to document the extended usage.
0100      */
0101     @Deprecated
0102     String extended() default "";
0103     String arguments() default "";
0104     String examples() default "";
0105     String note() default "";
0106     /**
0107      * Valid group names are almost the same with one defined as `groupname` in
0108      * `sql/functions.scala`. But, `collection_funcs` is split into fine-grained three groups:
0109      * `array_funcs`, `map_funcs`, and `json_funcs`. See `ExpressionInfo` for the
0110      * detailed group names.
0111      */
0112     String group() default "";
0113     String since() default "";
0114     String deprecated() default "";
0115 }