join.hpp

Go to the documentation of this file.

/*
 * SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 * SPDX-License-Identifier: Apache-2.0
 */
 
#pragma once
 
#include <cudf/ast/expressions.hpp>
#include <cudf/table/table_view.hpp>
#include <cudf/types.hpp>
#include <cudf/utilities/default_stream.hpp>
#include <cudf/utilities/export.hpp>
#include <cudf/utilities/memory_resource.hpp>
 
#include <rmm/device_uvector.hpp>
 
#include <cuda/std/limits>
#include <cuda/stream>
 
#include <cstddef>
#include <cstdint>
#include <memory>
#include <optional>
#include <utility>
 
namespace CUDF_EXPORT cudf {
 
enum class join_kind : int32_t {
  INNER_JOIN     = 0,  
  LEFT_JOIN      = 1,  
  FULL_JOIN      = 2,  
  LEFT_SEMI_JOIN = 3,  
  LEFT_ANTI_JOIN = 4   
};
 
enum class join_prefilter : bool { NO = false, YES = true };
 
enum class nullable_join : bool { YES = true, NO = false };
 
CUDF_HOST_DEVICE constexpr size_type JoinNoMatch = cuda::std::numeric_limits<size_type>::min();
 
struct join_match_context {
  table_view _left_table;  
  std::unique_ptr<rmm::device_uvector<size_type>>
    _match_counts;  
 
  join_match_context(table_view const& left_table,  // NOLINT(modernize-pass-by-value)
                     std::unique_ptr<rmm::device_uvector<size_type>> match_counts)
    : _left_table{left_table}, _match_counts{std::move(match_counts)}
  {
  }
  join_match_context(join_match_context const&)            = delete;
  join_match_context& operator=(join_match_context const&) = delete;
  join_match_context(join_match_context&&)                 = default;  
  join_match_context& operator=(join_match_context&&) = default;
  virtual ~join_match_context() = default;  
};
 
struct join_partition_context {
  std::unique_ptr<join_match_context>
    left_table_context;      
  size_type left_start_idx;  
  size_type left_end_idx;  
};
 
std::pair<std::unique_ptr<rmm::device_uvector<size_type>>,
          std::unique_ptr<rmm::device_uvector<size_type>>>
inner_join(cudf::table_view const& left_keys,
           cudf::table_view const& right_keys,
           null_equality compare_nulls       = null_equality::EQUAL,
           cuda::stream_ref stream           = cudf::get_default_stream(),
           rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
 
std::pair<std::unique_ptr<rmm::device_uvector<size_type>>,
          std::unique_ptr<rmm::device_uvector<size_type>>>
left_join(cudf::table_view const& left_keys,
          cudf::table_view const& right_keys,
          null_equality compare_nulls       = null_equality::EQUAL,
          cuda::stream_ref stream           = cudf::get_default_stream(),
          rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
 
std::pair<std::unique_ptr<rmm::device_uvector<size_type>>,
          std::unique_ptr<rmm::device_uvector<size_type>>>
full_join(cudf::table_view const& left_keys,
          cudf::table_view const& right_keys,
          null_equality compare_nulls       = null_equality::EQUAL,
          cuda::stream_ref stream           = cudf::get_default_stream(),
          rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
 
std::unique_ptr<cudf::table> cross_join(
  cudf::table_view const& left,
  cudf::table_view const& right,
  cuda::stream_ref stream           = cudf::get_default_stream(),
  rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
 
std::pair<std::unique_ptr<rmm::device_uvector<size_type>>,
          std::unique_ptr<rmm::device_uvector<size_type>>>
filter_join_indices(cudf::table_view const& left,
                    cudf::table_view const& right,
                    cudf::device_span<size_type const> left_indices,
                    cudf::device_span<size_type const> right_indices,
                    cudf::ast::expression const& predicate,
                    cudf::join_kind join_kind,
                    std::optional<std::size_t> output_size = std::nullopt,
                    cuda::stream_ref stream                = cudf::get_default_stream(),
                    rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
 
[[nodiscard]] std::pair<std::size_t, std::unique_ptr<rmm::device_uvector<size_type>>>
filter_join_indices_output_size(
  cudf::table_view const& left,
  cudf::table_view const& right,
  cudf::device_span<size_type const> left_indices,
  cudf::device_span<size_type const> right_indices,
  cudf::ast::expression const& predicate,
  cudf::join_kind join_kind,
  cuda::stream_ref stream           = cudf::get_default_stream(),
  rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
 
std::pair<std::unique_ptr<rmm::device_uvector<size_type>>,
          std::unique_ptr<rmm::device_uvector<size_type>>>
filter_join_indices_jit(
  cudf::table_view const& left,
  cudf::table_view const& right,
  cudf::device_span<size_type const> left_indices,
  cudf::device_span<size_type const> right_indices,
  std::string const& predicate_code,
  cudf::join_kind join_kind,
  bool is_ptx                       = false,
  cuda::stream_ref stream           = cudf::get_default_stream(),
  rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
 
std::pair<std::unique_ptr<rmm::device_uvector<size_type>>,
          std::unique_ptr<rmm::device_uvector<size_type>>>
filter_join_indices_jit(
  cudf::table_view const& left,
  cudf::table_view const& right,
  cudf::device_span<size_type const> left_indices,
  cudf::device_span<size_type const> right_indices,
  cudf::ast::expression const& predicate,
  cudf::join_kind join_kind,
  cuda::stream_ref stream           = cudf::get_default_stream(),
  rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
  // end of group
 
}  // namespace CUDF_EXPORT cudf