feat(spanner): convert ReadOptions/PartitionOptions to Options (#8448)

Add an `Options opts = {}` argument to `Read()`, `PartitionRead()`, and
`PartitionQuery()`, and relegate their `ReadOptions` and `PartitionOptions`
overloads to the "backwards compatibility" section.  The new `Options`
overloads also begin an `OptionsSpan`.

Add `ReadOptions`/`PartitionOptions`-to/from-`Options` conversion functions
to facilitate those compatibility interfaces, and add round-trip tests.

This required adding new Spanner-specific options `ReadIndexNameOption`,
`ReadRowLimitOption`, `PartitionSizeOption`, and `PartitionsMaximumOption`.

Update the samples to use the preferred `Options` overloads.

Part of #7690.

Author: devbww

google/cloud/spanner/CMakeLists.txt

@@ -167,6 +167,7 @@ add_library(
     query_options.h
     query_partition.cc
     query_partition.h
+    read_options.cc
     read_options.h
     read_partition.cc
     read_partition.h

google/cloud/spanner/client.cc

@@ -45,56 +45,57 @@ absl::optional<typename OptionType::Type> OptOpt(Options const& opts) {
 }  // namespace
 
 RowStream Client::Read(std::string table, KeySet keys,
-                       std::vector<std::string> columns,
-                       ReadOptions read_options) {
+                       std::vector<std::string> columns, Options opts) {
+  internal::OptionsSpan span(internal::MergeOptions(std::move(opts), opts_));
   return conn_->Read({spanner_internal::MakeSingleUseTransaction(
                           Transaction::ReadOnlyOptions()),
                       std::move(table),
                       std::move(keys),
                       std::move(columns),
-                      std::move(read_options),
+                      ToReadOptions(internal::CurrentOptions()),
                       {}});
 }
 
 RowStream Client::Read(Transaction::SingleUseOptions transaction_options,
                        std::string table, KeySet keys,
-                       std::vector<std::string> columns,
-                       ReadOptions read_options) {
+                       std::vector<std::string> columns, Options opts) {
+  internal::OptionsSpan span(internal::MergeOptions(std::move(opts), opts_));
   return conn_->Read({spanner_internal::MakeSingleUseTransaction(
                           std::move(transaction_options)),
                       std::move(table),
                       std::move(keys),
                       std::move(columns),
-                      std::move(read_options),
+                      ToReadOptions(internal::CurrentOptions()),
                       {}});
 }
 
 RowStream Client::Read(Transaction transaction, std::string table, KeySet keys,
-                       std::vector<std::string> columns,
-                       ReadOptions read_options) {
+                       std::vector<std::string> columns, Options opts) {
+  internal::OptionsSpan span(internal::MergeOptions(std::move(opts), opts_));
   return conn_->Read({std::move(transaction),
                       std::move(table),
                       std::move(keys),
                       std::move(columns),
-                      std::move(read_options),
+                      ToReadOptions(internal::CurrentOptions()),
                       {}});
 }
 
-RowStream Client::Read(ReadPartition const& read_partition) {
+RowStream Client::Read(ReadPartition const& read_partition, Options opts) {
+  internal::OptionsSpan span(internal::MergeOptions(std::move(opts), opts_));
   return conn_->Read(spanner_internal::MakeReadParams(read_partition));
 }
 
 StatusOr<std::vector<ReadPartition>> Client::PartitionRead(
     Transaction transaction, std::string table, KeySet keys,
-    std::vector<std::string> columns, ReadOptions read_options,
-    PartitionOptions const& partition_options) {
+    std::vector<std::string> columns, Options opts) {
+  internal::OptionsSpan span(internal::MergeOptions(std::move(opts), opts_));
   return conn_->PartitionRead({{std::move(transaction),
                                 std::move(table),
                                 std::move(keys),
                                 std::move(columns),
-                                std::move(read_options),
+                                ToReadOptions(internal::CurrentOptions()),
                                 {}},
-                               partition_options});
+                               ToPartitionOptions(internal::CurrentOptions())});
 }
 
 RowStream Client::ExecuteQuery(SqlStatement statement, Options opts) {
@@ -163,10 +164,11 @@ ProfileQueryResult Client::ProfileQuery(Transaction transaction,
 }
 
 StatusOr<std::vector<QueryPartition>> Client::PartitionQuery(
-    Transaction transaction, SqlStatement statement,
-    PartitionOptions const& partition_options) {
+    Transaction transaction, SqlStatement statement, Options opts) {
+  internal::OptionsSpan span(internal::MergeOptions(std::move(opts), opts_));
   return conn_->PartitionQuery(
-      {std::move(transaction), std::move(statement), partition_options});
+      {std::move(transaction), std::move(statement),
+       ToPartitionOptions(internal::CurrentOptions())});
 }
 
 StatusOr<DmlResult> Client::ExecuteDml(Transaction transaction,

google/cloud/spanner/client.h

@@ -181,7 +181,7 @@ class Client {
    *     not exist in the database; `Read` yields nothing for nonexistent rows.
    * @param columns The columns of `table` to be returned for each row matching
    *     this request.
-   * @param read_options `ReadOptions` used for this request.
+   * @param opts `Options` used for this request.
    *
    * @par Example
    * @snippet samples.cc read-data
@@ -190,8 +190,7 @@ class Client {
    *     column value can exceed 10 MiB.
    */
   RowStream Read(std::string table, KeySet keys,
-                 std::vector<std::string> columns,
-                 ReadOptions read_options = {});
+                 std::vector<std::string> columns, Options opts = {});
 
   /**
    * @copydoc Read
@@ -201,33 +200,73 @@ class Client {
    */
   RowStream Read(Transaction::SingleUseOptions transaction_options,
                  std::string table, KeySet keys,
-                 std::vector<std::string> columns,
-                 ReadOptions read_options = {});
+                 std::vector<std::string> columns, Options opts = {});
 
   /**
    * @copydoc Read
    *
    * @param transaction Execute this read as part of an existing transaction.
    */
   RowStream Read(Transaction transaction, std::string table, KeySet keys,
-                 std::vector<std::string> columns,
-                 ReadOptions read_options = {});
+                 std::vector<std::string> columns, Options opts = {});
   //@}
 
+  /// @name Backwards compatibility for `ReadOptions`.
+  ///@{
+  RowStream Read(std::string table, KeySet keys,
+                 std::vector<std::string> columns,
+                 ReadOptions const& read_options) {
+    return Read(std::move(table), std::move(keys), std::move(columns),
+                ToOptions(read_options));
+  }
+  RowStream Read(std::string table, KeySet keys,
+                 std::vector<std::string> columns,
+                 std::initializer_list<internal::NonConstructible>) {
+    return Read(std::move(table), std::move(keys), std::move(columns));
+  }
+  RowStream Read(Transaction::SingleUseOptions transaction_options,
+                 std::string table, KeySet keys,
+                 std::vector<std::string> columns,
+                 ReadOptions const& read_options) {
+    return Read(std::move(transaction_options), std::move(table),
+                std::move(keys), std::move(columns), ToOptions(read_options));
+  }
+  RowStream Read(Transaction::SingleUseOptions transaction_options,
+                 std::string table, KeySet keys,
+                 std::vector<std::string> columns,
+                 std::initializer_list<internal::NonConstructible>) {
+    return Read(std::move(transaction_options), std::move(table),
+                std::move(keys), std::move(columns));
+  }
+  RowStream Read(Transaction transaction, std::string table, KeySet keys,
+                 std::vector<std::string> columns,
+                 ReadOptions const& read_options) {
+    return Read(std::move(transaction), std::move(table), std::move(keys),
+                std::move(columns), ToOptions(read_options));
+  }
+  RowStream Read(Transaction transaction, std::string table, KeySet keys,
+                 std::vector<std::string> columns,
+                 std::initializer_list<internal::NonConstructible>) {
+    return Read(std::move(transaction), std::move(table), std::move(keys),
+                std::move(columns));
+  }
+  ///@}
+
   /**
    * Reads rows from a subset of rows in a database. Requires a prior call
    * to `PartitionRead` to obtain the partition information; see the
    * documentation of that method for full details.
    *
    * @param partition A `ReadPartition`, obtained by calling `PartitionRead`.
+   * @param opts `Options` used for this request.
    *
    * @note No individual row in the `ReadResult` can exceed 100 MiB, and no
    *     column value can exceed 10 MiB.
    *
    * @par Example
    * @snippet samples.cc read-read-partition
    */
-  RowStream Read(ReadPartition const& partition);
+  RowStream Read(ReadPartition const& partition, Options opts = {});
 
   /**
    * Creates a set of partitions that can be used to execute a read
@@ -252,8 +291,7 @@ class Client {
    *     not exist in the database; `Read` yields nothing for nonexistent rows.
    * @param columns The columns of `table` to be returned for each row matching
    *     this request.
-   * @param read_options `ReadOptions` used for this request.
-   * @param partition_options `PartitionOptions` used for this request.
+   * @param opts `Options` used for this request.
    *
    * @return A `StatusOr` containing a vector of `ReadPartition` or error
    *     status on failure.
@@ -263,8 +301,27 @@ class Client {
    */
   StatusOr<std::vector<ReadPartition>> PartitionRead(
       Transaction transaction, std::string table, KeySet keys,
-      std::vector<std::string> columns, ReadOptions read_options = {},
-      PartitionOptions const& partition_options = PartitionOptions{});
+      std::vector<std::string> columns, Options opts = {});
+
+  /// @name Backwards compatibility for `ReadOptions` and `PartitionOptions`.
+  ///@{
+  StatusOr<std::vector<ReadPartition>> PartitionRead(
+      Transaction transaction, std::string table, KeySet keys,
+      std::vector<std::string> columns, ReadOptions const& read_options,
+      PartitionOptions const& partition_options) {
+    return PartitionRead(std::move(transaction), std::move(table),
+                         std::move(keys), std::move(columns),
+                         internal::MergeOptions(ToOptions(read_options),
+                                                ToOptions(partition_options)));
+  }
+  StatusOr<std::vector<ReadPartition>> PartitionRead(
+      Transaction transaction, std::string table, KeySet keys,
+      std::vector<std::string> columns,
+      std::initializer_list<internal::NonConstructible>) {
+    return PartitionRead(std::move(transaction), std::move(table),
+                         std::move(keys), std::move(columns));
+  }
+  ///@}
 
   //@{
   /**
@@ -474,7 +531,7 @@ class Client {
    * @param transaction The transaction to execute the operation in.
    *     **Must** be a read-only snapshot transaction.
    * @param statement The SQL statement to execute.
-   * @param partition_options `PartitionOptions` used for this request.
+   * @param opts `Options` used for this request.
    *
    * @return A `StatusOr` containing a vector of `QueryPartition`s or error
    *     status on failure.
@@ -484,7 +541,22 @@ class Client {
    */
   StatusOr<std::vector<QueryPartition>> PartitionQuery(
       Transaction transaction, SqlStatement statement,
-      PartitionOptions const& partition_options = PartitionOptions{});
+      Options opts = Options{});
+
+  /// @name Backwards compatibility for `PartitionOptions`.
+  ///@{
+  StatusOr<std::vector<QueryPartition>> PartitionQuery(
+      Transaction transaction, SqlStatement statement,
+      PartitionOptions const& partition_options) {
+    return PartitionQuery(std::move(transaction), std::move(statement),
+                          ToOptions(partition_options));
+  }
+  StatusOr<std::vector<QueryPartition>> PartitionQuery(
+      Transaction transaction, SqlStatement statement,
+      std::initializer_list<internal::NonConstructible>) {
+    return PartitionQuery(std::move(transaction), std::move(statement));
+  }
+  ///@}
 
   /**
    * Executes a SQL DML statement.

google/cloud/spanner/google_cloud_cpp_spanner.bzl

@@ -172,6 +172,7 @@ google_cloud_cpp_spanner_srcs = [
     "partition_options.cc",
     "query_options.cc",
     "query_partition.cc",
+    "read_options.cc",
     "read_partition.cc",
     "results.cc",
     "row.cc",

google/cloud/spanner/internal/connection_impl.cc

@@ -325,13 +325,13 @@ class StreamingPartitionedDmlResult {
 
 std::shared_ptr<spanner::RetryPolicy> const&
 ConnectionImpl::RetryPolicyPrototype() const {
-  // TODO(#7690): Base this on internal::CurrentOptions().
+  // TODO(#4528) TODO(#7690): Base this on internal::CurrentOptions().
   return opts_.get<spanner::SpannerRetryPolicyOption>();
 }
 
 std::shared_ptr<spanner::BackoffPolicy> const&
 ConnectionImpl::BackoffPolicyPrototype() const {
-  // TODO(#7690): Base this on internal::CurrentOptions().
+  // TODO(#4528) TODO(#7690): Base this on internal::CurrentOptions().
   return opts_.get<spanner::SpannerBackoffPolicyOption>();
 }
 

google/cloud/spanner/options.h

@@ -186,6 +186,48 @@ struct RequestTagOption {
   using Type = std::string;
 };
 
+/**
+ * Option for `google::cloud::Options` to set the name of an index on a
+ * database table. This index is used instead of the table primary key when
+ * interpreting the `KeySet` and sorting result rows.
+ */
+struct ReadIndexNameOption {
+  using Type = std::string;
+};
+
+/**
+ * Option for `google::cloud::Options` to set a limit on the number of rows
+ * to yield from `Client::Read()`. There is no limit when the option is unset,
+ * or when it is set to 0.
+ */
+struct ReadRowLimitOption {
+  using Type = std::int64_t;
+};
+
+/**
+ * Option for `google::cloud::Options` to set the desired partition size to
+ * be generated by `Client::PartitionRead()` or `PartitionQuery()`.
+ *
+ * The default for this option is currently 1 GiB. This is only a hint. The
+ * actual size of each partition may be smaller or larger than this request.
+ */
+struct PartitionSizeOption {
+  using Type = std::int64_t;
+};
+
+/**
+ * Option for `google::cloud::Options` to set the desired maximum number of
+ * partitions to return from `Client::PartitionRead()` or `PartitionQuery()`.
+ *
+ * For example, this may be set to the number of workers available. The
+ * default for this option is currently 10,000. The maximum value is
+ * currently 200,000. This is only a hint. The actual number of partitions
+ * returned may be smaller or larger than this request.
+ */
+struct PartitionsMaximumOption {
+  using Type = std::int64_t;
+};
+
 /**
  * Option for `google::cloud::Options` to set a per-transaction tag.
  */

google/cloud/spanner/partition_options.cc

@@ -13,9 +13,38 @@
 // limitations under the License.
 
 #include "google/cloud/spanner/partition_options.h"
+#include "google/cloud/spanner/options.h"
 
 namespace google {
 namespace cloud {
+namespace spanner {
+GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
+
+Options ToOptions(PartitionOptions const& po) {
+  Options opts;
+  if (po.partition_size_bytes) {
+    opts.set<PartitionSizeOption>(*po.partition_size_bytes);
+  }
+  if (po.max_partitions) {
+    opts.set<PartitionsMaximumOption>(*po.max_partitions);
+  }
+  return opts;
+}
+
+PartitionOptions ToPartitionOptions(Options const& opts) {
+  PartitionOptions po;
+  if (opts.has<PartitionSizeOption>()) {
+    po.partition_size_bytes = opts.get<PartitionSizeOption>();
+  }
+  if (opts.has<PartitionsMaximumOption>()) {
+    po.max_partitions = opts.get<PartitionsMaximumOption>();
+  }
+  return po;
+}
+
+GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_END
+}  // namespace spanner
+
 namespace spanner_internal {
 GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN