google-cloud-bigquery 1.14.0 → 1.42.0

data/lib/google/cloud/bigquery/job.rb

@@ -74,8 +74,8 @@ module Google
         ##
         # The ID of the job.
         #
-        # @return [String] The ID must contain only letters (a-z, A-Z), numbers
-        #   (0-9), underscores (_), or dashes (-). The maximum length is 1,024
+        # @return [String] The ID must contain only letters (`[A-Za-z]`), numbers
+        #   (`[0-9]`), underscores (`_`), or dashes (`-`). The maximum length is 1,024
         #   characters.
         #
         def job_id
@@ -197,6 +197,102 @@ module Google
           Convert.millis_to_time @gapi.statistics.end_time
         end
 
+        ##
+        # The number of child jobs executed.
+        #
+        # @return [Integer] The number of child jobs executed.
+        #
+        def num_child_jobs
+          @gapi.statistics.num_child_jobs || 0
+        end
+
+        ##
+        # If this is a child job, the id of the parent.
+        #
+        # @return [String, nil] The ID of the parent job, or `nil` if not a child job.
+        #
+        def parent_job_id
+          @gapi.statistics.parent_job_id
+        end
+
+        ##
+        # An array containing the job resource usage breakdown by reservation, if present. Reservation usage statistics
+        # are only reported for jobs that are executed within reservations.  On-demand jobs do not report this data.
+        #
+        # @return [Array<Google::Cloud::Bigquery::Job::ReservationUsage>, nil] The reservation usage, if present.
+        #
+        def reservation_usage
+          return nil unless @gapi.statistics.reservation_usage
+          Array(@gapi.statistics.reservation_usage).map { |g| ReservationUsage.from_gapi g }
+        end
+
+        ##
+        # The ID of the session if this job is part of one. See the `create_session` param in {Project#query_job} and
+        # {Dataset#query_job}.
+        #
+        # @return [String, nil] The session ID, or `nil` if not associated with a session.
+        #
+        def session_id
+          @gapi.statistics.session_info&.session_id
+        end
+
+        ##
+        # The ID of a multi-statement transaction.
+        #
+        # @return [String, nil] The transaction ID, or `nil` if not associated with a transaction.
+        #
+        def transaction_id
+          @gapi.statistics.transaction_info&.transaction_id
+        end
+
+        ##
+        # The statistics including stack frames for a child job of a script.
+        #
+        # @return [Google::Cloud::Bigquery::Job::ScriptStatistics, nil] The script statistics, or `nil` if the job is
+        #   not a child job.
+        #
+        # @example
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #
+        #   multi_statement_sql = <<~SQL
+        #     -- Declare a variable to hold names as an array.
+        #     DECLARE top_names ARRAY<STRING>;
+        #     -- Build an array of the top 100 names from the year 2017.
+        #     SET top_names = (
+        #     SELECT ARRAY_AGG(name ORDER BY number DESC LIMIT 100)
+        #     FROM `bigquery-public-data.usa_names.usa_1910_current`
+        #     WHERE year = 2017
+        #     );
+        #     -- Which names appear as words in Shakespeare's plays?
+        #     SELECT
+        #     name AS shakespeare_name
+        #     FROM UNNEST(top_names) AS name
+        #     WHERE name IN (
+        #     SELECT word
+        #     FROM `bigquery-public-data.samples.shakespeare`
+        #     );
+        #   SQL
+        #
+        #   job = bigquery.query_job multi_statement_sql
+        #
+        #   job.wait_until_done!
+        #
+        #   child_jobs = bigquery.jobs parent_job: job
+        #
+        #   child_jobs.each do |child_job|
+        #     script_statistics = child_job.script_statistics
+        #     puts script_statistics.evaluation_kind
+        #     script_statistics.stack_frames.each do |stack_frame|
+        #       puts stack_frame.text
+        #     end
+        #   end
+        #
+        def script_statistics
+          ScriptStatistics.from_gapi @gapi.statistics.script_statistics if @gapi.statistics.script_statistics
+        end
+
         ##
         # The configuration for the job. Returns a hash.
         #
@@ -306,6 +402,28 @@ module Google
           true
         end
 
+        ##
+        # Requests that a job is deleted. This call will return when the job is deleted.
+        #
+        # @return [Boolean] Returns `true` if the job was deleted.
+        #
+        # @example
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #
+        #   job = bigquery.job "my_job"
+        #
+        #   job.delete
+        #
+        # @!group Lifecycle
+        #
+        def delete
+          ensure_service!
+          service.delete_job job_id, location: location
+          true
+        end
+
         ##
         # Created a new job with the current configuration.
         #
@@ -371,7 +489,7 @@ module Google
         #
         def wait_until_done!
           backoff = lambda do |retries|
-            delay = [retries**2 + 5, 60].min # Maximum delay is 60
+            delay = [(retries**2) + 5, 60].min # Maximum delay is 60
             sleep delay
           end
           retries = 0
@@ -423,6 +541,167 @@ module Google
           end
         end
 
+        ##
+        # Represents Job resource usage breakdown by reservation.
+        #
+        # @attr_reader [String] name The reservation name or "unreserved" for on-demand resources usage.
+        # @attr_reader [Fixnum] slot_ms The slot-milliseconds the job spent in the given reservation.
+        #
+        class ReservationUsage
+          attr_reader :name
+          attr_reader :slot_ms
+
+          ##
+          # @private Creates a new ReservationUsage instance.
+          def initialize name, slot_ms
+            @name = name
+            @slot_ms = slot_ms
+          end
+
+          ##
+          # @private New ReservationUsage from a statistics.reservation_usage value.
+          def self.from_gapi gapi
+            new gapi.name, gapi.slot_ms
+          end
+        end
+
+        ##
+        # Represents statistics for a child job of a script.
+        #
+        # @attr_reader [String] evaluation_kind Indicates the type of child job. Possible values include `STATEMENT` and
+        #   `EXPRESSION`.
+        # @attr_reader [Array<Google::Cloud::Bigquery::Job::ScriptStackFrame>] stack_frames Stack trace where the
+        #   current evaluation happened. Shows line/column/procedure name of each frame on the stack at the point where
+        #   the current evaluation happened. The leaf frame is first, the primary script is last.
+        #
+        # @example
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #
+        #   multi_statement_sql = <<~SQL
+        #     -- Declare a variable to hold names as an array.
+        #     DECLARE top_names ARRAY<STRING>;
+        #     -- Build an array of the top 100 names from the year 2017.
+        #     SET top_names = (
+        #     SELECT ARRAY_AGG(name ORDER BY number DESC LIMIT 100)
+        #     FROM `bigquery-public-data.usa_names.usa_1910_current`
+        #     WHERE year = 2017
+        #     );
+        #     -- Which names appear as words in Shakespeare's plays?
+        #     SELECT
+        #     name AS shakespeare_name
+        #     FROM UNNEST(top_names) AS name
+        #     WHERE name IN (
+        #     SELECT word
+        #     FROM `bigquery-public-data.samples.shakespeare`
+        #     );
+        #   SQL
+        #
+        #   job = bigquery.query_job multi_statement_sql
+        #
+        #   job.wait_until_done!
+        #
+        #   child_jobs = bigquery.jobs parent_job: job
+        #
+        #   child_jobs.each do |child_job|
+        #     script_statistics = child_job.script_statistics
+        #     puts script_statistics.evaluation_kind
+        #     script_statistics.stack_frames.each do |stack_frame|
+        #       puts stack_frame.text
+        #     end
+        #   end
+        #
+        class ScriptStatistics
+          attr_reader :evaluation_kind
+          attr_reader :stack_frames
+
+          ##
+          # @private Creates a new ScriptStatistics instance.
+          def initialize evaluation_kind, stack_frames
+            @evaluation_kind = evaluation_kind
+            @stack_frames = stack_frames
+          end
+
+          ##
+          # @private New ScriptStatistics from a statistics.script_statistics value.
+          def self.from_gapi gapi
+            frames = Array(gapi.stack_frames).map { |g| ScriptStackFrame.from_gapi g }
+            new gapi.evaluation_kind, frames
+          end
+        end
+
+        ##
+        # Represents a stack frame showing the line/column/procedure name where the current evaluation happened.
+        #
+        # @attr_reader [Integer] start_line One-based start line.
+        # @attr_reader [Integer] start_column One-based start column.
+        # @attr_reader [Integer] end_line One-based end line.
+        # @attr_reader [Integer] end_column One-based end column.
+        # @attr_reader [String] text Text of the current statement/expression.
+        #
+        # @example
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #
+        #   multi_statement_sql = <<~SQL
+        #     -- Declare a variable to hold names as an array.
+        #     DECLARE top_names ARRAY<STRING>;
+        #     -- Build an array of the top 100 names from the year 2017.
+        #     SET top_names = (
+        #     SELECT ARRAY_AGG(name ORDER BY number DESC LIMIT 100)
+        #     FROM `bigquery-public-data.usa_names.usa_1910_current`
+        #     WHERE year = 2017
+        #     );
+        #     -- Which names appear as words in Shakespeare's plays?
+        #     SELECT
+        #     name AS shakespeare_name
+        #     FROM UNNEST(top_names) AS name
+        #     WHERE name IN (
+        #     SELECT word
+        #     FROM `bigquery-public-data.samples.shakespeare`
+        #     );
+        #   SQL
+        #
+        #   job = bigquery.query_job multi_statement_sql
+        #
+        #   job.wait_until_done!
+        #
+        #   child_jobs = bigquery.jobs parent_job: job
+        #
+        #   child_jobs.each do |child_job|
+        #     script_statistics = child_job.script_statistics
+        #     puts script_statistics.evaluation_kind
+        #     script_statistics.stack_frames.each do |stack_frame|
+        #       puts stack_frame.text
+        #     end
+        #   end
+        #
+        class ScriptStackFrame
+          attr_reader :start_line
+          attr_reader :start_column
+          attr_reader :end_line
+          attr_reader :end_column
+          attr_reader :text
+
+          ##
+          # @private Creates a new ScriptStackFrame instance.
+          def initialize start_line, start_column, end_line, end_column, text
+            @start_line = start_line
+            @start_column = start_column
+            @end_line = end_line
+            @end_column = end_column
+            @text = text
+          end
+
+          ##
+          # @private New ScriptStackFrame from a statistics.script_statistics[].stack_frames element.
+          def self.from_gapi gapi
+            new gapi.start_line, gapi.start_column, gapi.end_line, gapi.end_column, gapi.text
+          end
+        end
+
         protected
 
         ##
@@ -431,24 +710,20 @@ module Google
           raise "Must have active connection" unless service
         end
 
-        def retrieve_table project_id, dataset_id, table_id
+        def retrieve_table project_id, dataset_id, table_id, metadata_view: nil
           ensure_service!
-          gapi = service.get_project_table project_id, dataset_id, table_id
+          gapi = service.get_project_table project_id, dataset_id, table_id, metadata_view: metadata_view
           Table.from_gapi gapi, service
         rescue Google::Cloud::NotFoundError
           nil
         end
 
         def status_code_for_reason reason
-          codes = { "accessDenied" => 403, "backendError" => 500,
-                    "billingNotEnabled" => 403,
-                    "billingTierLimitExceeded" => 400, "blocked" => 403,
-                    "duplicate" => 409, "internalError" => 500,
-                    "invalid" => 400, "invalidQuery" => 400, "notFound" => 404,
-                    "notImplemented" => 501, "quotaExceeded" => 403,
-                    "rateLimitExceeded" => 403, "resourceInUse" => 400,
-                    "resourcesExceeded" => 400, "responseTooLarge" => 403,
-                    "tableUnavailable" => 400 }
+          codes = { "accessDenied" => 403, "backendError" => 500, "billingNotEnabled" => 403,
+                    "billingTierLimitExceeded" => 400, "blocked" => 403, "duplicate" => 409, "internalError" => 500,
+                    "invalid" => 400, "invalidQuery" => 400, "notFound" => 404, "notImplemented" => 501,
+                    "quotaExceeded" => 403, "rateLimitExceeded" => 403, "resourceInUse" => 400,
+                    "resourcesExceeded" => 400, "responseTooLarge" => 403, "tableUnavailable" => 400 }
           codes[reason] || 0
         end
       end