org.apache.hadoop.hive.ql.udf.generic
Class GenericUDF

java.lang.Object
  org.apache.hadoop.hive.ql.udf.generic.GenericUDF

All Implemented Interfaces:

Closeable

Direct Known Subclasses:

AbstractGenericUDFEWAHBitmapBop, AbstractGenericUDFReflect, GenericUDFAbs, GenericUDFArray, GenericUDFArrayContains, GenericUDFAssertTrue, GenericUDFBaseCompare, GenericUDFBaseNumeric, GenericUDFBasePad, GenericUDFBaseTrim, GenericUDFBaseUnary, GenericUDFBetween, GenericUDFBridge, GenericUDFCase, GenericUDFCoalesce, GenericUDFConcat, GenericUDFConcatWS, GenericUDFDate, GenericUDFDateAdd, GenericUDFDateDiff, GenericUDFDateSub, GenericUDFDecode, GenericUDFElt, GenericUDFEncode, GenericUDFEWAHBitmapEmpty, GenericUDFField, GenericUDFFloorCeilBase, GenericUDFFormatNumber, GenericUDFFromUtcTimestamp, GenericUDFHash, GenericUDFIf, GenericUDFIn, GenericUDFIndex, GenericUDFInFile, GenericUDFInstr, GenericUDFLeadLag, GenericUDFLocate, GenericUDFLower, GenericUDFMacro, GenericUDFMap, GenericUDFMapKeys, GenericUDFMapValues, GenericUDFNamedStruct, GenericUDFNvl, GenericUDFOPAnd, GenericUDFOPNot, GenericUDFOPNotNull, GenericUDFOPNull, GenericUDFOPOr, GenericUDFPower, GenericUDFPrintf, GenericUDFRound, GenericUDFSentences, GenericUDFSize, GenericUDFSortArray, GenericUDFSplit, GenericUDFStringToMap, GenericUDFStruct, GenericUDFTimestamp, GenericUDFToBinary, GenericUDFToChar, GenericUDFToDate, GenericUDFToDecimal, GenericUDFToUnixTimeStamp, GenericUDFToVarchar, GenericUDFTranslate, GenericUDFUnion, GenericUDFUpper, GenericUDFWhen, GenericUDFXPath, UDFCurrentDB

public abstract class GenericUDF
extends Object
implements Closeable

A Generic User-defined function (GenericUDF) for the use with Hive. New GenericUDF classes need to inherit from this GenericUDF class. The GenericUDF are superior to normal UDFs in the following ways: 1. It can accept arguments of complex types, and return complex types. 2. It can accept variable length of arguments. 3. It can accept an infinite number of function signature - for example, it's easy to write a GenericUDF that accepts array, array> and so on (arbitrary levels of nesting). 4. It can do short-circuit evaluations using DeferedObject.

Nested Class Summary

static class	GenericUDF.DeferredJavaObject A basic dummy implementation of DeferredObject which just stores a Java Object reference.
static interface	GenericUDF.DeferredObject A Defered Object allows us to do lazy-evaluation and short-circuiting.

Constructor Summary

GenericUDF()
The constructor.

Method Summary

void	close() Close GenericUDF.
void	configure(MapredContext context) Additionally setup GenericUDF with MapredContext before initializing.
void	copyToNewInstance(Object newInstance) Some information may be set during initialize() which needs to be saved when the UDF is copied.
abstract Object	evaluate(GenericUDF.DeferredObject[] arguments) Evaluate the GenericUDF with the arguments.
GenericUDF	flip() Some functions are affected by appearing order of arguments (comparisons, for example)
abstract String	getDisplayString(String[] children) Get the String to be displayed in explain.
String[]	getRequiredFiles()
String[]	getRequiredJars() The following two functions can be overridden to automatically include additional resources required by this UDF.
String	getUdfName()
abstract ObjectInspector	initialize(ObjectInspector[] arguments) Initialize this GenericUDF.
ObjectInspector	initializeAndFoldConstants(ObjectInspector[] arguments) Initialize this GenericUDF.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

GenericUDF

public GenericUDF()

The constructor.

Method Detail

initialize

public abstract ObjectInspector initialize(ObjectInspector[] arguments)
                                    throws UDFArgumentException

Initialize this GenericUDF. This will be called once and only once per GenericUDF instance.

Parameters:

arguments - The ObjectInspector for the arguments

Returns:

The ObjectInspector for the return value

Throws:

UDFArgumentException - Thrown when arguments have wrong types, wrong length, etc.

configure

public void configure(MapredContext context)

Additionally setup GenericUDF with MapredContext before initializing. This is only called in runtime of MapRedTask.

Parameters:

context - context

initializeAndFoldConstants

public ObjectInspector initializeAndFoldConstants(ObjectInspector[] arguments)
                                           throws UDFArgumentException

Initialize this GenericUDF. Additionally, if the arguments are constant and the function is eligible to be folded, then the constant value returned by this UDF will be computed and stored in the ConstantObjectInspector returned. Otherwise, the function behaves exactly like initialize().

Throws:

UDFArgumentException

getRequiredJars

public String[] getRequiredJars()

The following two functions can be overridden to automatically include additional resources required by this UDF. The return types should be arrays of paths.

getRequiredFiles

public String[] getRequiredFiles()

evaluate

public abstract Object evaluate(GenericUDF.DeferredObject[] arguments)
                         throws HiveException

Evaluate the GenericUDF with the arguments.

Parameters:

arguments - The arguments as DeferedObject, use DeferedObject.get() to get the actual argument Object. The Objects can be inspected by the ObjectInspectors passed in the initialize call.

Returns:

The

Throws:

HiveException

getDisplayString

public abstract String getDisplayString(String[] children)

Get the String to be displayed in explain.

close

public void close()
           throws IOException

Close GenericUDF. This is only called in runtime of MapRedTask.

Specified by:

close in interface Closeable

Throws:

IOException

flip

public GenericUDF flip()

Some functions are affected by appearing order of arguments (comparisons, for example)

getUdfName

public String getUdfName()

copyToNewInstance

public void copyToNewInstance(Object newInstance)
                       throws UDFArgumentException

Some information may be set during initialize() which needs to be saved when the UDF is copied. This will be called by FunctionRegistry.cloneGenericUDF()

Throws:

UDFArgumentException