feat(bigtable): add support for Timestamp and Date (#15560)

* feat(bigtable): add support for Timestamp and Date

* chore: checkers

* chore: static cast to int

* chore: remove unused commit timestamp

* chore: compare timestamp protos directly

Author: diegomarquezp

google/cloud/bigtable/CMakeLists.txt

@@ -254,6 +254,8 @@ add_library(
     table_config.h
     table_resource.cc
     table_resource.h
+    timestamp.cc
+    timestamp.h
     value.cc
     value.h
     version.cc
@@ -495,6 +497,7 @@ if (BUILD_TESTING)
         table_test.cc
         testing/cleanup_stale_resources_test.cc
         testing/random_names_test.cc
+        timestamp_test.cc
         value_test.cc
         wait_for_consistency_test.cc)
 

google/cloud/bigtable/bigtable_client_unit_tests.bzl

@@ -95,6 +95,7 @@ bigtable_client_unit_tests = [
     "table_test.cc",
     "testing/cleanup_stale_resources_test.cc",
     "testing/random_names_test.cc",
+    "timestamp_test.cc",
     "value_test.cc",
     "wait_for_consistency_test.cc",
 ]

google/cloud/bigtable/google_cloud_cpp_bigtable.bzl

@@ -132,6 +132,7 @@ google_cloud_cpp_bigtable_hdrs = [
     "table_admin.h",
     "table_config.h",
     "table_resource.h",
+    "timestamp.h",
     "value.h",
     "version.h",
     "version_info.h",
@@ -226,6 +227,7 @@ google_cloud_cpp_bigtable_srcs = [
     "table_admin.cc",
     "table_config.cc",
     "table_resource.cc",
+    "timestamp.cc",
     "value.cc",
     "version.cc",
     "wait_for_consistency.cc",

google/cloud/bigtable/timestamp.cc

@@ -0,0 +1,121 @@
+// Copyright 2025 Google LLC
+//
+// 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
+//
+//     https://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 "google/cloud/bigtable/timestamp.h"
+#include "google/cloud/internal/make_status.h"
+#include "google/cloud/status.h"
+#include <google/protobuf/util/time_util.h>
+#include <string>
+
+namespace google {
+namespace cloud {
+namespace bigtable {
+GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
+
+namespace {
+
+Status OutOfRange(std::string message, internal::ErrorInfoBuilder info) {
+  return internal::OutOfRangeError(std::move(message), std::move(info));
+}
+
+Status PositiveOverflow(std::string const& type) {
+  return OutOfRange(type + " positive overflow", GCP_ERROR_INFO());
+}
+
+Status NegativeOverflow(std::string const& type) {
+  return OutOfRange(type + " negative overflow", GCP_ERROR_INFO());
+}
+
+}  // namespace
+
+StatusOr<protobuf::Timestamp> Timestamp::ConvertTo(
+    protobuf::Timestamp const&) const {
+  auto constexpr kDestType = "google::protobuf::Timestamp";
+  auto const s = absl::ToUnixSeconds(t_);
+  if (s > google::protobuf::util::TimeUtil::kTimestampMaxSeconds)
+    return PositiveOverflow(kDestType);
+  if (s < google::protobuf::util::TimeUtil::kTimestampMinSeconds)
+    return NegativeOverflow(kDestType);
+  auto const ns = absl::ToInt64Nanoseconds(t_ - absl::FromUnixSeconds(s));
+  google::protobuf::Timestamp proto;
+  proto.set_seconds(s);
+  proto.set_nanos(static_cast<std::int32_t>(ns));
+  return proto;
+}
+
+StatusOr<std::int64_t> Timestamp::ToRatio(std::int64_t min, std::int64_t max,
+                                          std::int64_t num,
+                                          std::int64_t den) const {
+  auto constexpr kDestType = "std::chrono::time_point";
+  auto const period = absl::Seconds(num) / den;
+  auto const duration = absl::Floor(t_ - absl::UnixEpoch(), period);
+  if (duration > max * period) return PositiveOverflow(kDestType);
+  if (duration < min * period) return NegativeOverflow(kDestType);
+  return duration / period;
+}
+
+StatusOr<Timestamp> MakeTimestamp(absl::Time t) {
+  auto constexpr kDestType = "google::cloud::bigtable::Timestamp";
+  auto constexpr kMinTime = absl::FromUnixSeconds(
+      google::protobuf::util::TimeUtil::kTimestampMinSeconds);
+  auto constexpr kMaxTime = absl::FromUnixSeconds(
+      google::protobuf::util::TimeUtil::kTimestampMaxSeconds + 1);
+  if (t >= kMaxTime) return PositiveOverflow(kDestType);
+  if (t < kMinTime) return NegativeOverflow(kDestType);
+  return Timestamp(t);
+}
+
+StatusOr<Timestamp> MakeTimestamp(protobuf::Timestamp const& proto) {
+  return MakeTimestamp(absl::FromUnixSeconds(proto.seconds()) +
+                       absl::Nanoseconds(proto.nanos()));
+}
+
+std::ostream& operator<<(std::ostream& os, Timestamp ts) {
+  return os << bigtable_internal::TimestampToRFC3339(ts);
+}
+
+GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_END
+}  // namespace bigtable
+
+namespace bigtable_internal {
+GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
+
+namespace {
+
+// Timestamp objects are always formatted in UTC, and we always format them
+// with a trailing 'Z'. However, we're a bit more liberal in the UTC offsets we
+// accept, thus the use of '%Ez' in kParseSpec.
+auto constexpr kFormatSpec = "%E4Y-%m-%d%ET%H:%M:%E*SZ";
+auto constexpr kParseSpec = "%Y-%m-%d%ET%H:%M:%E*S%Ez";
+
+}  // namespace
+
+StatusOr<bigtable::Timestamp> TimestampFromRFC3339(std::string const& s) {
+  absl::Time t;
+  std::string err;
+  if (absl::ParseTime(kParseSpec, s, &t, &err)) {
+    return bigtable::MakeTimestamp(t);
+  }
+  return internal::InvalidArgumentError(s + ": " + err, GCP_ERROR_INFO());
+}
+
+std::string TimestampToRFC3339(bigtable::Timestamp ts) {
+  auto const t = ts.get<absl::Time>().value();  // Cannot fail.
+  return absl::FormatTime(kFormatSpec, t, absl::UTCTimeZone());
+}
+
+GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_END
+}  // namespace bigtable_internal
+}  // namespace cloud
+}  // namespace google

google/cloud/bigtable/timestamp.h

@@ -0,0 +1,203 @@
+// Copyright 2025 Google LLC
+//
+// 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
+//
+//     https://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 GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_BIGTABLE_TIMESTAMP_H
+#define GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_BIGTABLE_TIMESTAMP_H
+
+#include "google/cloud/bigtable/version.h"
+#include "google/cloud/status_or.h"
+#include "absl/time/time.h"
+#include <google/protobuf/timestamp.pb.h>
+#include <chrono>
+#include <cstdint>
+#include <limits>
+#include <ostream>
+#include <string>
+
+namespace google {
+namespace cloud {
+namespace bigtable {
+GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
+
+/**
+ * Convenience alias. `std::chrono::sys_time` since C++20.
+ */
+template <typename Duration>
+using sys_time = std::chrono::time_point<std::chrono::system_clock, Duration>;
+
+/**
+ * A representation of the Bigtable TIMESTAMP type: An instant in time.
+ *
+ * A `Timestamp` represents an absolute point in time (i.e., is independent of
+ * any time zone), with at least nanosecond precision, and with a range of
+ * 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z, inclusive.
+ *
+ * The `MakeTimestamp(src)` factory function(s) should be used to construct
+ * `Timestamp` values from standard representations of absolute time.
+ *
+ * A `Timestamp` can be converted back to a standard representation using
+ * `ts.get<T>()`.
+ *
+ * @see https://cloud.google.com/bigtable/docs/data-types#timestamp_type
+ */
+class Timestamp {
+ public:
+  /// Default construction yields 1970-01-01T00:00:00Z.
+  Timestamp() : Timestamp(absl::UnixEpoch()) {}
+
+  /// @name Regular value type, supporting copy, assign, move.
+  ///@{
+  Timestamp(Timestamp&&) = default;
+  Timestamp& operator=(Timestamp&&) = default;
+  Timestamp(Timestamp const&) = default;
+  Timestamp& operator=(Timestamp const&) = default;
+  ///@}
+
+  /// @name Relational operators
+  ///@{
+  friend bool operator==(Timestamp const& a, Timestamp const& b) {
+    return a.t_ == b.t_;
+  }
+  friend bool operator!=(Timestamp const& a, Timestamp const& b) {
+    return !(a == b);
+  }
+  friend bool operator<(Timestamp const& a, Timestamp const& b) {
+    return a.t_ < b.t_;
+  }
+  friend bool operator<=(Timestamp const& a, Timestamp const& b) {
+    return !(b < a);
+  }
+  friend bool operator>=(Timestamp const& a, Timestamp const& b) {
+    return !(a < b);
+  }
+  friend bool operator>(Timestamp const& a, Timestamp const& b) {
+    return b < a;
+  }
+  ///@}
+
+  /// @name Output streaming
+  friend std::ostream& operator<<(std::ostream& os, Timestamp ts);
+
+  /**
+   * Convert the `Timestamp` to the user-specified template type. Fails if
+   * `*this` cannot be represented as a `T`.
+   *
+   * Supported destination types are:
+   *   - `absl::Time` - Since `absl::Time` can represent all possible
+   *     `Timestamp` values, `get<absl::Time>()` never returns an error.
+   *   - `google::protobuf::Timestamp` - Never returns an error, but any
+   *     sub-nanosecond precision will be lost.
+   *   - `google::cloud::bigtable::sys_time<Duration>` - `Duration::rep` may
+   *     not be wider than `std::int64_t`, and `Duration::period` may be no
+   *     more precise than `std::nano`.
+   *
+   * @par Example
+   *
+   * @code
+   *  sys_time<std::chrono::nanoseconds> tp = ...;
+   *  Timestamp ts = MakeTimestamp(tp).value();
+   *  assert(tp == ts.get<sys_time<std::chrono::nanoseconds>>().value());
+   * @endcode
+   */
+  template <typename T>
+  StatusOr<T> get() const {
+    // All `ConvertTo()` overloads return a `StatusOr<T>` even when they
+    // cannot actually fail (e.g., when the destination type can represent
+    // all `Timestamp` values). See individual comments below.
+    return ConvertTo(T{});
+  }
+
+ private:
+  friend StatusOr<Timestamp> MakeTimestamp(absl::Time);
+
+  StatusOr<std::int64_t> ToRatio(std::int64_t min, std::int64_t max,
+                                 std::int64_t num, std::int64_t den) const;
+
+  // Conversion to a `std::chrono::time_point` on the system clock. May
+  // produce out-of-range errors, depending on the properties of `Duration`
+  // and the `std::chrono::system_clock` epoch.
+  template <typename Duration>
+  StatusOr<sys_time<Duration>> ConvertTo(sys_time<Duration> const&) const {
+    using Rep = typename Duration::rep;
+    using Period = typename Duration::period;
+    static_assert(std::ratio_greater_equal<Period, std::nano>::value,
+                  "Duration must be no more precise than std::nano");
+    auto count =
+        ToRatio(std::numeric_limits<Rep>::min(),
+                std::numeric_limits<Rep>::max(), Period::num, Period::den);
+    if (!count) return std::move(count).status();
+    auto const unix_epoch = std::chrono::time_point_cast<Duration>(
+        sys_time<Duration>::clock::from_time_t(0));
+    return unix_epoch + Duration(static_cast<Rep>(*count));
+  }
+
+  // Conversion to an `absl::Time`. Can never fail.
+  StatusOr<absl::Time> ConvertTo(absl::Time) const { return t_; }
+
+  // Conversion to a `google::protobuf::Timestamp`. Can never fail, but
+  // any sub-nanosecond precision will be lost.
+  StatusOr<protobuf::Timestamp> ConvertTo(protobuf::Timestamp const&) const;
+
+  explicit Timestamp(absl::Time t) : t_(t) {}
+
+  absl::Time t_;
+};
+
+/**
+ * Construct a `Timestamp` from an `absl::Time`. May produce out-of-range
+ * errors if the given time is beyond the range supported by `Timestamp` (see
+ * class comments above).
+ */
+StatusOr<Timestamp> MakeTimestamp(absl::Time);
+
+/**
+ * Construct a `Timestamp` from a `google::protobuf::Timestamp`. May produce
+ * out-of-range errors if the given protobuf is beyond the range supported by
+ * `Timestamp` (which a valid protobuf never will).
+ */
+StatusOr<Timestamp> MakeTimestamp(protobuf::Timestamp const&);
+
+/**
+ * Construct a `Timestamp` from a `std::chrono::time_point` on the system
+ * clock. May produce out-of-range errors, depending on the properties of
+ * `Duration` and the `std::chrono::system_clock` epoch. `Duration::rep` may
+ * not be wider than `std::int64_t`. Requires that `Duration::period` is no
+ * more precise than `std::nano`.
+ */
+template <typename Duration>
+StatusOr<Timestamp> MakeTimestamp(sys_time<Duration> const& tp) {
+  using Period = typename Duration::period;
+  static_assert(std::ratio_greater_equal<Period, std::nano>::value,
+                "Duration must be no more precise than std::nano");
+  auto const unix_epoch = std::chrono::time_point_cast<Duration>(
+      sys_time<Duration>::clock::from_time_t(0));
+  auto const period = absl::Seconds(Period::num) / Period::den;
+  auto const count = (tp - unix_epoch).count();
+  return MakeTimestamp(absl::UnixEpoch() + count * period);
+}
+
+GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_END
+}  // namespace bigtable
+
+namespace bigtable_internal {
+GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
+StatusOr<bigtable::Timestamp> TimestampFromRFC3339(std::string const&);
+std::string TimestampToRFC3339(bigtable::Timestamp);
+GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_END
+}  // namespace bigtable_internal
+
+}  // namespace cloud
+}  // namespace google
+
+#endif  // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_BIGTABLE_TIMESTAMP_H