This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

API reference

The Vertica SDK has application programming interfaces (APIs) in the following languages:

Vertica has the following client API:

1 - C++ SDK

2 - Java SDK

3 - R SDK

Welcome to the Vertica R SDK API Documentation.

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).

3.1 - Main function

The first function called when Vertica runs an R user-defined extension (UDx).

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.

Example

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)
}

Arguments

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.

Description

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.

3.2 - Factory function

The factory function consists of an R list which specifies the parameters of your R user-defined extension (UDx).

The factory function consists of an R list which specifies the parameters of your R user-defined extension (UDx).

Example

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") )
}

Arguments

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:

  • scalar

  • transform

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:

  • VOLATILE (default)

  • IMMUTABLE

  • STABLE

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:

  • CALLED_ON_NULL_INPUT (default)

  • RETURN_NULL_ON_NULL_INPUT

  • STRICT

For details, see Setting null input and volatility behavior for R functions.

Description

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.

3.3 - Outtypecallback function

Function to define the column names, output data types, length/precision, and scale of the data being returned to Vertica.

Function to define the column names, output data types, length/precision, and scale of the data being returned to Vertica.

Example


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

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.

Description

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.

3.4 - Parametertypecallback function

Function to define the output data type(s), length/precision, and scale of the parameters sent to the main function.

Function to define the output data type(s), length/precision, and scale of the parameters sent to the main function.

Example

FunctionNameParameterTypes <- function() {
  parameters <- list(datatype = c("int", "varchar"),
                     length   = c("NA", "100"),
                     scale    = c("NA", "NA"),
                     name     = c("k", "algorithm"))
  return(parameters)
}

Arguments

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.

Description

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.

4 - Python SDK

5 - JDBC API