results.h

// Copyright 2019 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_SPANNER_RESULTS_H
#define GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_SPANNER_RESULTS_H
 
#include "google/cloud/spanner/row.h"
#include "google/cloud/spanner/timestamp.h"
#include "google/cloud/spanner/version.h"
#include "google/cloud/optional.h"
#include "absl/types/optional.h"
#include <google/spanner/v1/spanner.pb.h>
#include <memory>
#include <string>
#include <unordered_map>
 
namespace google {
namespace cloud {
namespace spanner {
GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
 
/**
 * Defines the interface for `RowStream` implementations.
 *
 * The `RowStream` class represents a stream of `Rows` returned from
 * `spanner::Client::Read()` or `spanner::Client::ExecuteQuery()`. There are
 * different implementations depending the the RPC. Applications can also
 * mock this class when testing their code and mocking the `spanner::Client`
 * behavior.
 */
class ResultSourceInterface {
 public:
  virtual ~ResultSourceInterface() = default;
 
  /**
   * Returns the next row in the stream.
   *
   * @return if the stream is interrupted due to a failure the
   *   `StatusOr<spanner::Row>` contains the error.  The function returns a
   *   successful `StatusOr<>` with an empty `spanner::Row` to indicate
   *   end-of-stream.
   */
  virtual StatusOr<spanner::Row> NextRow() = 0;
 
  /**
   * Returns metadata about the result set, such as the field types and the
   * transaction id created by the request.
   *
   * @see https://cloud.google.com/spanner/docs/reference/rpc/google.spanner.v1#resultsetmetadata
   *     for more information.
   */
  virtual absl::optional<google::spanner::v1::ResultSetMetadata> Metadata() = 0;
 
  /**
   * Returns statistics about the result set, such as the number of rows, and
   * the query plan used to compute the results.
   *
   * @see https://cloud.google.com/spanner/docs/reference/rpc/google.spanner.v1#resultsetstats
   *     for more information.
   */
  virtual absl::optional<google::spanner::v1::ResultSetStats> Stats() const = 0;
};
 
/**
 * Contains a hierarchical representation of the operations the database server
 * performs in order to execute a particular SQL statement.
 * [Query Plan
 * proto](https://github.com/googleapis/googleapis/blob/master/google/spanner/v1/query_plan.proto)
 *
 * @par Example:
 * @snippet samples.cc analyze-query
 */
using ExecutionPlan = ::google::spanner::v1::QueryPlan;
 
/**
 * Represents the stream of `Rows` returned from `spanner::Client::Read()` or
 * `spanner::Client::ExecuteQuery()`.
 *
 * This is a range defined by the [Input Iterators][input-iterator] returned
 * from its `begin()` and `end()` members. Callers may directly iterate the
 * `RowStream` instance, which will return a sequence of `StatusOr<Row>`
 * objects.
 *
 * For convenience, callers may wrap instances in a `StreamOf<std::tuple<...>>`
 * object, which will automatically parse each `Row` into a `std::tuple` with
 * the specified types.
 *
 * [input-iterator]: https://en.cppreference.com/w/cpp/named_req/InputIterator
 */
class RowStream {
 public:
  RowStream() = default;
  explicit RowStream(std::unique_ptr<ResultSourceInterface> source)
      : source_(std::move(source)) {}
 
  // This class is movable but not copyable.
  RowStream(RowStream&&) = default;
  RowStream& operator=(RowStream&&) = default;
 
  /// Returns a `RowStreamIterator` defining the beginning of this range.
  RowStreamIterator begin() {
    return RowStreamIterator([this]() mutable { return source_->NextRow(); });
  }
 
  /// Returns a `RowStreamIterator` defining the end of this range.
  // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
  RowStreamIterator end() { return {}; }
 
  /// Returns the number of rows modified by a DML statement.
  std::int64_t RowsModified() const;
 
  /**
   * Retrieves the timestamp at which the read occurred.
   *
   * @note Only available if a read-only transaction was used.
   */
  absl::optional<Timestamp> ReadTimestamp() const;
 
 private:
  std::unique_ptr<ResultSourceInterface> source_;
};
 
/**
 * Represents the result of a data modifying operation using
 * `spanner::Client::ExecuteDml()`.
 *
 * This class encapsulates the result of a Cloud Spanner DML operation, i.e.,
 * `INSERT`, `UPDATE`, or `DELETE`.
 *
 * @note `ExecuteDmlResult` returns the number of rows modified.
 *
 * @par Example:
 * @snippet samples.cc execute-dml
 */
class DmlResult {
 public:
  DmlResult() = default;
  explicit DmlResult(std::unique_ptr<ResultSourceInterface> source)
      : source_(std::move(source)) {}
 
  // This class is movable but not copyable.
  DmlResult(DmlResult&&) = default;
  DmlResult& operator=(DmlResult&&) = default;
 
  /**
   * Returns the number of rows modified by the DML statement.
   *
   * @note Partitioned DML only provides a lower bound of the rows modified, all
   *     other DML statements provide an exact count.
   */
  std::int64_t RowsModified() const;
 
 private:
  std::unique_ptr<ResultSourceInterface> source_;
};
 
/**
 * Represents the stream of `Rows` and profile stats returned from
 * `spanner::Client::ProfileQuery()`.
 *
 * This is a range defined by the [Input Iterators][input-iterator] returned
 * from its `begin()` and `end()` members. Callers may directly iterate the
 * `ProfileQueryResult` instance, which will return a sequence of
 * `StatusOr<Row>` objects.
 *
 * For convenience, callers may wrap instances in a `StreamOf<std::tuple<...>>`
 * object, which will automatically parse each `Row` into a `std::tuple` with
 * the specified types.
 *
 * [input-iterator]: https://en.cppreference.com/w/cpp/named_req/InputIterator
 *
 * @par Example:
 * @snippet samples.cc profile-query
 */
class ProfileQueryResult {
 public:
  ProfileQueryResult() = default;
  explicit ProfileQueryResult(std::unique_ptr<ResultSourceInterface> source)
      : source_(std::move(source)) {}
 
  // This class is movable but not copyable.
  ProfileQueryResult(ProfileQueryResult&&) = default;
  ProfileQueryResult& operator=(ProfileQueryResult&&) = default;
 
  /// Returns a `RowStreamIterator` defining the beginning of this result set.
  RowStreamIterator begin() {
    return RowStreamIterator([this]() mutable { return source_->NextRow(); });
  }
 
  /// Returns a `RowStreamIterator` defining the end of this result set.
  // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
  RowStreamIterator end() { return {}; }
 
  /**
   * Retrieves the timestamp at which the read occurred.
   *
   * @note Only available if a read-only transaction was used.
   */
  absl::optional<Timestamp> ReadTimestamp() const;
 
  /**
   * Returns a collection of key value pair statistics for the SQL statement
   * execution.
   *
   * @note Only available when the statement is executed and all results have
   *     been read.
   */
  absl::optional<std::unordered_map<std::string, std::string>> ExecutionStats()
      const;
 
  /**
   * Returns the plan of execution for the SQL statement.
   */
  absl::optional<spanner::ExecutionPlan> ExecutionPlan() const;
 
 private:
  std::unique_ptr<ResultSourceInterface> source_;
};
 
/**
 * Represents the result and profile stats of a data modifying operation using
 * `spanner::Client::ProfileDml()`.
 *
 * This class encapsulates the result of a Cloud Spanner DML operation, i.e.,
 * `INSERT`, `UPDATE`, or `DELETE`.
 *
 * @note `ProfileDmlResult` returns the number of rows modified, execution
 *     statistics, and query plan.
 *
 * @par Example:
 * @snippet samples.cc profile-dml
 */
class ProfileDmlResult {
 public:
  ProfileDmlResult() = default;
  explicit ProfileDmlResult(std::unique_ptr<ResultSourceInterface> source)
      : source_(std::move(source)) {}
 
  // This class is movable but not copyable.
  ProfileDmlResult(ProfileDmlResult&&) = default;
  ProfileDmlResult& operator=(ProfileDmlResult&&) = default;
 
  /**
   * Returns the number of rows modified by the DML statement.
   *
   * @note Partitioned DML only provides a lower bound of the rows modified, all
   * other DML statements provide an exact count.
   */
  std::int64_t RowsModified() const;
 
  /**
   * Returns a collection of key value pair statistics for the SQL statement
   * execution.
   *
   * @note Only available when the SQL statement is executed.
   */
  absl::optional<std::unordered_map<std::string, std::string>> ExecutionStats()
      const;
 
  /**
   * Returns the plan of execution for the SQL statement.
   */
  absl::optional<spanner::ExecutionPlan> ExecutionPlan() const;
 
 private:
  std::unique_ptr<ResultSourceInterface> source_;
};
 
GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_END
}  // namespace spanner
 
namespace spanner_internal {
GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
 
/// @deprecated Prefer using `spanner::ResultSourceInterface` directly.
using ResultSourceInterface = spanner::ResultSourceInterface;
 
GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_END
}  // namespace spanner_internal
}  // namespace cloud
}  // namespace google
 
#endif  // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_SPANNER_RESULTS_H