Expression Evaluation

group expressions

Enums

enum class ast_operator : int32_t

Enum of supported operators.

Values:

enumerator ADD

operator +

enumerator SUB

operator -

enumerator MUL

operator *

enumerator DIV

operator / using common type of lhs and rhs

enumerator TRUE_DIV

operator / after promoting type to floating point

enumerator FLOOR_DIV

operator / after promoting to 64 bit floating point and then flooring the result

enumerator MOD

operator %

enumerator PYMOD

operator % using Python’s sign rules for negatives

enumerator POW

lhs ^ rhs

enumerator EQUAL

operator ==

enumerator NULL_EQUAL

operator == with Spark rules: NULL_EQUAL(null, null) is true, NULL_EQUAL(null, valid) is false, and NULL_EQUAL(valid, valid) == EQUAL(valid, valid)

enumerator NOT_EQUAL

operator !=

enumerator LESS

operator <

enumerator GREATER

operator >

enumerator LESS_EQUAL

operator <=

enumerator GREATER_EQUAL

operator >=

enumerator BITWISE_AND

operator &

enumerator BITWISE_OR

operator |

enumerator BITWISE_XOR

operator ^

enumerator LOGICAL_AND

operator &&

enumerator NULL_LOGICAL_AND

operator && with Spark rules: NULL_LOGICAL_AND(null, null) is null, NULL_LOGICAL_AND(null, true) is null, NULL_LOGICAL_AND(null, false) is false, and NULL_LOGICAL_AND(valid, valid) == LOGICAL_AND(valid, valid)

enumerator LOGICAL_OR

operator ||

enumerator NULL_LOGICAL_OR

operator || with Spark rules: NULL_LOGICAL_OR(null, null) is null, NULL_LOGICAL_OR(null, true) is true, NULL_LOGICAL_OR(null, false) is null, and NULL_LOGICAL_OR(valid, valid) == LOGICAL_OR(valid, valid)

enumerator IDENTITY

Identity function.

enumerator IS_NULL

Check if operand is null.

enumerator SIN

Trigonometric sine.

enumerator COS

Trigonometric cosine.

enumerator TAN

Trigonometric tangent.

enumerator ARCSIN

Trigonometric sine inverse.

enumerator ARCCOS

Trigonometric cosine inverse.

enumerator ARCTAN

Trigonometric tangent inverse.

enumerator SINH

Hyperbolic sine.

enumerator COSH

Hyperbolic cosine.

enumerator TANH

Hyperbolic tangent.

enumerator ARCSINH

Hyperbolic sine inverse.

enumerator ARCCOSH

Hyperbolic cosine inverse.

enumerator ARCTANH

Hyperbolic tangent inverse.

enumerator EXP

Exponential (base e, Euler number)

enumerator LOG

Natural Logarithm (base e)

enumerator SQRT

Square-root (x^0.5)

enumerator CBRT

Cube-root (x^(1.0/3))

enumerator CEIL

Smallest integer value not less than arg.

enumerator FLOOR

largest integer value not greater than arg

enumerator ABS

Absolute value.

enumerator RINT

Rounds the floating-point argument arg to an integer value.

enumerator BIT_INVERT

Bitwise Not (~)

enumerator NOT

Logical Not (!)

enumerator CAST_TO_INT64

Cast value to int64_t.

enumerator CAST_TO_UINT64

Cast value to uint64_t.

enumerator CAST_TO_FLOAT64

Cast value to double.

enum class table_reference

Enum of table references.

This determines which table to use in cases with two tables (e.g. joins).

Values:

enumerator LEFT

Column index in the left table.

enumerator RIGHT

Column index in the right table.

enumerator OUTPUT

Column index in the output table.

struct expression

#include <expressions.hpp>

A generic expression that can be evaluated to return a value.

This class is a part of a “visitor” pattern with the expression_parser class. Expressions inheriting from this class can accept parsers as visitors.

Subclassed by cudf::ast::column_name_reference, cudf::ast::column_reference, cudf::ast::literal, cudf::ast::operation

Public Functions

virtual cudf::size_type accept(detail::expression_parser &visitor) const = 0

Accepts a visitor class.

Parameters:

visitor – The expression_parser parsing this expression tree

Returns:

Index of device data reference for this instance

virtual std::reference_wrapper<expression const> accept(detail::expression_transformer &visitor) const = 0

Accepts a visitor class.

Parameters:

visitor – The expression_transformer transforming this expression tree

Returns:

Reference wrapper of transformed expression

inline bool may_evaluate_null(table_view const &left, rmm::cuda_stream_view stream) const

Returns true if the expression may evaluate to null.

Parameters:

• left – The left operand of the expression (The same is used as right operand)

• stream – CUDA stream used for device memory operations and kernel launches

Returns:

true if the expression may evaluate to null, otherwise false

virtual bool may_evaluate_null(table_view const &left, table_view const &right, rmm::cuda_stream_view stream) const = 0

Returns true if the expression may evaluate to null.

Parameters:

• left – The left operand of the expression

• right – The right operand of the expression

• stream – CUDA stream used for device memory operations and kernel launches

Returns:

true if the expression may evaluate to null, otherwise false

class generic_scalar_device_view : public cudf::detail::scalar_device_view_base

#include <expressions.hpp>

A type-erased scalar_device_view where the value is a fixed width type or a string.

Public Functions

template<typename T>
inline T const value() const noexcept

Returns the stored value.

Template Parameters:

T – The desired type

Returns:

The stored value

template<typename T>
inline generic_scalar_device_view(numeric_scalar<T> &s)

Construct a new generic scalar device view object from a numeric scalar.

Parameters:

s – The numeric scalar to construct from

template<typename T>
inline generic_scalar_device_view(timestamp_scalar<T> &s)

Construct a new generic scalar device view object from a timestamp scalar.

Parameters:

s – The timestamp scalar to construct from

template<typename T>
inline generic_scalar_device_view(duration_scalar<T> &s)

Construct a new generic scalar device view object from a duration scalar.

Parameters:

s – The duration scalar to construct from

inline generic_scalar_device_view(string_scalar &s)

Construct a new generic scalar device view object from a string scalar.

Parameters:

s – The string scalar to construct from

class literal : public cudf::ast::expression

#include <expressions.hpp>

A literal value used in an abstract syntax tree.

Public Functions

template<typename T>
inline literal(cudf::numeric_scalar<T> &value)

Construct a new literal object.

Template Parameters:

T – Numeric scalar template type

Parameters:

value – A numeric scalar value

template<typename T>
inline literal(cudf::timestamp_scalar<T> &value)

Construct a new literal object.

Template Parameters:

T – Timestamp scalar template type

Parameters:

value – A timestamp scalar value

template<typename T>
inline literal(cudf::duration_scalar<T> &value)

Construct a new literal object.

Template Parameters:

T – Duration scalar template type

Parameters:

value – A duration scalar value

inline literal(cudf::string_scalar &value)

Construct a new literal object.

Parameters:

value – A string scalar value

inline cudf::data_type get_data_type() const

Get the data type.

Returns:

The data type of the literal

inline generic_scalar_device_view get_value() const

Get the value object.

Returns:

The device scalar object

virtual cudf::size_type accept(detail::expression_parser &visitor) const override

Accepts a visitor class.

Parameters:

visitor – The expression_parser parsing this expression tree

Returns:

Index of device data reference for this instance

virtual std::reference_wrapper<expression const> accept(detail::expression_transformer &visitor) const override

Accepts a visitor class.

Parameters:

visitor – The expression_parser parsing this expression tree

Returns:

Index of device data reference for this instance

inline virtual bool may_evaluate_null(table_view const &left, table_view const &right, rmm::cuda_stream_view stream) const override

Returns true if the expression may evaluate to null.

Parameters:

• left – The left operand of the expression

• right – The right operand of the expression

• stream – CUDA stream used for device memory operations and kernel launches

Returns:

true if the expression may evaluate to null, otherwise false

inline bool is_valid(rmm::cuda_stream_view stream) const

Check if the underlying scalar is valid.

Parameters:

stream – CUDA stream used for device memory operations and kernel launches

Returns:

true if the underlying scalar is valid

class column_reference : public cudf::ast::expression

#include <expressions.hpp>

A expression referring to data from a column in a table.

Public Functions

inline column_reference(cudf::size_type column_index, table_reference table_source = table_reference::LEFT)

Construct a new column reference object.

Parameters:

• column_index – Index of this column in the table (provided when the expression is evaluated).

• table_source – Which table to use in cases with two tables (e.g. joins)

inline cudf::size_type get_column_index() const

Get the column index.

Returns:

The column index of the column reference

inline table_reference get_table_source() const

Get the table source.

Returns:

table_reference The reference to the table containing this column

inline cudf::data_type get_data_type(table_view const &table) const

Get the data type.

Parameters:

table – Table used to determine types

Returns:

The data type of the column

inline cudf::data_type get_data_type(table_view const &left_table, table_view const &right_table) const

Get the data type.

Parameters:

• left_table – Left table used to determine types

• right_table – Right table used to determine types

Returns:

The data type of the column

virtual cudf::size_type accept(detail::expression_parser &visitor) const override

Accepts a visitor class.

Parameters:

visitor – The expression_parser parsing this expression tree

Returns:

Index of device data reference for this instance

virtual std::reference_wrapper<expression const> accept(detail::expression_transformer &visitor) const override

Accepts a visitor class.

Parameters:

visitor – The expression_parser parsing this expression tree

Returns:

Index of device data reference for this instance

inline virtual bool may_evaluate_null(table_view const &left, table_view const &right, rmm::cuda_stream_view stream) const override

Returns true if the expression may evaluate to null.

Parameters:

• left – The left operand of the expression

• right – The right operand of the expression

• stream – CUDA stream used for device memory operations and kernel launches

Returns:

true if the expression may evaluate to null, otherwise false

class operation : public cudf::ast::expression

#include <expressions.hpp>

An operation expression holds an operator and zero or more operands.

Public Functions

operation(ast_operator op, expression const &input)

Construct a new unary operation object.

Parameters:

• op – Operator

• input – Input expression (operand)

operation(ast_operator op, expression const &left, expression const &right)

Construct a new binary operation object.

Parameters:

• op – Operator

• left – Left input expression (left operand)

• right – Right input expression (right operand)

inline ast_operator get_operator() const

Get the operator.

Returns:

The operator

inline std::vector<std::reference_wrapper<expression const>> const &get_operands() const

Get the operands.

Returns:

Vector of operands

virtual cudf::size_type accept(detail::expression_parser &visitor) const override

Accepts a visitor class.

Parameters:

visitor – The expression_parser parsing this expression tree

Returns:

Index of device data reference for this instance

virtual std::reference_wrapper<expression const> accept(detail::expression_transformer &visitor) const override

Accepts a visitor class.

Parameters:

visitor – The expression_parser parsing this expression tree

Returns:

Index of device data reference for this instance

inline virtual bool may_evaluate_null(table_view const &left, table_view const &right, rmm::cuda_stream_view stream) const override

Returns true if the expression may evaluate to null.

Parameters:

• left – The left operand of the expression

• right – The right operand of the expression

• stream – CUDA stream used for device memory operations and kernel launches

Returns:

true if the expression may evaluate to null, otherwise false

class column_name_reference : public cudf::ast::expression

#include <expressions.hpp>

A expression referring to data from a column in a table.

Public Functions

inline column_name_reference(std::string column_name)

Construct a new column name reference object.

Parameters:

column_name – Name of this column in the table metadata (provided when the expression is evaluated).

inline std::string get_column_name() const

Get the column name.

Returns:

The name of this column reference

virtual cudf::size_type accept(detail::expression_parser &visitor) const override

Accepts a visitor class.

Parameters:

visitor – The expression_parser parsing this expression tree

Returns:

Index of device data reference for this instance

virtual std::reference_wrapper<expression const> accept(detail::expression_transformer &visitor) const override

Accepts a visitor class.

Parameters:

visitor – The expression_parser parsing this expression tree

Returns:

Index of device data reference for this instance

inline virtual bool may_evaluate_null(table_view const &left, table_view const &right, rmm::cuda_stream_view stream) const override

Returns true if the expression may evaluate to null.

Parameters:

• left – The left operand of the expression

• right – The right operand of the expression

• stream – CUDA stream used for device memory operations and kernel launches

Returns:

true if the expression may evaluate to null, otherwise false

class tree

#include <expressions.hpp>

An AST expression tree. It owns and contains multiple dependent expressions. All the expressions are destroyed when the tree is destructed.

Public Functions

tree() = default

construct an empty ast tree

tree(tree&&) = default

Moves the ast tree.

tree &operator=(tree&&) = default

move-assigns the AST tree

Returns:

a reference to the move-assigned tree

template<typename Expr, typename ...Args>
inline Expr const &emplace(Args&&... args)

Add an expression to the AST tree.

Parameters:

args – Arguments to use to construct the ast expression

Returns:

a reference to the added expression

template<typename Expr>
inline Expr const &push(Expr expr)

Add an expression to the AST tree.

Parameters:

expr – AST expression to be added

Returns:

a reference to the added expression

inline expression const &front() const

get the first expression in the tree

Returns:

the first inserted expression into the tree

inline expression const &back() const

get the last expression in the tree

Returns:

the last inserted expression into the tree

inline size_t size() const

get the number of expressions added to the tree

Returns:

the number of expressions added to the tree

inline expression const &at(size_t index)

get the expression at an index in the tree. Index is checked.

Parameters:

index – index of expression in the ast tree

Returns:

the expression at the specified index

inline expression const &operator[](size_t index) const

get the expression at an index in the tree. Index is unchecked.

Parameters:

index – index of expression in the ast tree

Returns:

the expression at the specified index