google-cloud-bigquery 1.21.2

data/TROUBLESHOOTING.md

@@ -0,0 +1,31 @@
+# Troubleshooting
+
+## Where can I get more help?
+
+### Ask the Community
+
+If you have a question about how to use a Google Cloud client library in your
+project or are stuck in the Developer's console and don't know where to turn,
+it's possible your questions have already been addressed by the community.
+
+First, check out the appropriate tags on StackOverflow:
+  - [`google-cloud-platform+ruby+bigquery`][so-ruby]
+
+Next, try searching through the issues on GitHub:
+
+  - [`api:bigquery` issues][gh-search-ruby]
+
+Still nothing?
+
+### Ask the Developers
+
+If you're experiencing a bug with the code, or have an idea for how it can be
+improved, *please* create a new issue on GitHub so we can talk about it.
+
+  - [New issue][gh-ruby]
+
+[so-ruby]: http://stackoverflow.com/questions/tagged/google-cloud-platform+ruby+bigquery
+
+[gh-search-ruby]: https://github.com/googleapis/google-cloud-ruby/issues?q=label%3A%22api%3A+bigquery%22
+
+[gh-ruby]: https://github.com/googleapis/google-cloud-ruby/issues/new

data/lib/google-cloud-bigquery.rb

@@ -0,0 +1,139 @@
+# Copyright 2016 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.
+
+##
+# This file is here to be autorequired by bundler, so that the
+# Google::Cloud.bigquery and Google::Cloud#bigquery methods can be available,
+# but the library and all dependencies won't be loaded until required and used.
+
+
+gem "google-cloud-core"
+require "google/cloud" unless defined? Google::Cloud.new
+require "google/cloud/config"
+require "googleauth"
+
+module Google
+  module Cloud
+    ##
+    # Creates a new object for connecting to the BigQuery service.
+    # Each call creates a new connection.
+    #
+    # For more information on connecting to Google Cloud see the
+    # {file:AUTHENTICATION.md Authentication Guide}.
+    #
+    # @param [String, Array<String>] scope The OAuth 2.0 scopes controlling the
+    #   set of resources and operations that the connection can access. See
+    #   [Using OAuth 2.0 to Access Google
+    #   APIs](https://developers.google.com/identity/protocols/OAuth2).
+    #
+    #   The default scope is:
+    #
+    #   * `https://www.googleapis.com/auth/bigquery`
+    # @param [Integer] retries Number of times to retry requests on server
+    #   error. The default value is `5`. Optional.
+    # @param [Integer] timeout Default request timeout in seconds. Optional.
+    #
+    # @return [Google::Cloud::Bigquery::Project]
+    #
+    # @example
+    #   require "google/cloud"
+    #
+    #   gcloud = Google::Cloud.new
+    #   bigquery = gcloud.bigquery
+    #   dataset = bigquery.dataset "my_dataset"
+    #   table = dataset.table "my_table"
+    #
+    #   data = table.data
+    #
+    #   # Iterate over the first page of results
+    #   data.each do |row|
+    #     puts row[:name]
+    #   end
+    #   # Retrieve the next page of results
+    #   data = data.next if data.next?
+    #
+    # @example The default scope can be overridden with the `scope` option:
+    #   require "google/cloud"
+    #
+    #   gcloud  = Google::Cloud.new
+    #   platform_scope = "https://www.googleapis.com/auth/cloud-platform"
+    #   bigquery = gcloud.bigquery scope: platform_scope
+    #
+    def bigquery scope: nil, retries: nil, timeout: nil
+      Google::Cloud.bigquery @project, @keyfile, scope:   scope,
+                                                 retries: (retries || @retries),
+                                                 timeout: (timeout || @timeout)
+    end
+
+    ##
+    # Creates a new `Project` instance connected to the BigQuery service.
+    # Each call creates a new connection.
+    #
+    # For more information on connecting to Google Cloud see the
+    # {file:AUTHENTICATION.md Authentication Guide}.
+    #
+    # @param [String] project_id Identifier for a BigQuery project. If not
+    #   present, the default project for the credentials is used.
+    # @param [String, Hash, Google::Auth::Credentials] credentials The path to
+    #   the keyfile as a String, the contents of the keyfile as a Hash, or a
+    #   Google::Auth::Credentials object. (See {Bigquery::Credentials})
+    # @param [String, Array<String>] scope The OAuth 2.0 scopes controlling the
+    #   set of resources and operations that the connection can access. See
+    #   [Using OAuth 2.0 to Access Google
+    #   APIs](https://developers.google.com/identity/protocols/OAuth2).
+    #
+    #   The default scope is:
+    #
+    #   * `https://www.googleapis.com/auth/bigquery`
+    # @param [Integer] retries Number of times to retry requests on server
+    #   error. The default value is `5`. Optional.
+    # @param [Integer] timeout Default timeout to use in requests. Optional.
+    #
+    # @return [Google::Cloud::Bigquery::Project]
+    #
+    # @example
+    #   require "google/cloud"
+    #
+    #   bigquery = Google::Cloud.bigquery
+    #   dataset = bigquery.dataset "my_dataset"
+    #   table = dataset.table "my_table"
+    #
+    def self.bigquery project_id = nil, credentials = nil, scope: nil, retries: nil, timeout: nil
+      require "google/cloud/bigquery"
+      Google::Cloud::Bigquery.new project_id: project_id, credentials: credentials,
+                                  scope: scope, retries: retries, timeout: timeout
+    end
+  end
+end
+
+# Set the default bigquery configuration
+Google::Cloud.configure.add_config! :bigquery do |config|
+  default_project = Google::Cloud::Config.deferred do
+    ENV["BIGQUERY_PROJECT"]
+  end
+  default_creds = Google::Cloud::Config.deferred do
+    Google::Cloud::Config.credentials_from_env(
+      "BIGQUERY_CREDENTIALS", "BIGQUERY_CREDENTIALS_JSON", "BIGQUERY_KEYFILE", "BIGQUERY_KEYFILE_JSON"
+    )
+  end
+
+  config.add_field! :project_id, default_project, match: String, allow_nil: true
+  config.add_alias! :project, :project_id
+  config.add_field! :credentials, default_creds, match: [String, Hash, Google::Auth::Credentials], allow_nil: true
+  config.add_alias! :keyfile, :credentials
+  config.add_field! :scope, nil, match: [String, Array]
+  config.add_field! :retries, nil, match: Integer
+  config.add_field! :timeout, nil, match: Integer
+  config.add_field! :endpoint, nil, match: String
+end

data/lib/google/cloud/bigquery.rb

@@ -0,0 +1,145 @@
+# Copyright 2015 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.
+
+
+require "google-cloud-bigquery"
+require "google/cloud/bigquery/project"
+require "google/cloud/config"
+require "google/cloud/env"
+
+module Google
+  module Cloud
+    ##
+    # # Google Cloud BigQuery
+    #
+    # Google BigQuery enables super-fast, SQL-like queries against massive
+    # datasets, using the processing power of Google's infrastructure.
+    #
+    # See {file:OVERVIEW.md BigQuery Overview}.
+    #
+    module Bigquery
+      # Creates a new `Project` instance connected to the BigQuery service.
+      # Each call creates a new connection.
+      #
+      # For more information on connecting to Google Cloud see the
+      # {file:AUTHENTICATION.md Authentication Guide}.
+      #
+      # @param [String] project_id Identifier for a BigQuery project. If not
+      #   present, the default project for the credentials is used.
+      # @param [String, Hash, Google::Auth::Credentials] credentials The path to
+      #   the keyfile as a String, the contents of the keyfile as a Hash, or a
+      #   Google::Auth::Credentials object. (See {Bigquery::Credentials})
+      # @param [String, Array<String>] scope The OAuth 2.0 scopes controlling
+      #   the set of resources and operations that the connection can access.
+      #   See # [Using OAuth 2.0 to Access Google #
+      #   APIs](https://developers.google.com/identity/protocols/OAuth2).
+      #
+      #   The default scope is:
+      #
+      #   * `https://www.googleapis.com/auth/bigquery`
+      # @param [Integer] retries Number of times to retry requests on server
+      #   error. The default value is `5`. Optional.
+      # @param [Integer] timeout Default timeout to use in requests. Optional.
+      # @param [String] endpoint Override of the endpoint host name. Optional.
+      #   If the param is nil, uses the default endpoint.
+      # @param [String] project Alias for the `project_id` argument. Deprecated.
+      # @param [String] keyfile Alias for the `credentials` argument.
+      #   Deprecated.
+      #
+      # @return [Google::Cloud::Bigquery::Project]
+      #
+      # @example
+      #   require "google/cloud/bigquery"
+      #
+      #   bigquery = Google::Cloud::Bigquery.new
+      #   dataset = bigquery.dataset "my_dataset"
+      #   table = dataset.table "my_table"
+      #
+      def self.new project_id: nil, credentials: nil, scope: nil, retries: nil, timeout: nil, endpoint: nil,
+                   project: nil, keyfile: nil
+        scope       ||= configure.scope
+        retries     ||= configure.retries
+        timeout     ||= configure.timeout
+        endpoint    ||= configure.endpoint
+        credentials ||= (keyfile || default_credentials(scope: scope))
+
+        unless credentials.is_a? Google::Auth::Credentials
+          credentials = Bigquery::Credentials.new credentials, scope: scope
+        end
+
+        project_id = resolve_project_id(project_id || project, credentials)
+        raise ArgumentError, "project_id is missing" if project_id.empty?
+
+        Bigquery::Project.new(
+          Bigquery::Service.new(
+            project_id, credentials,
+            retries: retries, timeout: timeout, host: endpoint
+          )
+        )
+      end
+
+      ##
+      # Configure the Google Cloud BigQuery library.
+      #
+      # The following BigQuery configuration parameters are supported:
+      #
+      # * `project_id` - (String) Identifier for a BigQuery project. (The
+      #   parameter `project` is considered deprecated, but may also be used.)
+      # * `credentials` - (String, Hash, Google::Auth::Credentials) The path to
+      #   the keyfile as a String, the contents of the keyfile as a Hash, or a
+      #   Google::Auth::Credentials object. (See {Bigquery::Credentials}) (The
+      #   parameter `keyfile` is considered deprecated, but may also be used.)
+      # * `endpoint` - (String) Override of the endpoint host name, or `nil`
+      #   to use the default endpoint.
+      # * `scope` - (String, Array<String>) The OAuth 2.0 scopes controlling
+      #   the set of resources and operations that the connection can access.
+      # * `retries` - (Integer) Number of times to retry requests on server
+      #   error.
+      # * `timeout` - (Integer) Default timeout to use in requests.
+      #
+      # @return [Google::Cloud::Config] The configuration object the
+      #   Google::Cloud::Bigquery library uses.
+      #
+      def self.configure
+        yield Google::Cloud.configure.bigquery if block_given?
+
+        Google::Cloud.configure.bigquery
+      end
+
+      ##
+      # @private Resolve project.
+      def self.resolve_project_id given_project, credentials
+        project_id = given_project || default_project_id
+        project_id ||= credentials.project_id if credentials.respond_to? :project_id
+        project_id.to_s # Always cast to a string
+      end
+
+      ##
+      # @private Default project.
+      def self.default_project_id
+        Google::Cloud.configure.bigquery.project_id ||
+          Google::Cloud.configure.project_id ||
+          Google::Cloud.env.project_id
+      end
+
+      ##
+      # @private Default credentials.
+      def self.default_credentials scope: nil
+        Google::Cloud.configure.bigquery.credentials ||
+          Google::Cloud.configure.credentials ||
+          Bigquery::Credentials.default(scope: scope)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,197 @@
+# Copyright 2020 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.
+
+
+require "google/cloud/bigquery/standard_sql"
+
+module Google
+  module Cloud
+    module Bigquery
+      ##
+      # # Argument
+      #
+      # Input/output argument of a function or a stored procedure. See {Routine}.
+      #
+      # @example
+      #   require "google/cloud/bigquery"
+      #
+      #   bigquery = Google::Cloud::Bigquery.new
+      #   dataset = bigquery.dataset "my_dataset"
+      #   routine = dataset.create_routine "my_routine" do |r|
+      #     r.routine_type = "SCALAR_FUNCTION"
+      #     r.language = :SQL
+      #     r.body = "(SELECT SUM(IF(elem.name = \"foo\",elem.val,null)) FROM UNNEST(arr) AS elem)"
+      #     r.arguments = [
+      #       Google::Cloud::Bigquery::Argument.new(
+      #         name: "arr",
+      #         argument_kind: "FIXED_TYPE",
+      #         data_type: Google::Cloud::Bigquery::StandardSql::DataType.new(
+      #           type_kind: "ARRAY",
+      #           array_element_type: Google::Cloud::Bigquery::StandardSql::DataType.new(
+      #             type_kind: "STRUCT",
+      #             struct_type: Google::Cloud::Bigquery::StandardSql::StructType.new(
+      #               fields: [
+      #                 Google::Cloud::Bigquery::StandardSql::Field.new(
+      #                   name: "name",
+      #                   type: Google::Cloud::Bigquery::StandardSql::DataType.new(type_kind: "STRING")
+      #                 ),
+      #                 Google::Cloud::Bigquery::StandardSql::Field.new(
+      #                   name: "val",
+      #                   type: Google::Cloud::Bigquery::StandardSql::DataType.new(type_kind: "INT64")
+      #                 )
+      #               ]
+      #             )
+      #           )
+      #         )
+      #       )
+      #     ]
+      #   end
+      #
+      class Argument
+        ##
+        # Creates a new, immutable Argument object.
+        #
+        # @overload initialize(data_type, kind, mode, name)
+        #   @param [StandardSql::DataType, String] data_type The data type of the argument. Required unless
+        #     {#argument_kind} is `ANY_TYPE`.
+        #   @param [String] argument_kind The kind of argument. Optional. Defaults to `FIXED_TYPE`.
+        #
+        #     * `FIXED_TYPE` - The argument is a variable with fully specified type, which can be a struct or an array,
+        #       but not a table.
+        #     * `ANY_TYPE` - The argument is any type, including struct or array, but not a table.
+        #
+        #     To be added: `FIXED_TABLE`, `ANY_TABLE`.
+        #   @param [String] mode Specifies whether the argument is input or output. Optional. Can be set for procedures
+        #     only.
+        #
+        #     * IN - The argument is input-only.
+        #     * OUT - The argument is output-only.
+        #     * INOUT - The argument is both an input and an output.
+        #   @param [String] name The name of the argument. Optional. Can be absent for a function return argument.
+        #
+        def initialize **kwargs
+          kwargs[:data_type] = StandardSql::DataType.gapi_from_string_or_data_type kwargs[:data_type]
+          @gapi = Google::Apis::BigqueryV2::Argument.new(**kwargs)
+        end
+
+        ##
+        # The data type of the argument. Required unless {#argument_kind} is `ANY_TYPE`.
+        #
+        # @return [StandardSql::DataType] The data type.
+        #
+        def data_type
+          StandardSql::DataType.from_gapi @gapi.data_type
+        end
+
+        ##
+        # The kind of argument. Optional. Defaults to `FIXED_TYPE`.
+        #
+        # * `FIXED_TYPE` - The argument is a variable with fully specified type, which can be a struct or an array, but
+        #   not a table.
+        # * `ANY_TYPE` - The argument is any type, including struct or array, but not a table.
+        #
+        # To be added: `FIXED_TABLE`, `ANY_TABLE`.
+        #
+        # @return [String] The upper case kind of argument.
+        #
+        def argument_kind
+          @gapi.argument_kind
+        end
+
+        ##
+        # Checks if the value of {#argument_kind} is `FIXED_TYPE`. The default is `true`.
+        #
+        # @return [Boolean] `true` when `FIXED_TYPE`, `false` otherwise.
+        #
+        def fixed_type?
+          return true if @gapi.argument_kind.nil?
+          @gapi.argument_kind == "FIXED_TYPE"
+        end
+
+        ##
+        # Checks if the value of {#argument_kind} is `ANY_TYPE`. The default is `false`.
+        #
+        # @return [Boolean] `true` when `ANY_TYPE`, `false` otherwise.
+        #
+        def any_type?
+          @gapi.argument_kind == "ANY_TYPE"
+        end
+
+        ##
+        # Specifies whether the argument is input or output. Optional. Can be set for procedures only.
+        #
+        # * IN - The argument is input-only.
+        # * OUT - The argument is output-only.
+        # * INOUT - The argument is both an input and an output.
+        #
+        # @return [String] The upper case input/output mode of the argument.
+        #
+        def mode
+          @gapi.mode
+        end
+
+        ##
+        # Checks if the value of {#mode} is `IN`. Can be set for procedures only. The default is `false`.
+        #
+        # @return [Boolean] `true` when `IN`, `false` otherwise.
+        #
+        def in?
+          @gapi.mode == "IN"
+        end
+
+        ##
+        # Checks if the value of {#mode} is `OUT`. Can be set for procedures only. The default is `false`.
+        #
+        # @return [Boolean] `true` when `OUT`, `false` otherwise.
+        #
+        def out?
+          @gapi.mode == "OUT"
+        end
+
+        ##
+        # Checks if the value of {#mode} is `INOUT`. Can be set for procedures only. The default is `false`.
+        #
+        # @return [Boolean] `true` when `INOUT`, `false` otherwise.
+        #
+        def inout?
+          @gapi.mode == "INOUT"
+        end
+
+        ##
+        #
+        # The name of the argument. Optional. Can be absent for a function return argument.
+        #
+        # @return [String] The name of the argument.
+        #
+        def name
+          @gapi.name
+        end
+
+        ##
+        # @private
+        def to_gapi
+          @gapi
+        end
+
+        ##
+        # @private New Argument from a Google API Client object.
+        def self.from_gapi gapi
+          new.tap do |a|
+            a.instance_variable_set :@gapi, gapi
+          end
+        end
+      end
+    end
+  end
+end