feat: publish the Cloud Bigtable ExecuteQuery API (#26362)

google-cloud-bigtable-v2/.owlbot-manifest.json

@@ -20,6 +20,7 @@
  "lib/google/bigtable/v2/feature_flags_pb.rb",
  "lib/google/bigtable/v2/request_stats_pb.rb",
  "lib/google/bigtable/v2/response_params_pb.rb",
+ "lib/google/bigtable/v2/types_pb.rb",
  "lib/google/cloud/bigtable/v2.rb",
  "lib/google/cloud/bigtable/v2/bigtable.rb",
  "lib/google/cloud/bigtable/v2/bigtable/client.rb",
@@ -37,13 +38,16 @@
  "proto_docs/google/bigtable/v2/feature_flags.rb",
  "proto_docs/google/bigtable/v2/request_stats.rb",
  "proto_docs/google/bigtable/v2/response_params.rb",
+ "proto_docs/google/bigtable/v2/types.rb",
  "proto_docs/google/protobuf/any.rb",
  "proto_docs/google/protobuf/duration.rb",
  "proto_docs/google/protobuf/timestamp.rb",
  "proto_docs/google/protobuf/wrappers.rb",
  "proto_docs/google/rpc/status.rb",
+ "proto_docs/google/type/date.rb",
  "snippets/Gemfile",
  "snippets/bigtable/check_and_mutate_row.rb",
+ "snippets/bigtable/execute_query.rb",
  "snippets/bigtable/generate_initial_change_stream_partitions.rb",
  "snippets/bigtable/mutate_row.rb",
  "snippets/bigtable/mutate_rows.rb",

google-cloud-bigtable-v2/gapic_metadata.json

@@ -54,6 +54,11 @@
  "methods": [
  "read_change_stream"
  ]
+ },
+ "ExecuteQuery": {
+ "methods": [
+ "execute_query"
+ ]
  }
  }
  }

google-cloud-bigtable-v2/lib/google/cloud/bigtable/v2/bigtable/client.rb

@@ -1226,6 +1226,137 @@ def read_change_stream request, options = nil
  raise ::Google::Cloud::Error.from_error(e)
  end
 
+ ##
+ # Executes a BTQL query against a particular Cloud Bigtable instance.
+ #
+ # @overload execute_query(request, options = nil)
+ # Pass arguments to `execute_query` via a request object, either of type
+ # {::Google::Cloud::Bigtable::V2::ExecuteQueryRequest} or an equivalent Hash.
+ #
+ # @param request [::Google::Cloud::Bigtable::V2::ExecuteQueryRequest, ::Hash]
+ # A request object representing the call parameters. Required. To specify no
+ # parameters, or to keep all the default parameter values, pass an empty Hash.
+ # @param options [::Gapic::CallOptions, ::Hash]
+ # Overrides the default settings for this call, e.g, timeout, retries, etc. Optional.
+ #
+ # @overload execute_query(instance_name: nil, app_profile_id: nil, query: nil, proto_format: nil, resume_token: nil, params: nil)
+ # Pass arguments to `execute_query` via keyword arguments. Note that at
+ # least one keyword argument is required. To specify no parameters, or to keep all
+ # the default parameter values, pass an empty Hash as a request object (see above).
+ #
+ # @param instance_name [::String]
+ # Required. The unique name of the instance against which the query should be
+ # executed.
+ # Values are of the form `projects/<project>/instances/<instance>`
+ # @param app_profile_id [::String]
+ # Optional. This value specifies routing for replication. If not specified,
+ # the `default` application profile will be used.
+ # @param query [::String]
+ # Required. The query string.
+ # @param proto_format [::Google::Cloud::Bigtable::V2::ProtoFormat, ::Hash]
+ # Protocol buffer format as described by ProtoSchema and ProtoRows
+ # messages.
+ # @param resume_token [::String]
+ # Optional. If this request is resuming a previously interrupted query
+ # execution, `resume_token` should be copied from the last
+ # PartialResultSet yielded before the interruption. Doing this
+ # enables the query execution to resume where the last one left
+ # off.
+ # The rest of the request parameters must exactly match the
+ # request that yielded this token. Otherwise the request will fail.
+ # @param params [::Hash{::String => ::Google::Cloud::Bigtable::V2::Value, ::Hash}]
+ # Required. params contains string type keys and Bigtable type values that
+ # bind to placeholders in the query string. In query string, a parameter
+ # placeholder consists of the
+ # `@` character followed by the parameter name (for example, `@firstName`) in
+ # the query string.
+ #
+ # For example, if
+ # `params["firstName"] = bytes_value: "foo" type {bytes_type {}}`
+ # then `@firstName` will be replaced with googlesql bytes value "foo" in the
+ # query string during query evaluation.
+ #
+ # In case of Value.kind is not set, it will be set to corresponding null
+ # value in googlesql.
+ # `params["firstName"] = type {string_type {}}`
+ # then `@firstName` will be replaced with googlesql null string.
+ #
+ # Value.type should always be set and no inference of type will be made from
+ # Value.kind. If Value.type is not set, we will return INVALID_ARGUMENT
+ # error.
+ #
+ # @yield [response, operation] Access the result along with the RPC operation
+ # @yieldparam response [::Enumerable<::Google::Cloud::Bigtable::V2::ExecuteQueryResponse>]
+ # @yieldparam operation [::GRPC::ActiveCall::Operation]
+ #
+ # @return [::Enumerable<::Google::Cloud::Bigtable::V2::ExecuteQueryResponse>]
+ #
+ # @raise [::Google::Cloud::Error] if the RPC is aborted.
+ #
+ # @example Basic example
+ # require "google/cloud/bigtable/v2"
+ #
+ # # Create a client object. The client can be reused for multiple calls.
+ # client = Google::Cloud::Bigtable::V2::Bigtable::Client.new
+ #
+ # # Create a request. To set request fields, pass in keyword arguments.
+ # request = Google::Cloud::Bigtable::V2::ExecuteQueryRequest.new
+ #
+ # # Call the execute_query method to start streaming.
+ # output = client.execute_query request
+ #
+ # # The returned object is a streamed enumerable yielding elements of type
+ # # ::Google::Cloud::Bigtable::V2::ExecuteQueryResponse
+ # output.each do |current_response|
+ # p current_response
+ # end
+ #
+ def execute_query request, options = nil
+ raise ::ArgumentError, "request must be provided" if request.nil?
+
+ request = ::Gapic::Protobuf.coerce request, to: ::Google::Cloud::Bigtable::V2::ExecuteQueryRequest
+
+ # Converts hash and nil to an options object
+ options = ::Gapic::CallOptions.new(**options.to_h) if options.respond_to? :to_h
+
+ # Customize the options with defaults
+ metadata = @config.rpcs.execute_query.metadata.to_h
+
+ # Set x-goog-api-client, x-goog-user-project and x-goog-api-version headers
+ metadata[:"x-goog-api-client"] ||= ::Gapic::Headers.x_goog_api_client \
+ lib_name: @config.lib_name, lib_version: @config.lib_version,
+ gapic_version: ::Google::Cloud::Bigtable::V2::VERSION
+ metadata[:"x-goog-api-version"] = API_VERSION unless API_VERSION.empty?
+ metadata[:"x-goog-user-project"] = @quota_project_id if @quota_project_id
+
+ header_params = {}
+ if request.instance_name &&
+ %r{^projects/[^/]+/instances/[^/]+/?$}.match?(request.instance_name)
+ header_params["name"] = request.instance_name
+ end
+ if request.app_profile_id && !request.app_profile_id.empty?
+ header_params["app_profile_id"] = request.app_profile_id
+ end
+
+ request_params_header = URI.encode_www_form header_params
+ metadata[:"x-goog-request-params"] ||= request_params_header
+
+ options.apply_defaults timeout: @config.rpcs.execute_query.timeout,
+ metadata: metadata,
+ retry_policy: @config.rpcs.execute_query.retry_policy
+
+ options.apply_defaults timeout: @config.timeout,
+ metadata: @config.metadata,
+ retry_policy: @config.retry_policy
+
+ @bigtable_stub.call_rpc :execute_query, request, options: options do |response, operation|
+ yield response, operation if block_given?
+ return response
+ end
+ rescue ::GRPC::BadStatus => e
+ raise ::Google::Cloud::Error.from_error(e)
+ end
+
  ##
  # Configuration class for the Bigtable API.
  #
@@ -1424,6 +1555,11 @@ class Rpcs
  # @return [::Gapic::Config::Method]
  #
  attr_reader :read_change_stream
+ ##
+ # RPC-specific configuration for `execute_query`
+ # @return [::Gapic::Config::Method]
+ #
+ attr_reader :execute_query
 
  # @private
  def initialize parent_rpcs = nil
@@ -1445,6 +1581,8 @@ def initialize parent_rpcs = nil
  @generate_initial_change_stream_partitions = ::Gapic::Config::Method.new generate_initial_change_stream_partitions_config
  read_change_stream_config = parent_rpcs.read_change_stream if parent_rpcs.respond_to? :read_change_stream
  @read_change_stream = ::Gapic::Config::Method.new read_change_stream_config
+ execute_query_config = parent_rpcs.execute_query if parent_rpcs.respond_to? :execute_query
+ @execute_query = ::Gapic::Config::Method.new execute_query_config
 
  yield self if block_given?
  end