Example code for blog on new row comparators

cpp/examples/README.md

@@ -7,3 +7,4 @@ Current examples:
 
 - Basic: demonstrates a basic use case with libcudf and building a custom application with libcudf
 - Strings: demonstrates using libcudf for accessing and creating strings columns and for building custom kernels for strings
+- Nested Types: demonstrates using libcudf for some operations on nested types

cpp/examples/build.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 
-# Copyright (c) 2021-2022, NVIDIA CORPORATION.
+# Copyright (c) 2021-2023, NVIDIA CORPORATION.
 
 # libcudf examples build script
 
@@ -29,3 +29,11 @@ STRINGS_EXAMPLE_BUILD_DIR=${STRINGS_EXAMPLE_DIR}/build
 cmake -S ${STRINGS_EXAMPLE_DIR} -B ${STRINGS_EXAMPLE_BUILD_DIR} -Dcudf_ROOT="${LIB_BUILD_DIR}"
 # Build
 cmake --build ${STRINGS_EXAMPLE_BUILD_DIR} -j${PARALLEL_LEVEL}
+
+# Nested Types example
+NESTED_TYPES_EXAMPLE_DIR=${EXAMPLES_DIR}/nested_types
+NESTED_TYPES_EXAMPLE_BUILD_DIR=${NESTED_TYPES_EXAMPLE_DIR}/build
+# Configure
+cmake -S ${NESTED_TYPES_EXAMPLE_DIR} -B ${NESTED_TYPES_EXAMPLE_BUILD_DIR} -Dcudf_ROOT="${LIB_BUILD_DIR}"
+# Build
+cmake --build ${NESTED_TYPES_EXAMPLE_BUILD_DIR} -j${PARALLEL_LEVEL}

cpp/examples/nested_types/CMakeLists.txt

@@ -0,0 +1,32 @@
+# Copyright (c) 2023, NVIDIA CORPORATION.
+
+cmake_minimum_required(VERSION 3.26.4)
+
+project(
+  nested_types
+  VERSION 0.0.1
+  LANGUAGES CXX CUDA
+)
+
+set(CPM_DOWNLOAD_VERSION v0.35.3)
+file(
+  DOWNLOAD
+  https://github.com/cpm-cmake/CPM.cmake/releases/download/${CPM_DOWNLOAD_VERSION}/get_cpm.cmake
+  ${CMAKE_BINARY_DIR}/cmake/get_cpm.cmake
+)
+include(${CMAKE_BINARY_DIR}/cmake/get_cpm.cmake)
+
+set(CUDF_TAG branch-23.10)
+CPMFindPackage(
+  NAME cudf GIT_REPOSITORY https://github.com/rapidsai/cudf
+  GIT_TAG ${CUDF_TAG}
+  GIT_SHALLOW
+    TRUE
+    SOURCE_SUBDIR
+    cpp
+)
+
+# Configure your project here
+add_executable(deduplication deduplication.cpp)
+target_link_libraries(deduplication PRIVATE cudf::cudf)
+target_compile_features(deduplication PRIVATE cxx_std_17)

cpp/examples/nested_types/deduplication.cpp

@@ -0,0 +1,205 @@
+/*
+ * Copyright (c) 2023, NVIDIA 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.
+ */
+
+#include <cudf/column/column_factories.hpp>
+#include <cudf/column/column_view.hpp>
+#include <cudf/copying.hpp>
+#include <cudf/groupby.hpp>
+#include <cudf/io/json.hpp>
+#include <cudf/io/types.hpp>
+#include <cudf/join.hpp>
+#include <cudf/sorting.hpp>
+#include <cudf/stream_compaction.hpp>
+#include <cudf/table/table_view.hpp>
+
+#include <rmm/mr/device/cuda_memory_resource.hpp>
+#include <rmm/mr/device/device_memory_resource.hpp>
+#include <rmm/mr/device/owning_wrapper.hpp>
+#include <rmm/mr/device/pool_memory_resource.hpp>
+
+#include <chrono>
+#include <iostream>
+#include <string>
+
+/**
+ * @file deduplication.cpp
+ * @brief Demonstrates usage of the libcudf APIs to perform operations on nested-type tables.
+ *
+ * The algorithms chosen to be demonstrated are to showcase nested-type row operators of three
+ * kinds:
+ * 1. hashing: Used by functions `count_aggregate` and `join_count` to hash inputs of any type
+ * 2. equality: Used by functions `count_aggregate` and `join_count` in conjunction with hashing
+ *              to determine equality for nested types
+ * 3. lexicographic: Used by function `sort_keys` to create a lexicographical order for nested-types
+ * so as to enable sorting
+ *
+ * @note This example is for demonstration purposes only. It is not intended to show the most
+ * performant way to do the example algorithm.
+ *
+ */
+
+/**
+ * @brief Create CUDA memory resource
+ */
+auto make_cuda_mr() { return std::make_shared<rmm::mr::cuda_memory_resource>(); }
+
+/**
+ * @brief Create a pool device memory resource
+ */
+auto make_pool_mr()
+{
+  return rmm::mr::make_owning_wrapper<rmm::mr::pool_memory_resource>(make_cuda_mr());
+}
+
+/**
+ * @brief Create memory resource for libcudf functions
+ */
+std::shared_ptr<rmm::mr::device_memory_resource> create_memory_resource(std::string_view name)
+{
+  if (name == "pool") { return make_pool_mr(); }
+  return make_cuda_mr();
+}
+
+cudf::io::table_with_metadata read_json(std::string filepath)
+{
+  auto source_info = cudf::io::source_info(filepath);
+  auto builder     = cudf::io::json_reader_options::builder(source_info).lines(true);
+  auto options     = builder.build();
+  return cudf::io::read_json(options);
+}
+
+void write_json(cudf::table_view tbl, cudf::io::table_metadata metadata, std::string filepath)
+{
+  // write the data for inspection
+  auto sink_info = cudf::io::sink_info(filepath);
+  auto builder   = cudf::io::json_writer_options::builder(sink_info, tbl).lines(true);
+  builder.metadata(metadata);
+  auto options = builder.build();
+  cudf::io::write_json(options);
+}
+
+/**
+ * @brief Aggregate count of duplicate rows in nested-type column
+ */
+std::unique_ptr<cudf::table> count_aggregate(cudf::table_view tbl)
+{
+  // Get count for each key
+  auto keys = cudf::table_view{{tbl.column(0)}};
+  auto val  = cudf::make_numeric_column(cudf::data_type{cudf::type_id::INT32}, keys.num_rows());
+
+  cudf::groupby::groupby grpby_obj(keys);
+  std::vector<cudf::groupby::aggregation_request> requests;
+  requests.emplace_back(cudf::groupby::aggregation_request());
+  auto agg = cudf::make_count_aggregation<cudf::groupby_aggregation>();
+  requests[0].aggregations.push_back(std::move(agg));
+  requests[0].values = *val;
+  auto agg_results   = grpby_obj.aggregate(requests);
+  auto result_key    = std::move(agg_results.first);
+  auto result_val    = std::move(agg_results.second[0].results[0]);
+
+  auto left_cols = result_key->release();
+  left_cols.push_back(std::move(result_val));
+
+  return std::make_unique<cudf::table>(std::move(left_cols));
+}
+
+/**
+ * @brief Join each row with its duplicate counts
+ */
+std::unique_ptr<cudf::table> join_count(cudf::table_view left, cudf::table_view right)
+{
+  auto [left_indices, right_indices] =
+    cudf::inner_join(cudf::table_view{{left.column(0)}}, cudf::table_view{{right.column(0)}});
+  auto new_left  = cudf::gather(left, cudf::device_span<int const>{*left_indices});
+  auto new_right = cudf::gather(right, cudf::device_span<int const>{*right_indices});
+
+  auto left_cols  = new_left->release();
+  auto right_cols = new_right->release();
+  left_cols.push_back(std::move(right_cols[1]));
+
+  return std::make_unique<cudf::table>(std::move(left_cols));
+}
+
+/**
+ * @brief Sort nested-type column
+ */
+std::unique_ptr<cudf::table> sort_keys(cudf::table_view tbl)
+{
+  auto sort_order = cudf::sorted_order(cudf::table_view{{tbl.column(0)}});
+  return cudf::gather(tbl, *sort_order);
+}
+
+/**
+ * @brief Main for nested_types examples
+ *
+ * Command line parameters:
+ * 1. JSON input file name/path (default: "example.json")
+ * 2. JSON output file name/path (default: "output.json")
+ * 3. Memory resource (optional): "pool" or "cuda" (default: "pool")
+ *
+ * The stdout includes the number of rows in the input and the output size in bytes.
+ */
+int main(int argc, char const** argv)
+{
+  std::string input_filepath;
+  std::string output_filepath;
+  std::string mr_name;
+  if (argc < 4) {
+    input_filepath  = "example.json";
+    output_filepath = "output.json";
+    mr_name         = "pool";
+  } else if (argc == 4) {
+    input_filepath  = argv[1];
+    output_filepath = argv[2];
+    mr_name         = argv[3];
+  } else {
+    std::cout << "Either provide all command-line arguments, or none to use defaults" << std::endl;
+    return 1;
+  }
+
+  auto resource = create_memory_resource(mr_name);
+  rmm::mr::set_current_device_resource(resource.get());
+
+  // read input file
+  auto [tbl, metadata] = read_json(input_filepath);
+
+  auto const st = std::chrono::steady_clock::now();
+
+  auto const count_st                            = std::chrono::steady_clock::now();
+  auto count                                     = count_aggregate(tbl->view());
+  std::chrono::duration<double> const count_time = std::chrono::steady_clock::now() - count_st;
+  std::cout << "count_aggregate time: " << count_time.count() << " seconds\n";
+
+  auto const combined_st = std::chrono::steady_clock::now();
+  auto combined          = join_count(tbl->view(), count->view());
+  std::chrono::duration<double> const combined_time =
+    std::chrono::steady_clock::now() - combined_st;
+  std::cout << "join_count time: " << combined_time.count() << " seconds\n";
+
+  auto const sorted_st                            = std::chrono::steady_clock::now();
+  auto sorted                                     = sort_keys(combined->view());
+  std::chrono::duration<double> const sorted_time = std::chrono::steady_clock::now() - sorted_st;
+  std::cout << "sort_keys time: " << sorted_time.count() << " seconds\n";
+
+  metadata.schema_info.emplace_back("count");
+
+  std::chrono::duration<double> const elapsed = std::chrono::steady_clock::now() - st;
+  std::cout << "Wall time: " << elapsed.count() << " seconds\n";
+
+  write_json(sorted->view(), metadata, output_filepath);
+
+  return 0;
+}

cpp/examples/nested_types/example.json

@@ -0,0 +1,5 @@
+{"features": {"key":"a1", "value": [{"info":"message_1", "type": "device_a", "dt": 1688750001}]}, "source": "network_a", "quality": 0.7}
+{"features": {"key":"a2", "value": [{"info":"message_2", "type": "device_a", "dt": 1688750002}]}, "source": "network_a", "quality": 0.7}
+{"features": {"key":"a3", "value": [{"info":"message_3", "type": "device_a", "dt": 1688750003}]}, "source": "network_b", "quality": 0.8}
+{"features": {"key":"a1", "value": [{"info":"message_1", "type": "device_a", "dt": 1688750001}]}, "source": "network_b", "quality": 0.9}
+{"features": {"key":"a4", "value": [{"info":"message_4", "type": "device_a", "dt": 1688750004}]}, "source": "network_b", "quality": 0.9}

cpp/include/cudf/detail/gather.cuh

@@ -483,7 +483,7 @@ struct column_gatherer_impl<struct_view> {
     auto const nullable =
       nullify_out_of_bounds || std::any_of(sliced_children.begin(),
                                            sliced_children.end(),
-                                           [](auto const& col) { return col.nullable(); });
+                                           [](auto const& col) { return col.has_nulls(); });
 
     if (nullable) {
       gather_bitmask(
@@ -569,8 +569,8 @@ void gather_bitmask(table_view const& source,
 
   // Create null mask if source is nullable but target is not
   for (size_t i = 0; i < target.size(); ++i) {
-    if ((source.column(i).nullable() or op == gather_bitmask_op::NULLIFY) and
-        not target[i]->nullable()) {
+    if ((source.column(i).has_nulls() or op == gather_bitmask_op::NULLIFY) and
+        not target[i]->has_nulls()) {
       auto const state =
         op == gather_bitmask_op::PASSTHROUGH ? mask_state::ALL_VALID : mask_state::UNINITIALIZED;
       auto mask = detail::create_null_mask(target[i]->size(), state, stream, mr);
@@ -613,7 +613,7 @@ void gather_bitmask(table_view const& source,
   // Copy the valid counts into each column
   auto const valid_counts = make_std_vector_sync(d_valid_counts, stream);
   for (size_t i = 0; i < target.size(); ++i) {
-    if (target[i]->nullable()) {
+    if (target[i]->has_nulls()) {
       auto const null_count = target_rows - valid_counts[i];
       target[i]->set_null_count(null_count);
     }
@@ -675,7 +675,7 @@ std::unique_ptr<table> gather(table_view const& source_table,
 
   auto const nullable = bounds_policy == out_of_bounds_policy::NULLIFY ||
                         std::any_of(source_table.begin(), source_table.end(), [](auto const& col) {
-                          return col.nullable();
+                          return col.has_nulls();
                         });
   if (nullable) {
     auto const op = bounds_policy == out_of_bounds_policy::NULLIFY ? gather_bitmask_op::NULLIFY

cpp/include/cudf/detail/null_mask.cuh

@@ -42,6 +42,8 @@
 #include <optional>
 #include <vector>
 
+#include <cudf/detail/nvtx/ranges.hpp>
+
 namespace cudf {
 namespace detail {
 /**
@@ -156,6 +158,7 @@ size_type inplace_bitmask_binop(Binop op,
                                 size_type mask_size_bits,
                                 rmm::cuda_stream_view stream)
 {
+  CUDF_FUNC_RANGE();
   CUDF_EXPECTS(
     std::all_of(masks_begin_bits.begin(), masks_begin_bits.end(), [](auto b) { return b >= 0; }),
     "Invalid range.");

cpp/src/structs/utilities.cpp

@@ -30,6 +30,8 @@
 #include <thrust/iterator/counting_iterator.h>
 #include <thrust/iterator/transform_iterator.h>
 
+#include <cudf/detail/nvtx/ranges.hpp>
+
 namespace cudf::structs::detail {
 
 /**
@@ -397,6 +399,7 @@ std::pair<column_view, temporary_nullable_data> push_down_nulls(column_view cons
                                                                 rmm::cuda_stream_view stream,
                                                                 rmm::mr::device_memory_resource* mr)
 {
+  CUDF_FUNC_RANGE();
   auto output = push_down_nulls_no_sanitize(input, stream, mr);
 
   if (auto const output_view = output.first;
@@ -410,7 +413,6 @@ std::pair<column_view, temporary_nullable_data> push_down_nulls(column_view cons
     // must be done after calling it.
     output.second.new_null_masks.clear();
   }
-
   return output;
 }
 

cpp/src/table/row_operators.cu

@@ -34,6 +34,8 @@
 
 #include <thrust/iterator/transform_iterator.h>
 
+#include <cudf/detail/nvtx/ranges.hpp>
+
 namespace cudf {
 namespace experimental {
 
@@ -73,6 +75,7 @@ std::vector<column_view> unslice_children(column_view const& c)
  */
 table_view remove_struct_child_offsets(table_view table)
 {
+  CUDF_FUNC_RANGE();
   std::vector<column_view> cols;
   cols.reserve(table.num_columns());
   std::transform(table.begin(), table.end(), std::back_inserter(cols), [&](column_view const& c) {
@@ -185,6 +188,7 @@ auto decompose_structs(table_view table,
                        host_span<order const> column_order         = {},
                        host_span<null_order const> null_precedence = {})
 {
+  CUDF_FUNC_RANGE();
   auto linked_columns = detail::table_to_linked_columns(table);
 
   std::vector<column_view> verticalized_columns;