Compute Functions

Datum class

class arrow::Datum

Variant type for various Arrow C++ data structures.

Public Functions

Datum()

Empty datum, to be populated elsewhere.

bool is_value() const

True if Datum contains a scalar or array-like data.

ValueDescr descr() const

Return the shape (array or scalar) and type for supported kinds (ARRAY, CHUNKED_ARRAY, and SCALAR).

Debug asserts otherwise

ValueDescr::Shape shape() const

Return the shape (array or scalar) for supported kinds (ARRAY, CHUNKED_ARRAY, and SCALAR).

Debug asserts otherwise

std::shared_ptr<DataType> type() const

The value type of the variant, if any.

Return

nullptr if no type

int64_t length() const

The value length of the variant, if any.

Return

kUnknownLength if no type

ArrayVector chunks() const

The array chunks of the variant, if any.

Return

empty if not arraylike

Abstract Function classes

struct FunctionOptions

#include <arrow/compute/function.h>

Base class for specifying options configuring a function’s behavior, such as error handling.

Subclassed by arrow::compute::ArithmeticOptions, arrow::compute::CastOptions, arrow::compute::CompareOptions, arrow::compute::CountOptions, arrow::compute::FilterOptions, arrow::compute::MatchSubstringOptions, arrow::compute::MinMaxOptions, arrow::compute::PartitionNthOptions, arrow::compute::SetLookupOptions, arrow::compute::StrptimeOptions, arrow::compute::TakeOptions

struct arrow::compute::Arity

#include <arrow/compute/function.h>

Contains the number of required arguments for the function.

Naming conventions taken from https://en.wikipedia.org/wiki/Arity.

Public Members

int num_args

The number of required arguments (or the minimum number for varargs functions).

bool is_varargs = false

If true, then the num_args is the minimum number of required arguments.

Public Static Functions

Arity Nullary()

A function taking no arguments.

Arity Unary()

A function taking 1 argument.

Arity Binary()

A function taking 2 arguments.

Arity Ternary()

A function taking 3 arguments.

Arity VarArgs(int min_args = 0)

A function taking a variable number of arguments.

Parameters

• [in] min_args: the minimum number of arguments required when invoking the function

class arrow::compute::Function

#include <arrow/compute/function.h>

Base class for compute functions.

Function implementations contain a collection of “kernels” which are implementations of the function for specific argument types. Selecting a viable kernel for executing a function is referred to as “dispatching”.

Subclassed by arrow::compute::detail::FunctionImpl< KernelType >, arrow::compute::MetaFunction, arrow::compute::detail::FunctionImpl< ScalarAggregateKernel >, arrow::compute::detail::FunctionImpl< ScalarKernel >, arrow::compute::detail::FunctionImpl< VectorKernel >

Public Types

enum Kind

The kind of function, which indicates in what contexts it is valid for use.

Values:

enumerator SCALAR

A function that performs scalar data operations on whole arrays of data.

Can generally process Array or Scalar values. The size of the output will be the same as the size (or broadcasted size, in the case of mixing Array and Scalar inputs) of the input.

enumerator VECTOR

A function with array input and output whose behavior depends on the values of the entire arrays passed, rather than the value of each scalar value.

enumerator SCALAR_AGGREGATE

A function that computes scalar summary statistics from array input.

enumerator META

A function that dispatches to other functions and does not contain its own kernels.

Public Functions

const std::string &name() const

The name of the kernel. The registry enforces uniqueness of names.

Function::Kind kind() const

The kind of kernel, which indicates in what contexts it is valid for use.

const Arity &arity() const

Contains the number of arguments the function requires, or if the function accepts variable numbers of arguments.

int num_kernels() const = 0

Returns the number of registered kernels for this function.

Result<Datum> Execute(const std::vector<Datum> &args, const FunctionOptions *options, ExecContext *ctx) const

Execute the function eagerly with the passed input arguments with kernel dispatch, batch iteration, and memory allocation details taken care of.

Function implementations may assume that options is non-null and valid or to forgo options and accept only nullptr for that argument.

This function can be overridden in subclasses.

const FunctionOptions *default_options() const

Returns a the default options for this function.

Whatever option semantics a Function has, implementations must guarantee that default_options() is valid to pass to Execute as options.

class arrow::compute::ScalarFunction : public arrow::compute::detail::FunctionImpl<ScalarKernel>

#include <arrow/compute/function.h>

A function that executes elementwise operations on arrays or scalars, and therefore whose results generally do not depend on the order of the values in the arguments.

Accepts and returns arrays that are all of the same size. These functions roughly correspond to the functions used in SQL expressions.

Subclassed by arrow::compute::CastFunction

Public Functions

Status AddKernel(std::vector<InputType> in_types, OutputType out_type, ArrayKernelExec exec, KernelInit init = NULLPTR)

Add a kernel with given input/output types, no required state initialization, preallocation for fixed-width types, and default null handling (intersect validity bitmaps of inputs).

Status AddKernel(ScalarKernel kernel)

Add a kernel (function implementation).

Returns error if the kernel’s signature does not match the function’s arity.

Result<const ScalarKernel*> DispatchExact(const std::vector<ValueDescr> &values) const

Return a kernel that can execute the function given the exact argument types (without implicit type casts or scalar->array promotions).

NB: This function is overridden in CastFunction.

class arrow::compute::VectorFunction : public arrow::compute::detail::FunctionImpl<VectorKernel>

#include <arrow/compute/function.h>

A function that executes general array operations that may yield outputs of different sizes or have results that depend on the whole array contents.

These functions roughly correspond to the functions found in non-SQL array languages like APL and its derivatives.

Public Functions

Status AddKernel(std::vector<InputType> in_types, OutputType out_type, ArrayKernelExec exec, KernelInit init = NULLPTR)

Add a simple kernel with given input/output types, no required state initialization, no data preallocation, and no preallocation of the validity bitmap.

Status AddKernel(VectorKernel kernel)

Add a kernel (function implementation).

Returns error if the kernel’s signature does not match the function’s arity.

Result<const VectorKernel*> DispatchExact(const std::vector<ValueDescr> &values) const

Return a kernel that can execute the function given the exact argument types (without implicit type casts or scalar->array promotions)

class arrow::compute::ScalarAggregateFunction : public arrow::compute::detail::FunctionImpl<ScalarAggregateKernel>

#include <arrow/compute/function.h>

Public Functions

Status AddKernel(ScalarAggregateKernel kernel)

Add a kernel (function implementation).

Returns error if the kernel’s signature does not match the function’s arity.

Result<const ScalarAggregateKernel*> DispatchExact(const std::vector<ValueDescr> &values) const

Return a kernel that can execute the function given the exact argument types (without implicit type casts or scalar->array promotions)

class arrow::compute::MetaFunction : public arrow::compute::Function

#include <arrow/compute/function.h>

A function that dispatches to other functions.

Must implement MetaFunction::ExecuteImpl.

For Array, ChunkedArray, and Scalar Datum kinds, may rely on the execution of concrete Function types, but must handle other Datum kinds on its own.

Public Functions

int num_kernels() const override

Returns the number of registered kernels for this function.

Result<Datum> Execute(const std::vector<Datum> &args, const FunctionOptions *options, ExecContext *ctx) const override

Execute the function eagerly with the passed input arguments with kernel dispatch, batch iteration, and memory allocation details taken care of.

Function implementations may assume that options is non-null and valid or to forgo options and accept only nullptr for that argument.

This function can be overridden in subclasses.

Function registry

class arrow::compute::FunctionRegistry

A mutable central function registry for built-in functions as well as user-defined functions.

Functions are implementations of arrow::compute::Function.

Generally, each function contains kernels which are implementations of a function for a specific argument signature. After looking up a function in the registry, one can either execute it eagerly with Function::Execute or use one of the function’s dispatch methods to pick a suitable kernel for lower-level function execution.

Public Functions

Status AddFunction(std::shared_ptr<Function> function, bool allow_overwrite = false)

Add a new function to the registry.

Returns Status::KeyError if a function with the same name is already registered

Status AddAlias(const std::string &target_name, const std::string &source_name)

Add aliases for the given function name.

Returns Status::KeyError if the function with the given name is not registered

Result<std::shared_ptr<Function>> GetFunction(const std::string &name) const

Retrieve a function by name from the registry.

std::vector<std::string> GetFunctionNames() const

Return vector of all entry names in the registry.

Helpful for displaying a manifest of available functions

int num_functions() const

The number of currently registered functions.

Public Static Functions

std::unique_ptr<FunctionRegistry> Make()

Construct a new registry.

Most users only need to use the global registry

FunctionRegistry *arrow::compute::GetFunctionRegistry()

Return the process-global function registry.

Convenience functions

Result<Datum> CallFunction(const std::string &func_name, const std::vector<Datum> &args, const FunctionOptions *options, ExecContext *ctx = NULLPTR)

One-shot invoker for all types of functions.

Does kernel dispatch, argument checking, iteration of ChunkedArray inputs, and wrapping of outputs.

Result<Datum> CallFunction(const std::string &func_name, const std::vector<Datum> &args, ExecContext *ctx = NULLPTR)

Variant of CallFunction which uses a function’s default options.

NB: Some functions require FunctionOptions be provided.

Concrete options classes

enum CompareOperator

Values:

enumerator EQUAL

enumerator NOT_EQUAL

enumerator GREATER

enumerator GREATER_EQUAL

enumerator LESS

enumerator LESS_EQUAL

struct arrow::compute::CountOptions : public arrow::compute::FunctionOptions

#include <arrow/compute/api_aggregate.h>

Control Count kernel behavior.

By default, all non-null values are counted.

Public Types

enum Mode

Values:

enumerator COUNT_NON_NULL = 0

Count all non-null values.

enumerator COUNT_NULL

Count all null values.

Public Functions

CountOptions(enum Mode count_mode)

Public Members

enum Mode count_mode = COUNT_NON_NULL

Public Static Functions

CountOptions Defaults()

struct arrow::compute::MinMaxOptions : public arrow::compute::FunctionOptions

#include <arrow/compute/api_aggregate.h>

Control MinMax kernel behavior.

By default, null values are ignored

Public Types

enum Mode

Values:

enumerator SKIP = 0

Skip null values.

enumerator OUTPUT_NULL

Any nulls will result in null output.

Public Functions

MinMaxOptions(enum Mode null_handling = SKIP)

Public Members

enum Mode null_handling = SKIP

Public Static Functions

MinMaxOptions Defaults()

struct arrow::compute::ArithmeticOptions : public arrow::compute::FunctionOptions

#include <arrow/compute/api_scalar.h>

Public Functions

ArithmeticOptions()

Public Members

bool check_overflow

struct arrow::compute::MatchSubstringOptions : public arrow::compute::FunctionOptions

#include <arrow/compute/api_scalar.h>

Public Functions

MatchSubstringOptions(std::string pattern)

Public Members

std::string pattern

The exact substring to look for inside input values.

struct arrow::compute::SetLookupOptions : public arrow::compute::FunctionOptions

#include <arrow/compute/api_scalar.h>

Options for IsIn and IndexIn functions.

Public Functions

SetLookupOptions(Datum value_set, bool skip_nulls)

Public Members

Datum value_set

The set of values to look up input values into.

bool skip_nulls

Whether nulls in value_set count for lookup.

If true, any null in value_set is ignored and nulls in the input produce null (IndexIn) or false (IsIn) values in the output. If false, any null in value_set is successfully matched in the input.

struct arrow::compute::StrptimeOptions : public arrow::compute::FunctionOptions

#include <arrow/compute/api_scalar.h>

Public Functions

StrptimeOptions(std::string format, TimeUnit::type unit)

Public Members

std::string format

TimeUnit::type unit

struct arrow::compute::CompareOptions : public arrow::compute::FunctionOptions

#include <arrow/compute/api_scalar.h>

Public Functions

CompareOptions(CompareOperator op)

Public Members

enum CompareOperator op

struct arrow::compute::FilterOptions : public arrow::compute::FunctionOptions

#include <arrow/compute/api_vector.h>

Public Types

enum NullSelectionBehavior

Configure the action taken when a slot of the selection mask is null.

Values:

enumerator DROP

the corresponding filtered value will be removed in the output

enumerator EMIT_NULL

the corresponding filtered value will be null in the output

Public Functions

FilterOptions(NullSelectionBehavior null_selection = DROP)

Public Members

NullSelectionBehavior null_selection_behavior = DROP

Public Static Functions

FilterOptions Defaults()

struct arrow::compute::TakeOptions : public arrow::compute::FunctionOptions

#include <arrow/compute/api_vector.h>

Public Functions

TakeOptions(bool boundscheck = true)

Public Members

bool boundscheck = true

Public Static Functions

TakeOptions BoundsCheck()

TakeOptions NoBoundsCheck()

TakeOptions Defaults()

struct arrow::compute::PartitionNthOptions : public arrow::compute::FunctionOptions

#include <arrow/compute/api_vector.h>

Partitioning options for NthToIndices.

Public Functions

PartitionNthOptions(int64_t pivot)

Public Members

int64_t pivot

The index into the equivalent sorted array of the partition pivot element.

struct arrow::compute::CastOptions : public arrow::compute::FunctionOptions

#include <arrow/compute/cast.h>

Public Functions

CastOptions()

CastOptions(bool safe)

Public Members

std::shared_ptr<DataType> to_type

bool allow_int_overflow

bool allow_time_truncate

bool allow_time_overflow

bool allow_decimal_truncate

bool allow_float_truncate

bool allow_invalid_utf8

Public Static Functions

CastOptions Safe()

CastOptions Unsafe()