Expose expressions for C API

Author: myrrc

vortex-array/src/dtype/field_names.rs

@@ -317,6 +317,12 @@ impl From<Vec<FieldName>> for FieldNames {
     }
 }
 
+impl From<Vec<String>> for FieldNames {
+    fn from(value: Vec<String>) -> Self {
+        value.into_iter().collect()
+    }
+}
+
 impl From<Vec<Arc<str>>> for FieldNames {
     fn from(value: Vec<Arc<str>>) -> Self {
         value.into_iter().collect()

vortex-ffi/cinclude/vortex.h

@@ -114,6 +114,66 @@ typedef enum {
     DTYPE_FIXED_SIZE_LIST = 9,
 } vx_dtype_variant;
 
+/**
+ * Equalities, inequalities, and boolean operations over possibly null values.
+ * For most operations, if either side is null, the result is null.
+ * VX_OPERATOR_KLEENE_AND, VX_OPERATOR_KLEENE_OR obey Kleene (three-valued)
+ * logic
+ */
+typedef enum {
+    /**
+     * Expressions are equal.
+     */
+    VX_OPERATOR_EQ = 0,
+    /**
+     * Expressions are not equal.
+     */
+    VX_OPERATOR_NOT_EQ = 1,
+    /**
+     * Expression is greater than another
+     */
+    VX_OPERATOR_GT = 2,
+    /**
+     * Expression is greater or equal to another
+     */
+    VX_OPERATOR_GTE = 3,
+    /**
+     * Expression is less than another
+     */
+    VX_OPERATOR_LT = 4,
+    /**
+     * Expression is less or equal to another
+     */
+    VX_OPERATOR_LTE = 5,
+    /**
+     * Boolean AND /\.
+     */
+    VX_OPERATOR_KLEENE_AND = 6,
+    /**
+     * Boolean OR \/.
+     */
+    VX_OPERATOR_KLEENE_OR = 7,
+    /**
+     * The sum of the arguments.
+     * Errors at runtime if the sum would overflow or underflow.
+     */
+    VX_OPERATOR_ADD = 8,
+    /**
+     * The difference between the arguments.
+     * Errors at runtime if the sum would overflow or underflow.
+     * The result is null at any index where either input is null.
+     */
+    VX_OPERATOR_SUB = 9,
+    /**
+     * Multiple two numbers
+     */
+    VX_OPERATOR_MUL = 10,
+    /**
+     * Divide the left side by the right side
+     */
+    VX_OPERATOR_DIV = 11,
+} vx_operator;
+
 /**
  * Log levels for the Vortex library.
  */
@@ -297,6 +357,22 @@ typedef struct vx_dtype vx_dtype;
  */
 typedef struct vx_error vx_error;
 
+/**
+ * A node in a Vortex expression tree.
+ *
+ * Expressions represent scalar computations that can be performed on
+ * data. Each expression consists of an encoding (vtable), heap-allocated
+ * metadata, and child expressions.
+ *
+ * Unless stated explicitly, all expressions returned are owned and must
+ * be freed by the caller.
+ * Unless stated explicitly, if an operation on const vx_expression* is
+ * passed NULL, NULL is returned.
+ * Operations on expressions don't take ownership of input values, and so
+ * input values must be freed by the caller.
+ */
+typedef struct vx_expression vx_expression;
+
 /**
  * A handle to a Vortex file encapsulating the footer and logic for instantiating a reader.
  */
@@ -478,6 +554,11 @@ const vx_string *vx_array_get_utf8(const vx_array *array, uint32_t index);
  */
 const vx_binary *vx_array_get_binary(const vx_array *array, uint32_t index);
 
+/**
+ * Apply the expression to the array, producing a new array in constant time
+ */
+const vx_array *vx_array_apply(const vx_array *array, const vx_expression *expression, vx_error **error);
+
 /**
  * Free an owned [`vx_array_iterator`] object.
  */
@@ -677,6 +758,100 @@ void vx_error_free(vx_error *ptr);
  */
 const vx_string *vx_error_get_message(const vx_error *error);
 
+/**
+ * Clone a borrowed [`vx_expression`], returning an owned [`vx_expression`].
+ *
+ *
+ * Must be released with [`vx_expression_free`].
+ */
+const vx_expression *vx_expression_clone(const vx_expression *ptr);
+
+/**
+ * Free an owned [`vx_expression`] object.
+ */
+void vx_expression_free(const vx_expression *ptr);
+
+/**
+ * Create a root expression
+ */
+const vx_expression *vx_expression_root(void);
+
+/**
+ * Create an expression that accesses a field from the root array.
+ *
+ * Equivalent to get_item(name, root()).
+ */
+const vx_expression *vx_expression_column(const char *name);
+
+/**
+ * Create an expression that selects (includes) specific fields from a child
+ * expression. Child expression must have a DTYPE_STRUCT dtype.
+ *
+ * Example:
+ *
+ * const vx_expression* root = vx_expression_root();
+ * const char* names[] = {"name", "age"};
+ * const vx_expression* select = vx_expression_select(names, 2, root);
+ * vx_expression_free(select);
+ * vx_expression_free(root);
+ *
+ */
+const vx_expression *vx_expression_select(const char *const *names, size_t len, const vx_expression *child);
+
+/**
+ * Create an AND expression for multiple child expressions.
+ * If there are no input expressions, returns NULL.
+ */
+const vx_expression *vx_expression_and(const vx_expression *const *expressions, size_t len);
+
+/**
+ * Create an OR disjunction expression for multiple child expressions.
+ * If there are no input expressions, returns NULL.
+ */
+const vx_expression *vx_expression_or(const vx_expression *const *expressions, size_t len);
+
+/**
+ * Create a binary expression for two expressions of form lhs OP rhs.
+ * If either input is NULL, returns NULL.
+ *
+ * Example:
+ *
+ * const vx_expression* age = vx_expression_column("age");
+ * const vx_expression* height = vx_expression_column("height");
+ * const vx_expression* sum = vx_expression_binary(VX_OPERATOR_SUM, age, height);
+ * vx_expression_free(sum);
+ * vx_expression_free(height);
+ * vx_expression_free(age);
+ *
+ */
+const vx_expression *
+vx_expression_binary(vx_operator operator_, const vx_expression *lhs, const vx_expression *rhs);
+
+const vx_expression *vx_expression_eq(const vx_expression *lhs, const vx_expression *rhs);
+
+const vx_expression *vx_expression_not_eq(const vx_expression *lhs, const vx_expression *rhs);
+
+const vx_expression *vx_expression_lt(const vx_expression *lhs, const vx_expression *rhs);
+
+const vx_expression *vx_expression_lt_eq(const vx_expression *lhs, const vx_expression *rhs);
+
+const vx_expression *vx_expression_gt(const vx_expression *lhs, const vx_expression *rhs);
+
+const vx_expression *vx_expression_gt_eq(const vx_expression *lhs, const vx_expression *rhs);
+
+const vx_expression *vx_expression_not(const vx_expression *child);
+
+/**
+ * Create an expression that checks for null values.
+ *
+ * Return a boolean array indicating which positions contain null values.
+ */
+const vx_expression *vx_expression_is_null(const vx_expression *child);
+
+const vx_expression *vx_expression_get_item(const vx_expression *child, const char *item);
+
+const vx_expression *vx_expression_list_contains(const vx_expression *list, const vx_expression *value);
+
 /**
  * Clone a borrowed [`vx_file`], returning an owned [`vx_file`].
  *

vortex-ffi/src/array.rs

@@ -9,13 +9,15 @@ use vortex::array::DynArray;
 use vortex::array::ToCanonical;
 use vortex::dtype::half::f16;
 use vortex::error::VortexExpect;
+use vortex::error::vortex_ensure;
 use vortex::error::vortex_err;
 
 use crate::arc_dyn_wrapper;
 use crate::binary::vx_binary;
 use crate::dtype::vx_dtype;
 use crate::error::try_or_default;
 use crate::error::vx_error;
+use crate::expression::vx_expression;
 use crate::string::vx_string;
 
 arc_dyn_wrapper!(
@@ -186,11 +188,28 @@ pub unsafe extern "C-unwind" fn vx_array_get_binary(
     }
 }
 
+/// Apply the expression to the array, producing a new array in constant time
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn vx_array_apply(
+    array: *const vx_array,
+    expression: *const vx_expression,
+    error: *mut *mut vx_error,
+) -> *const vx_array {
+    try_or_default(error, || {
+        vortex_ensure!(!array.is_null());
+        vortex_ensure!(!expression.is_null());
+        let array = vx_array::as_ref(array);
+        let expression = vx_expression::as_ref(expression);
+        Ok(vx_array::new(Arc::new(array.apply(expression)?)))
+    })
+}
+
 #[cfg(test)]
 mod tests {
     use std::ptr;
 
     use vortex::array::IntoArray;
+    use vortex::array::arrays::BoolArray;
     use vortex::array::arrays::PrimitiveArray;
     use vortex::array::arrays::StructArray;
     use vortex::array::arrays::VarBinViewArray;
@@ -199,12 +218,16 @@ mod tests {
     use vortex::buffer::buffer;
     #[cfg(not(miri))]
     use vortex::dtype::half::f16;
+    use vortex::expr::eq;
+    use vortex::expr::lit;
+    use vortex::expr::root;
 
     use crate::array::*;
     use crate::binary::vx_binary_free;
     use crate::dtype::vx_dtype_get_variant;
     use crate::dtype::vx_dtype_variant;
     use crate::error::vx_error_free;
+    use crate::expression::vx_expression_free;
     use crate::string::vx_string_free;
 
     #[test]
@@ -424,6 +447,55 @@ mod tests {
         }
     }
 
+    #[test]
+    #[cfg_attr(miri, ignore)]
+    fn test_apply() {
+        let primitive = PrimitiveArray::new(
+            buffer![1i32, 2i32, 3i32, 3i32],
+            Validity::from_iter([true, false, true, true]),
+        );
+
+        unsafe {
+            let mut error = ptr::null_mut();
+
+            let res = vx_array_apply(ptr::null(), ptr::null(), &raw mut error);
+            assert!(res.is_null());
+            assert!(!error.is_null());
+            vx_error_free(error);
+
+            let array = vx_array::new(primitive.into_array());
+
+            let res = vx_array_apply(array, ptr::null(), &raw mut error);
+            assert!(res.is_null());
+            assert!(!error.is_null());
+            vx_error_free(error);
+
+            // Test with Vortex Rust-side expressions here, test C API for
+            // expressions in src/expressions.rs
+            let expression = eq(root(), lit(3i32));
+            let expression = vx_expression::new(Arc::new(expression));
+
+            let res = vx_array_apply(ptr::null(), expression, &raw mut error);
+            assert!(res.is_null());
+            assert!(!error.is_null());
+            vx_error_free(error);
+
+            let res = vx_array_apply(array, expression, &raw mut error);
+            assert!(!res.is_null());
+            assert!(error.is_null());
+            {
+                let res = vx_array::as_ref(res);
+                let buffer = res.to_bool().to_bit_buffer();
+                let expected = BoolArray::from_iter(vec![false, false, true, true]);
+                assert_eq!(buffer, expected.to_bit_buffer());
+            }
+            vx_array_free(res);
+
+            vx_expression_free(expression);
+            vx_array_free(array);
+        }
+    }
+
     #[test]
     fn test_array_dtype_lifetime_pattern() {
         let array = {