This is the multi-page printable view of this section. Click here to print.
Welcome to the Vertica R SDK API Documentation. This documentation covers all of the functions that make up the R SDK. Using this API, you can create User Defined Extensions (UDxs) that integrate your own features into the Vertica Analytics Platform.
To learn how UDxs work and how to develop, compile, and deploy them, see Developing user-defined extensions (UDxs).
The first function called when Vertica runs an R user-defined extension (UDx). It must return a data frame and is defined by the name parameter of the factory function.
FunctionName <- function(input_data_frame, parameters_data_frame) {
# Each column from Vertica is turned into a column in the input data frame.
# This is a brief example of multiplying two columns of the input data frame.
output_data_frame <- data.frame(input_data_frame[, 1] * input_data_frame[, 2])
# The function must return a data frame.
return(output_data_frame)
}
input_data_frame |
The data read by the Vertica user-defined extension (UDx). This input must be a data frame. |
parameters_data_frame |
The parameters passed to the Vertica user-defined extension (UDx). This input must be a data frame. If you are passing parameters from your Vertica UDx, defined with USING PARAMETERS, then you must included this in your R UDx. If you are not passing parameters to your R UDx, then this can be omitted from your R UDx. |
The main function takes as input one data frame as the first argument, and if your UDx accepts parameters, a parameter data frame as the second argument. The main function must return a data frame. The factory function converts the intype argument into a data frame for the main function. For example, intype=c("float","float") is converted by the factory function into a two-dimensional matrix.
The function can call other functions defined in your R UDx library file.
The factory function consists of an R list which specifies the parameters of your R user-defined extension (UDx).
FunctionNameFactory <- function() {
list(name = MainFunctionName,
udxtype = c("scalar"),
intype = c("float","int", ...),
outtype = c("float", ...),
outtypecallback = MyReturnTypeFunc,
parametertypecallback = MyParamReturnFunc,
volatility = c("volatile"),
strictness = c("called_on_null_input") )
}
name |
The name of the R function in this UDx that is called when the function is invoked by Vertica, and which returns the value(s) back to Vertica. |
udxtype |
The type of UDx, one of the following:
|
intype |
Data types of arguments accepted by the function. UDxs support up to 9800 arguments. |
outtype |
Data types of the arguments returned by the function. |
outtypecallback |
(Optional) The callback function to call before sending the data back to Vertica, which defines the types and precision that the main function returns. |
parametertypecallback |
The callback function to send parameter types and names to Vertica. This parameter is required if your UDx is called from Vertica with USING PARAMETERS. |
volatility |
(Optional) Indicates whether the function returns the same output given the same input, one of the following:
For details, see Setting null input and volatility behavior for R functions. |
strictness |
(Optional) Indicates whether the function always returns NULL when any input argument is NULL, one of the following:
For details, see Setting null input and volatility behavior for R functions. |
User-defined functions in R (R UDx) require a factory function for each main R function that you want to call from within Vertica. The factory function encapsulates all the information required by Vertica to load the R UDx.
Function to define the column names, output data types, length/precision, and scale of the data being returned to Vertica.
SalesTaxReturnTypes <- function(arguments.data.frame, parameters.data.frame) {
output.return.type <- data.frame(datatype = rep(NA, 2),
length = rep(NA, 2),
scale = rep(NA, 2),
name = rep(NA, 2))
output.return.type$datatype <- c("float", "float")
output.return.type$name <- c("Sales Tax Rate", "Item Cost with Tax")
return(output.return.type)
}
arguments.data.frame |
Data frame that contains the arguments passed to the UDx from Vertica. This data frame is created and used internally by the UDx process. |
parameters.data.frame |
Data frame that contains the parameters defined in the UDx from Vertica. This data frame is created and used internally by the UDx process. |
datatype |
Output data type. |
length |
(Optional) Dimension of the output. |
scale |
(Optional) Proportional dimensions of the output. |
name |
Column name of the output. |
When creating the outtypecallback function, define one row for each value returned. Use the same order as in the outtype defined in the factory function. If any columns are left blank or the outtypecallback function is omitted, then Vertica uses default values.
When specifying LONG VARCHAR or LONG VARBINARY data types, include the space between the two words. For example:
datatype = c("long varchar")
Function to define the output data type(s), length/precision, and scale of the parameters sent to the main function.
FunctionNameParameterTypes <- function() {
parameters <- list(datatype = c("int", "varchar"),
length = c("NA", "100"),
scale = c("NA", "NA"),
name = c("k", "algorithm"))
return(parameters)
}
datatype |
The data type of the parameter. |
length |
(Optional) The dimension of the parameter. |
scale |
The proportional dimensions of the parameter. |
name |
The name of the parameter. |
When creating the parametertypecallback function, you define one row for each parameter being sent to the function. You must specify a parametertypecallback function if your UDx uses parameters.
The parametertypecallback does not accept any input arguments.