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, arrow::compute::VarianceOptions

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.

If the options pointer is null, then default_options() will be used.

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.

If the options pointer is null, then default_options() will be used.

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¶: 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¶: Skip null values.

enumerator EMIT_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::VarianceOptions : public arrow::compute::FunctionOptions ¶

#include <arrow/compute/api_aggregate.h>

Control Delta Degrees of Freedom (ddof) of Variance and Stddev kernel.

The divisor used in calculations is N - ddof, where N is the number of elements. By default, ddof is zero, and population variance or stddev is returned.

Public Functions

VarianceOptions(int ddof = 0)¶

Public Members

int ddof = 0¶

Public Static Functions

VarianceOptions 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()¶