approx_distinct_count.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/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 <cuda/std/span>
#include <cuda/stream>
 
#include <cstddef>
#include <cstdint>
#include <memory>
 
namespace CUDF_EXPORT cudf {
 
// Forward declarations
namespace hashing::detail {
template <typename Key>
struct XXHash_64;
}
 
namespace detail {
template <template <typename> class Hasher>
class approx_distinct_count;
}
 
class approx_distinct_count {
 public:
  using impl_type =
    cudf::detail::approx_distinct_count<cudf::hashing::detail::XXHash_64>;  
 
  struct desired_standard_error {
    double value;  
 
    explicit constexpr desired_standard_error(double v) : value{v} {}
  };
 
  approx_distinct_count(table_view const& input,
                        std::int32_t precision    = 12,
                        null_policy null_handling = null_policy::EXCLUDE,
                        nan_policy nan_handling   = nan_policy::NAN_IS_NULL,
                        cuda::stream_ref stream   = cudf::get_default_stream(),
                        cuda::mr::any_resource<cuda::mr::device_accessible> mr =
                          cudf::get_current_device_resource_ref());
 
  approx_distinct_count(table_view const& input,
                        desired_standard_error error,
                        null_policy null_handling = null_policy::EXCLUDE,
                        nan_policy nan_handling   = nan_policy::NAN_IS_NULL,
                        cuda::stream_ref stream   = cudf::get_default_stream(),
                        cuda::mr::any_resource<cuda::mr::device_accessible> mr =
                          cudf::get_current_device_resource_ref());
 
  approx_distinct_count(cuda::std::span<cuda::std::byte> sketch_span,
                        std::int32_t precision,
                        null_policy null_handling = null_policy::EXCLUDE,
                        nan_policy nan_handling   = nan_policy::NAN_IS_NULL);
 
  ~approx_distinct_count();
 
  approx_distinct_count(approx_distinct_count const&)            = delete;
  approx_distinct_count& operator=(approx_distinct_count const&) = delete;
  approx_distinct_count(approx_distinct_count&&) = default;  
  approx_distinct_count& operator=(approx_distinct_count&&) = default;
 
  void add(table_view const& input, cuda::stream_ref stream = cudf::get_default_stream());
 
  void merge(approx_distinct_count const& other,
             cuda::stream_ref stream = cudf::get_default_stream());
 
  void merge(cuda::std::span<cuda::std::byte const> sketch_span,
             cuda::stream_ref stream = cudf::get_default_stream());
 
  [[nodiscard]] std::size_t estimate(cuda::stream_ref stream = cudf::get_default_stream()) const;
 
  [[nodiscard]] cuda::std::span<cuda::std::byte> sketch() noexcept;
 
  [[nodiscard]] cuda::std::span<cuda::std::byte const> sketch() const noexcept;
 
  [[nodiscard]] null_policy null_handling() const noexcept;
 
  [[nodiscard]] nan_policy nan_handling() const noexcept;
 
  [[nodiscard]] std::int32_t precision() const noexcept;
 
  [[nodiscard]] double standard_error() const noexcept;
 
  [[nodiscard]] static std::size_t sketch_bytes(std::int32_t precision);
 
  [[nodiscard]] static std::size_t sketch_alignment();
 
 private:
  std::unique_ptr<impl_type> _impl;
};
 
}  // namespace CUDF_EXPORT cudf