[REVIEW] Add nanosecond & microsecond to DatetimeProperties

cpp/include/cudf/datetime.hpp

@@ -133,6 +133,57 @@ std::unique_ptr<cudf::column> extract_second(
   cudf::column_view const& column,
   rmm::mr::device_memory_resource* mr = rmm::mr::get_current_device_resource());
 
+/**
+ * @brief  Extracts millisecond fraction from any date time type and returns an int16_t
+ * cudf::column.
+ *
+ * A millisecond fraction is only the 3 digits that make up the millisecond portion of a duration.
+ * For example, the microsecond fraction of 1.234567890 seconds is 234.
+ *
+ * @param column cudf::column_view of the input datetime values
+ * @param mr Device memory resource used to allocate device memory of the returned column
+ *
+ * @returns cudf::column of the extracted int16_t milliseconds
+ * @throw cudf::logic_error if input column datatype is not TIMESTAMP
+ */
+std::unique_ptr<cudf::column> extract_millisecond_fraction(
+  cudf::column_view const& column,
+  rmm::mr::device_memory_resource* mr = rmm::mr::get_current_device_resource());
+
+/**
+ * @brief  Extracts microsecond fraction from any date time type and returns an int16_t
+ * cudf::column.
+ *
+ * A microsecond fraction is only the 3 digits that make up the microsecond portion of a duration.
+ * For example, the microsecond fraction of 1.234567890 seconds is 567.
+ *
+ * @param column cudf::column_view of the input datetime values
+ * @param mr Device memory resource used to allocate device memory of the returned column
+ *
+ * @returns cudf::column of the extracted int16_t microseconds
+ * @throw cudf::logic_error if input column datatype is not TIMESTAMP
+ */
+std::unique_ptr<cudf::column> extract_microsecond_fraction(
+  cudf::column_view const& column,
+  rmm::mr::device_memory_resource* mr = rmm::mr::get_current_device_resource());
+
+/**
+ * @brief  Extracts nanosecond fraction from any date time type and returns an int16_t
+ * cudf::column.
+ *
+ * A nanosecond fraction is only the 3 digits that make up the nanosecond portion of a duration.
+ * For example, the nanosecond fraction of 1.234567890 seconds is 890.
+ *
+ * @param column cudf::column_view of the input datetime values
+ * @param mr Device memory resource used to allocate device memory of the returned column
+ *
+ * @returns cudf::column of the extracted int16_t nanoseconds
+ * @throw cudf::logic_error if input column datatype is not TIMESTAMP
+ */
+std::unique_ptr<cudf::column> extract_nanosecond_fraction(
+  cudf::column_view const& column,
+  rmm::mr::device_memory_resource* mr = rmm::mr::get_current_device_resource());
+
 /** @} */  // end of group
 /**
  * @addtogroup datetime_compute

cpp/include/cudf/detail/datetime.hpp

@@ -94,6 +94,39 @@ std::unique_ptr<cudf::column> extract_second(
   rmm::cuda_stream_view stream        = cudf::default_stream_value,
   rmm::mr::device_memory_resource* mr = rmm::mr::get_current_device_resource());
 
+/**
+ * @copydoc cudf::extract_millisecond_fraction(cudf::column_view const&,
+ * rmm::mr::device_memory_resource *)
+ *
+ * @param stream CUDA stream used for device memory operations and kernel launches.
+ */
+std::unique_ptr<cudf::column> extract_millisecond_fraction(
+  cudf::column_view const& column,
+  rmm::cuda_stream_view stream        = cudf::default_stream_value,
+  rmm::mr::device_memory_resource* mr = rmm::mr::get_current_device_resource());
+
+/**
+ * @copydoc cudf::extract_microsecond_fraction(cudf::column_view const&,
+ * rmm::mr::device_memory_resource *)
+ *
+ * @param stream CUDA stream used for device memory operations and kernel launches.
+ */
+std::unique_ptr<cudf::column> extract_microsecond_fraction(
+  cudf::column_view const& column,
+  rmm::cuda_stream_view stream        = cudf::default_stream_value,
+  rmm::mr::device_memory_resource* mr = rmm::mr::get_current_device_resource());
+
+/**
+ * @copydoc cudf::extract_nanosecond_fraction(cudf::column_view const&,
+ * rmm::mr::device_memory_resource *)
+ *
+ * @param stream CUDA stream used for device memory operations and kernel launches.
+ */
+std::unique_ptr<cudf::column> extract_nanosecond_fraction(
+  cudf::column_view const& column,
+  rmm::cuda_stream_view stream        = cudf::default_stream_value,
+  rmm::mr::device_memory_resource* mr = rmm::mr::get_current_device_resource());
+
 /**
  * @copydoc cudf::last_day_of_month(cudf::column_view const&, rmm::mr::device_memory_resource *)
  *

cpp/src/datetime/datetime_ops.cu

@@ -76,9 +76,14 @@ struct extract_component_operator {
 
     if (time_since_midnight.count() < 0) { time_since_midnight += days(1); }
 
-    auto hrs_  = duration_cast<hours>(time_since_midnight);
-    auto mins_ = duration_cast<minutes>(time_since_midnight - hrs_);
-    auto secs_ = duration_cast<seconds>(time_since_midnight - hrs_ - mins_);
+    auto hrs_       = duration_cast<hours>(time_since_midnight);
+    auto mins_      = duration_cast<minutes>(time_since_midnight - hrs_);
+    auto secs_      = duration_cast<seconds>(time_since_midnight - hrs_ - mins_);
+    auto millisecs_ = duration_cast<milliseconds>(time_since_midnight - hrs_ - mins_ - secs_);
+    auto microsecs_ =
+      duration_cast<microseconds>(time_since_midnight - hrs_ - mins_ - secs_ - millisecs_);
+    auto nanosecs_ = duration_cast<nanoseconds>(time_since_midnight - hrs_ - mins_ - secs_ -
+                                                millisecs_ - microsecs_);
 
     switch (Component) {
       case datetime_component::YEAR:
@@ -92,6 +97,9 @@ struct extract_component_operator {
       case datetime_component::HOUR: return hrs_.count();
       case datetime_component::MINUTE: return mins_.count();
       case datetime_component::SECOND: return secs_.count();
+      case datetime_component::MILLISECOND: return millisecs_.count();
+      case datetime_component::MICROSECOND: return microsecs_.count();
+      case datetime_component::NANOSECOND: return nanosecs_.count();
       default: return 0;
     }
   }
@@ -495,6 +503,33 @@ std::unique_ptr<column> extract_second(column_view const& column,
     cudf::type_id::INT16>(column, stream, mr);
 }
 
+std::unique_ptr<column> extract_millisecond_fraction(column_view const& column,
+                                                     rmm::cuda_stream_view stream,
+                                                     rmm::mr::device_memory_resource* mr)
+{
+  return detail::apply_datetime_op<
+    detail::extract_component_operator<detail::datetime_component::MILLISECOND>,
+    cudf::type_id::INT16>(column, stream, mr);
+}
+
+std::unique_ptr<column> extract_microsecond_fraction(column_view const& column,
+                                                     rmm::cuda_stream_view stream,
+                                                     rmm::mr::device_memory_resource* mr)
+{
+  return detail::apply_datetime_op<
+    detail::extract_component_operator<detail::datetime_component::MICROSECOND>,
+    cudf::type_id::INT16>(column, stream, mr);
+}
+
+std::unique_ptr<column> extract_nanosecond_fraction(column_view const& column,
+                                                    rmm::cuda_stream_view stream,
+                                                    rmm::mr::device_memory_resource* mr)
+{
+  return detail::apply_datetime_op<
+    detail::extract_component_operator<detail::datetime_component::NANOSECOND>,
+    cudf::type_id::INT16>(column, stream, mr);
+}
+
 std::unique_ptr<column> last_day_of_month(column_view const& column,
                                           rmm::cuda_stream_view stream,
                                           rmm::mr::device_memory_resource* mr)
@@ -607,6 +642,27 @@ std::unique_ptr<column> extract_second(column_view const& column,
   return detail::extract_second(column, cudf::default_stream_value, mr);
 }
 
+std::unique_ptr<column> extract_millisecond_fraction(column_view const& column,
+                                                     rmm::mr::device_memory_resource* mr)
+{
+  CUDF_FUNC_RANGE();
+  return detail::extract_millisecond_fraction(column, cudf::default_stream_value, mr);
+}
+
+std::unique_ptr<column> extract_microsecond_fraction(column_view const& column,
+                                                     rmm::mr::device_memory_resource* mr)
+{
+  CUDF_FUNC_RANGE();
+  return detail::extract_microsecond_fraction(column, cudf::default_stream_value, mr);
+}
+
+std::unique_ptr<column> extract_nanosecond_fraction(column_view const& column,
+                                                    rmm::mr::device_memory_resource* mr)
+{
+  CUDF_FUNC_RANGE();
+  return detail::extract_nanosecond_fraction(column, cudf::default_stream_value, mr);
+}
+
 std::unique_ptr<column> last_day_of_month(column_view const& column,
                                           rmm::mr::device_memory_resource* mr)
 {

cpp/tests/datetime/datetime_ops_test.cpp

@@ -60,6 +60,9 @@ TYPED_TEST(NonTimestampTest, TestThrowsOnNonTimestamp)
   EXPECT_THROW(extract_hour(col), cudf::logic_error);
   EXPECT_THROW(extract_minute(col), cudf::logic_error);
   EXPECT_THROW(extract_second(col), cudf::logic_error);
+  EXPECT_THROW(extract_millisecond_fraction(col), cudf::logic_error);
+  EXPECT_THROW(extract_microsecond_fraction(col), cudf::logic_error);
+  EXPECT_THROW(extract_nanosecond_fraction(col), cudf::logic_error);
   EXPECT_THROW(last_day_of_month(col), cudf::logic_error);
   EXPECT_THROW(day_of_year(col), cudf::logic_error);
   EXPECT_THROW(add_calendrical_months(
@@ -97,54 +100,102 @@ TEST_F(BasicDatetimeOpsTest, TestExtractingDatetimeComponents)
       1674631932929   // 2023-01-25 07:32:12.929 GMT
     };
 
+  auto timestamps_ns =
+    cudf::test::fixed_width_column_wrapper<cudf::timestamp_ns, cudf::timestamp_ns::rep>{
+      -23324234,  // 1969-12-31 23:59:59.976675766 GMT
+      23432424,   // 1970-01-01 00:00:00.023432424 GMT
+      987234623   // 1970-01-01 00:00:00.987234623 GMT
+    };
+
   CUDF_TEST_EXPECT_COLUMNS_EQUAL(*extract_year(timestamps_D),
                                  fixed_width_column_wrapper<int16_t>{1965, 2018, 2023});
   CUDF_TEST_EXPECT_COLUMNS_EQUAL(*extract_year(timestamps_s),
                                  fixed_width_column_wrapper<int16_t>{1965, 2018, 2023});
   CUDF_TEST_EXPECT_COLUMNS_EQUAL(*extract_year(timestamps_ms),
                                  fixed_width_column_wrapper<int16_t>{1965, 2018, 2023});
+  CUDF_TEST_EXPECT_COLUMNS_EQUAL(*extract_year(timestamps_ns),
+                                 fixed_width_column_wrapper<int16_t>{1969, 1970, 1970});
 
   CUDF_TEST_EXPECT_COLUMNS_EQUAL(*extract_month(timestamps_D),
                                  fixed_width_column_wrapper<int16_t>{10, 7, 1});
   CUDF_TEST_EXPECT_COLUMNS_EQUAL(*extract_month(timestamps_s),
                                  fixed_width_column_wrapper<int16_t>{10, 7, 1});
   CUDF_TEST_EXPECT_COLUMNS_EQUAL(*extract_month(timestamps_ms),
                                  fixed_width_column_wrapper<int16_t>{10, 7, 1});
+  CUDF_TEST_EXPECT_COLUMNS_EQUAL(*extract_month(timestamps_ns),
+                                 fixed_width_column_wrapper<int16_t>{12, 1, 1});
 
   CUDF_TEST_EXPECT_COLUMNS_EQUAL(*extract_day(timestamps_D),
                                  fixed_width_column_wrapper<int16_t>{26, 4, 25});
   CUDF_TEST_EXPECT_COLUMNS_EQUAL(*extract_day(timestamps_s),
                                  fixed_width_column_wrapper<int16_t>{26, 4, 25});
   CUDF_TEST_EXPECT_COLUMNS_EQUAL(*extract_day(timestamps_ms),
                                  fixed_width_column_wrapper<int16_t>{26, 4, 25});
+  CUDF_TEST_EXPECT_COLUMNS_EQUAL(*extract_day(timestamps_ns),
+                                 fixed_width_column_wrapper<int16_t>{31, 1, 1});
 
   CUDF_TEST_EXPECT_COLUMNS_EQUAL(*extract_weekday(timestamps_D),
                                  fixed_width_column_wrapper<int16_t>{2, 3, 3});
   CUDF_TEST_EXPECT_COLUMNS_EQUAL(*extract_weekday(timestamps_s),
                                  fixed_width_column_wrapper<int16_t>{2, 3, 3});
   CUDF_TEST_EXPECT_COLUMNS_EQUAL(*extract_weekday(timestamps_ms),
                                  fixed_width_column_wrapper<int16_t>{2, 3, 3});
+  CUDF_TEST_EXPECT_COLUMNS_EQUAL(*extract_weekday(timestamps_ms),
+                                 fixed_width_column_wrapper<int16_t>{2, 3, 3});
 
   CUDF_TEST_EXPECT_COLUMNS_EQUAL(*extract_hour(timestamps_D),
                                  fixed_width_column_wrapper<int16_t>{0, 0, 0});
   CUDF_TEST_EXPECT_COLUMNS_EQUAL(*extract_hour(timestamps_s),
                                  fixed_width_column_wrapper<int16_t>{14, 12, 7});
   CUDF_TEST_EXPECT_COLUMNS_EQUAL(*extract_hour(timestamps_ms),
                                  fixed_width_column_wrapper<int16_t>{14, 12, 7});
+  CUDF_TEST_EXPECT_COLUMNS_EQUAL(*extract_hour(timestamps_ns),
+                                 fixed_width_column_wrapper<int16_t>{23, 0, 0});
 
   CUDF_TEST_EXPECT_COLUMNS_EQUAL(*extract_minute(timestamps_D),
                                  fixed_width_column_wrapper<int16_t>{0, 0, 0});
   CUDF_TEST_EXPECT_COLUMNS_EQUAL(*extract_minute(timestamps_s),
                                  fixed_width_column_wrapper<int16_t>{1, 0, 32});
   CUDF_TEST_EXPECT_COLUMNS_EQUAL(*extract_minute(timestamps_ms),
                                  fixed_width_column_wrapper<int16_t>{1, 0, 32});
+  CUDF_TEST_EXPECT_COLUMNS_EQUAL(*extract_minute(timestamps_ns),
+                                 fixed_width_column_wrapper<int16_t>{59, 0, 0});
 
   CUDF_TEST_EXPECT_COLUMNS_EQUAL(*extract_second(timestamps_D),
                                  fixed_width_column_wrapper<int16_t>{0, 0, 0});
   CUDF_TEST_EXPECT_COLUMNS_EQUAL(*extract_second(timestamps_s),
                                  fixed_width_column_wrapper<int16_t>{12, 0, 12});
   CUDF_TEST_EXPECT_COLUMNS_EQUAL(*extract_second(timestamps_ms),
                                  fixed_width_column_wrapper<int16_t>{12, 0, 12});
+  CUDF_TEST_EXPECT_COLUMNS_EQUAL(*extract_minute(timestamps_ns),
+                                 fixed_width_column_wrapper<int16_t>{59, 0, 0});
+
+  CUDF_TEST_EXPECT_COLUMNS_EQUAL(*extract_millisecond_fraction(timestamps_D),
+                                 fixed_width_column_wrapper<int16_t>{0, 0, 0});
+  CUDF_TEST_EXPECT_COLUMNS_EQUAL(*extract_millisecond_fraction(timestamps_s),
+                                 fixed_width_column_wrapper<int16_t>{0, 0, 0});
+  CUDF_TEST_EXPECT_COLUMNS_EQUAL(*extract_millisecond_fraction(timestamps_ms),
+                                 fixed_width_column_wrapper<int16_t>{762, 0, 929});
+  CUDF_TEST_EXPECT_COLUMNS_EQUAL(*extract_millisecond_fraction(timestamps_ns),
+                                 fixed_width_column_wrapper<int16_t>{976, 23, 987});
+
+  CUDF_TEST_EXPECT_COLUMNS_EQUAL(*extract_microsecond_fraction(timestamps_D),
+                                 fixed_width_column_wrapper<int16_t>{0, 0, 0});
+  CUDF_TEST_EXPECT_COLUMNS_EQUAL(*extract_microsecond_fraction(timestamps_s),
+                                 fixed_width_column_wrapper<int16_t>{0, 0, 0});
+  CUDF_TEST_EXPECT_COLUMNS_EQUAL(*extract_microsecond_fraction(timestamps_ms),
+                                 fixed_width_column_wrapper<int16_t>{0, 0, 0});
+  CUDF_TEST_EXPECT_COLUMNS_EQUAL(*extract_microsecond_fraction(timestamps_ns),
+                                 fixed_width_column_wrapper<int16_t>{675, 432, 234});
+
+  CUDF_TEST_EXPECT_COLUMNS_EQUAL(*extract_nanosecond_fraction(timestamps_D),
+                                 fixed_width_column_wrapper<int16_t>{0, 0, 0});
+  CUDF_TEST_EXPECT_COLUMNS_EQUAL(*extract_nanosecond_fraction(timestamps_s),
+                                 fixed_width_column_wrapper<int16_t>{0, 0, 0});
+  CUDF_TEST_EXPECT_COLUMNS_EQUAL(*extract_nanosecond_fraction(timestamps_ms),
+                                 fixed_width_column_wrapper<int16_t>{0, 0, 0});
+  CUDF_TEST_EXPECT_COLUMNS_EQUAL(*extract_nanosecond_fraction(timestamps_ns),
+                                 fixed_width_column_wrapper<int16_t>{766, 424, 623});
 }
 
 template <typename T>
@@ -175,6 +226,9 @@ TYPED_TEST(TypedDatetimeOpsTest, TestEmptyColumns)
   CUDF_TEST_EXPECT_COLUMNS_EQUAL(*extract_hour(timestamps), int16s);
   CUDF_TEST_EXPECT_COLUMNS_EQUAL(*extract_minute(timestamps), int16s);
   CUDF_TEST_EXPECT_COLUMNS_EQUAL(*extract_second(timestamps), int16s);
+  CUDF_TEST_EXPECT_COLUMNS_EQUAL(*extract_millisecond_fraction(timestamps), int16s);
+  CUDF_TEST_EXPECT_COLUMNS_EQUAL(*extract_microsecond_fraction(timestamps), int16s);
+  CUDF_TEST_EXPECT_COLUMNS_EQUAL(*extract_nanosecond_fraction(timestamps), int16s);
 }
 
 TYPED_TEST(TypedDatetimeOpsTest, TestExtractingGeneratedDatetimeComponents)

docs/cudf/source/api_docs/index_objects.rst

@@ -262,6 +262,9 @@ Time/date components
    DatetimeIndex.hour
    DatetimeIndex.minute
    DatetimeIndex.second
+   DatetimeIndex.millisecond
+   DatetimeIndex.microsecond
+   DatetimeIndex.nanosecond
    DatetimeIndex.dayofweek
    DatetimeIndex.dayofyear
    DatetimeIndex.day_of_year

docs/cudf/source/api_docs/series.rst

@@ -266,8 +266,11 @@ Datetime properties
    days_in_month
    day_of_year
    hour
+   microsecond
+   millisecond
    minute
    month
+   nanosecond
    second
    weekday
    year

python/cudf/cudf/_lib/cpp/datetime.pxd

@@ -15,6 +15,15 @@ cdef extern from "cudf/datetime.hpp" namespace "cudf::datetime" nogil:
     cdef unique_ptr[column] extract_hour(const column_view& column) except +
     cdef unique_ptr[column] extract_minute(const column_view& column) except +
     cdef unique_ptr[column] extract_second(const column_view& column) except +
+    cdef unique_ptr[column] extract_millisecond_fraction(
+        const column_view& column
+    ) except +
+    cdef unique_ptr[column] extract_microsecond_fraction(
+        const column_view& column
+    ) except +
+    cdef unique_ptr[column] extract_nanosecond_fraction(
+        const column_view& column
+    ) except +
 
     ctypedef enum rounding_frequency "cudf::datetime::rounding_frequency":
         DAY "cudf::datetime::rounding_frequency::DAY"

python/cudf/cudf/_lib/datetime.pyx

@@ -49,6 +49,18 @@ def extract_datetime_component(Column col, object field):
             c_result = move(libcudf_datetime.extract_minute(col_view))
         elif field == "second":
             c_result = move(libcudf_datetime.extract_second(col_view))
+        elif field == "milli_second":
+            c_result = move(
+                libcudf_datetime.extract_millisecond_fraction(col_view)
+            )
+        elif field == "micro_second":
+            c_result = move(
+                libcudf_datetime.extract_microsecond_fraction(col_view)
+            )
+        elif field == "nano_second":
+            c_result = move(
+                libcudf_datetime.extract_nanosecond_fraction(col_view)
+            )
         elif field == "day_of_year":
             c_result = move(libcudf_datetime.day_of_year(col_view))
         else: