GDV-13: [C++] Add support for filters (apache#75)

- similar to projection, filter is built for a specific schema and
  condition (i.e expression)
- the output of filter is a selection vector (Int16Array)

Author: pravindra

include/gandiva/condition.h

@@ -0,0 +1,36 @@
+/*
+ * Copyright (C) 2017-2018 Dremio Corporation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+#ifndef GANDIVA_CONDITION_H
+#define GANDIVA_CONDITION_H
+
+#include "gandiva/arrow.h"
+#include "gandiva/expression.h"
+#include "gandiva/gandiva_aliases.h"
+
+namespace gandiva {
+
+/// \brief A condition expression.
+class Condition : public Expression {
+ public:
+  Condition(const NodePtr root)
+      : Expression(root, std::make_shared<arrow::Field>("cond", arrow::boolean())) {}
+
+  virtual ~Condition() = default;
+};
+
+}  // namespace gandiva
+
+#endif  // GANDIVA_CONDITION_H

include/gandiva/expression.h

@@ -26,6 +26,8 @@ class Expression {
  public:
   Expression(const NodePtr root, const FieldPtr result) : root_(root), result_(result) {}
 
+  virtual ~Expression() = default;
+
   const NodePtr &root() const { return root_; }
 
   const FieldPtr &result() const { return result_; }

include/gandiva/filter.h

@@ -0,0 +1,82 @@
+/*
+ * Copyright (C) 2017-2018 Dremio Corporation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either condess or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+#ifndef GANDIVA_EXPR_FILTER_H
+#define GANDIVA_EXPR_FILTER_H
+
+#include <memory>
+#include <string>
+#include <utility>
+#include <vector>
+
+#include "gandiva/arrow.h"
+#include "gandiva/condition.h"
+#include "gandiva/configuration.h"
+#include "gandiva/selection_vector.h"
+#include "gandiva/status.h"
+
+namespace gandiva {
+
+class LLVMGenerator;
+
+/// \brief filter records based on a condition.
+///
+/// A filter is built for a specific schema and condition. Once the filter is built, it
+/// can be used to evaluate many row batches.
+class Filter {
+ public:
+  Filter(std::unique_ptr<LLVMGenerator> llvm_generator, SchemaPtr schema,
+         std::shared_ptr<Configuration> config);
+
+  ~Filter() = default;
+
+  /// Build a filter for the given schema and condition, with the default configuration.
+  ///
+  /// \param[in] : schema schema for the record batches, and the condition.
+  /// \param[in] : condition filter condition.
+  /// \param[out]: filter the returned filter object
+  static Status Make(SchemaPtr schema, ConditionPtr condition,
+                     std::shared_ptr<Filter> *filter) {
+    return Make(schema, condition, ConfigurationBuilder::DefaultConfiguration(), filter);
+  }
+
+  /// \brief Build a filter for the given schema and condition.
+  /// Customize the filter with runtime configuration.
+  ///
+  /// \param[in] : schema schema for the record batches, and the condition.
+  /// \param[in] : condition filter conditions.
+  /// \param[in] : config run time configuration.
+  /// \param[out]: filter the returned filter object
+  static Status Make(SchemaPtr schema, ConditionPtr condition,
+                     std::shared_ptr<Configuration> config,
+                     std::shared_ptr<Filter> *filter);
+
+  /// Evaluate the specified record batch, and populate output selection vector.
+  ///
+  /// \param[in] : batch the record batch. schema should be the same as the one in 'Make'
+  /// \param[in/out]: out_selection the selection array with indices of rows that match
+  ///                 the condition.
+  Status Evaluate(const arrow::RecordBatch &batch,
+                  std::shared_ptr<SelectionVector> out_selection);
+
+ private:
+  const std::unique_ptr<LLVMGenerator> llvm_generator_;
+  const SchemaPtr schema_;
+  const std::shared_ptr<Configuration> configuration_;
+};
+
+}  // namespace gandiva
+
+#endif  // GANDIVA_EXPR_FILTER_H

include/gandiva/gandiva_aliases.h

@@ -42,6 +42,9 @@ class Expression;
 using ExpressionPtr = std::shared_ptr<Expression>;
 using ExpressionVector = std::vector<ExpressionPtr>;
 
+class Condition;
+using ConditionPtr = std::shared_ptr<Condition>;
+
 class Node;
 using NodePtr = std::shared_ptr<Node>;
 using NodeVector = std::vector<std::shared_ptr<Node>>;

include/gandiva/selection_vector.h

@@ -0,0 +1,160 @@
+// Copyright (C) 2017-2018 Dremio Corporation
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#ifndef GANDIVA_SELECTION_VECTOR__H
+#define GANDIVA_SELECTION_VECTOR__H
+
+#include "gandiva/arrow.h"
+#include "gandiva/logging.h"
+#include "gandiva/status.h"
+
+namespace gandiva {
+
+/// \brief Selection Vector : vector of indices in a row-batch for a selection,
+/// backed by an arrow-array.
+class SelectionVector {
+ public:
+  ~SelectionVector() = default;
+
+  /// Get the value at a given index.
+  virtual int GetIndex(int index) const = 0;
+
+  /// Set the value at a given index.
+  virtual void SetIndex(int index, int value) = 0;
+
+  // Get the max supported value in the selection vector.
+  virtual int GetMaxSupportedValue() const = 0;
+
+  /// The maximum slots (capacity) of the selection vector.
+  virtual int GetMaxSlots() const = 0;
+
+  /// The number of slots (size) of the selection vector.
+  virtual int GetNumSlots() const = 0;
+
+  /// Set the number of slots in the selection vector.
+  virtual void SetNumSlots(int num_slots) = 0;
+
+  /// Convert to arrow-array.
+  virtual ArrayPtr ToArray() const = 0;
+
+  /// populate selection vector for all the set bits in the bitmap.
+  ///
+  /// \param[in] : bitmap the bitmap
+  /// \param[in] : bitmap_size size of the bitmap in bytes
+  /// \param[in] : max_bitmap_index max valid index in bitmap (can be lesser than
+  ///              capacity in the bitmap, due to alignment/padding).
+  Status PopulateFromBitMap(const uint8_t *bitmap, int bitmap_size, int max_bitmap_index);
+};
+
+/// \brief template implementation of selection vector with a specific ctype and arrow
+/// type.
+template <typename C_TYPE, typename A_TYPE>
+class SelectionVectorImpl : public SelectionVector {
+ public:
+  SelectionVectorImpl(int max_slots, std::shared_ptr<arrow::Buffer> buffer)
+      : max_slots_(max_slots), num_slots_(0), buffer_(buffer) {
+    raw_data_ = reinterpret_cast<C_TYPE *>(buffer->mutable_data());
+  }
+
+  int GetIndex(int index) const override {
+    DCHECK_LE(index, max_slots_);
+    return raw_data_[index];
+  }
+
+  void SetIndex(int index, int value) override {
+    DCHECK_LE(index, max_slots_);
+    DCHECK_LE(value, GetMaxSupportedValue());
+
+    raw_data_[index] = value;
+  }
+
+  ArrayPtr ToArray() const override;
+
+  int GetMaxSlots() const override { return max_slots_; }
+
+  int GetNumSlots() const override { return num_slots_; }
+
+  void SetNumSlots(int num_slots) override {
+    DCHECK_LE(num_slots, max_slots_);
+    num_slots_ = num_slots;
+  }
+
+ protected:
+  static Status AllocateBuffer(int max_slots, arrow::MemoryPool *pool,
+                               std::shared_ptr<arrow::Buffer> *buffer);
+
+  static Status ValidateBuffer(int max_slots, std::shared_ptr<arrow::Buffer> buffer);
+
+  /// maximum slots in the vector
+  int max_slots_;
+
+  /// number of slots in the vector
+  int num_slots_;
+
+  std::shared_ptr<arrow::Buffer> buffer_;
+  C_TYPE *raw_data_;
+};
+
+template <typename C_TYPE, typename A_TYPE>
+ArrayPtr SelectionVectorImpl<C_TYPE, A_TYPE>::ToArray() const {
+  auto data_type = arrow::TypeTraits<A_TYPE>::type_singleton();
+  auto array_data = arrow::ArrayData::Make(data_type, num_slots_, {nullptr, buffer_});
+  return arrow::MakeArray(array_data);
+}
+
+class SelectionVectorInt16 : public SelectionVectorImpl<int16_t, arrow::Int16Type> {
+ public:
+  SelectionVectorInt16(int max_slots, std::shared_ptr<arrow::Buffer> buffer)
+      : SelectionVectorImpl(max_slots, buffer) {}
+
+  int GetMaxSupportedValue() const override { return INT16_MAX; }
+
+  /// \param[in] : max_slots max number of slots
+  /// \param[in] : buffer buffer sized to accomodate max_slots
+  /// \param[out]: selection_vector selection vector backed by 'buffer'
+  static Status Make(int max_slots, std::shared_ptr<arrow::Buffer> buffer,
+                     std::shared_ptr<SelectionVectorInt16> *selection_vector);
+
+  /// \param[in] : max_slots max number of slots
+  /// \param[in] : pool memory pool to allocate buffer
+  /// \param[out]: selection_vector selection vector backed by a buffer allocated from the
+  ///              pool.
+  static Status Make(int max_slots, arrow::MemoryPool *pool,
+                     std::shared_ptr<SelectionVectorInt16> *selection_vector);
+};
+
+class SelectionVectorInt32 : public SelectionVectorImpl<int32_t, arrow::Int32Type> {
+ public:
+  SelectionVectorInt32(int max_slots, std::shared_ptr<arrow::Buffer> buffer)
+      : SelectionVectorImpl(max_slots, buffer) {}
+
+  int GetMaxSupportedValue() const override { return INT32_MAX; }
+
+  /// \param[in] : max_slots max number of slots
+  /// \param[in] : buffer buffer sized to accomodate max_slots
+  /// \param[out]: selection_vector selection vector backed by 'buffer'
+  static Status Make(int max_slots, std::shared_ptr<arrow::Buffer> buffer,
+                     std::shared_ptr<SelectionVectorInt32> *selection_vector);
+
+  /// \param[in] : max_slots max number of slots
+  /// \param[in] : pool memory pool to allocate buffer
+  /// \param[out]: selection_vector selection vector backed by a buffer allocated from the
+  ///              pool.
+  static Status Make(int max_slots, arrow::MemoryPool *pool,
+                     std::shared_ptr<SelectionVectorInt32> *selection_vector);
+};
+
+}  // namespace gandiva
+
+#endif  // GANDIVA_SELECTION_VECTOR__H

include/gandiva/status.h

@@ -35,7 +35,7 @@
 
 #define GANDIVA_RETURN_FAILURE_IF_FALSE(condition, status)                               \
   do {                                                                                   \
-    if (!condition) {                                                                    \
+    if (!(condition)) {                                                                  \
       Status _status = (status);                                                         \
       std::stringstream ss;                                                              \
       ss << __FILE__ << ":" << __LINE__ << " code: " << _status.CodeAsString() << " \n " \
@@ -197,4 +197,4 @@ inline Status& Status::operator&=(Status&& s) {
 }
 
 }  // namespace gandiva
-#endif  // GANDIVA_STATUS_H
+#endif  // GANDIVA_STATUS_H

include/gandiva/tree_expr_builder.h

@@ -19,6 +19,7 @@
 #include <string>
 #include <vector>
 
+#include "gandiva/condition.h"
 #include "gandiva/expression.h"
 
 namespace gandiva {
@@ -74,6 +75,13 @@ class TreeExprBuilder {
   /// returns null if the out_field is null.
   static ExpressionPtr MakeExpression(const std::string &function,
                                       const FieldVector &in_fields, FieldPtr out_field);
+
+  /// \brief create a condition with the specified root_node
+  static ConditionPtr MakeCondition(NodePtr root_node);
+
+  /// \brief convenience function for simple function conditions.
+  static ConditionPtr MakeCondition(const std::string &function,
+                                    const FieldVector &in_fields);
 };
 
 }  // namespace gandiva

integ/CMakeLists.txt

@@ -15,6 +15,7 @@
 project(gandiva)
 
 foreach(lib_type "shared" "static")
+  add_gandiva_integ_test(filter_test.cc gandiva_${lib_type})
   add_gandiva_integ_test(projector_test.cc gandiva_${lib_type})
   add_gandiva_integ_test(if_expr_test.cc gandiva_${lib_type})
   add_gandiva_integ_test(literal_test.cc gandiva_${lib_type})