gcloud 0.5.0 → 0.6.0

data/lib/gcloud/bigquery/project.rb

@@ -93,25 +93,25 @@ module Gcloud
       #   syntax}[https://cloud.google.com/bigquery/query-reference], of the
       #   query to execute. Example: "SELECT count(f1) FROM
       #   [myProjectId:myDatasetId.myTableId]". (+String+)
-      # <code>options[:priority]</code>::
+      # +priority+::
       #   Specifies a priority for the query. Possible values include
       #   +INTERACTIVE+ and +BATCH+. The default value is +INTERACTIVE+.
       #   (+String+)
-      # <code>options[:cache]</code>::
+      # +cache+::
       #   Whether to look for the result in the query cache. The query cache is
       #   a best-effort cache that will be flushed whenever tables in the query
       #   are modified. The default value is +true+. (+Boolean+)
-      # <code>options[:table]</code>::
+      # +table+::
       #   The destination table where the query results should be stored. If not
       #   present, a new table will be created to store the results. (+Table+)
-      # <code>options[:create]</code>::
+      # +create+::
       #   Specifies whether the job is allowed to create new tables. (+String+)
       #
       #   The following values are supported:
       #   * +needed+ - Create the table if it does not exist.
       #   * +never+ - The table must already exist. A 'notFound' error is
       #     raised if the table does not exist.
-      # <code>options[:write]</code>::
+      # +write+::
       #   Specifies the action that occurs if the destination table already
       #   exists. (+String+)
       #
@@ -120,15 +120,15 @@ module Gcloud
       #   * +append+ - BigQuery appends the data to the table.
       #   * +empty+ - A 'duplicate' error is returned in the job result if the
       #     table exists and contains data.
-      # <code>options[:large_results]</code>::
+      # +large_results+::
       #   If +true+, allows the query to produce arbitrarily large result tables
-      #   at a slight cost in performance. Requires <code>options[:table]</code>
-      #   to be set. (+Boolean+)
-      # <code>options[:flatten]</code>::
+      #   at a slight cost in performance. Requires +table+ parameter to be set.
+      #   (+Boolean+)
+      # +flatten+::
       #   Flattens all nested and repeated fields in the query results. The
-      #   default value is +true+. <code>options[:large_results]</code> must be
-      #   +true+ if this is set to +false+. (+Boolean+)
-      # <code>options[:dataset]</code>::
+      #   default value is +true+. +large_results+ parameter must be +true+ if
+      #   this is set to +false+. (+Boolean+)
+      # +dataset+::
       #   Specifies the default dataset to use for unqualified table names in
       #   the query. (+Dataset+ or +String+)
       #
@@ -152,8 +152,13 @@ module Gcloud
       #     end
       #   end
       #
-      def query_job query, options = {}
+      def query_job query, priority: "INTERACTIVE", cache: true, table: nil,
+                    create: nil, write: nil, large_results: nil, flatten: nil,
+                    dataset: nil
         ensure_connection!
+        options = { priority: priority, cache: cache, table: table,
+                    create: create, write: write, large_results: large_results,
+                    flatten: flatten, dataset: dataset }
         resp = connection.query_job query, options
         if resp.success?
           Job.from_gapi resp.data, connection
@@ -173,37 +178,37 @@ module Gcloud
       #   syntax}[https://cloud.google.com/bigquery/query-reference], of the
       #   query to execute. Example: "SELECT count(f1) FROM
       #   [myProjectId:myDatasetId.myTableId]". (+String+)
-      # <code>options[:max]</code>::
+      # +max+::
       #   The maximum number of rows of data to return per page of results.
       #   Setting this flag to a small value such as 1000 and then paging
       #   through results might improve reliability when the query result set is
       #   large. In addition to this limit, responses are also limited to 10 MB.
       #   By default, there is no maximum row count, and only the byte limit
       #   applies. (+Integer+)
-      # <code>options[:timeout]</code>::
+      # +timeout+::
       #   How long to wait for the query to complete, in milliseconds, before
       #   the request times out and returns. Note that this is only a timeout
       #   for the request, not the query. If the query takes longer to run than
       #   the timeout value, the call returns without any results and with
       #   QueryData#complete? set to false. The default value is 10000
       #   milliseconds (10 seconds). (+Integer+)
-      # <code>options[:dryrun]</code>::
+      # +dryrun+::
       #   If set to +true+, BigQuery doesn't run the job. Instead, if the query
       #   is valid, BigQuery returns statistics about the job such as how many
       #   bytes would be processed. If the query is invalid, an error returns.
       #   The default value is +false+. (+Boolean+)
-      # <code>options[:cache]</code>::
+      # +cache+::
       #   Whether to look for the result in the query cache. The query cache is
       #   a best-effort cache that will be flushed whenever tables in the query
       #   are modified. The default value is true. For more information, see
       #   {query caching}[https://developers.google.com/bigquery/querying-data].
       #   (+Boolean+)
-      # <code>options[:dataset]</code>::
+      # +dataset+::
       #   Specifies the default datasetId and projectId to assume for any
       #   unqualified table names in the query. If not set, all table names in
       #   the query string must be qualified in the format 'datasetId.tableId'.
       #   (+String+)
-      # <code>options[:project]</code>::
+      # +project+::
       #   Specifies the default projectId to assume for any unqualified table
       #   names in the query. Only used if +dataset+ option is set. (+String+)
       #
@@ -223,8 +228,11 @@ module Gcloud
       #     puts row["name"]
       #   end
       #
-      def query query, options = {}
+      def query query, max: nil, timeout: 10000, dryrun: nil, cache: true,
+                dataset: nil, project: nil
         ensure_connection!
+        options = { max: max, timeout: timeout, dryrun: dryrun, cache: cache,
+                    dataset: dataset, project: project }
         resp = connection.query query, options
         if resp.success?
           QueryData.from_gapi resp.data, connection
@@ -275,16 +283,14 @@ module Gcloud
       #   A unique ID for this dataset, without the project name.
       #   The ID must contain only letters (a-z, A-Z), numbers (0-9), or
       #   underscores (_). The maximum length is 1,024 characters. (+String+)
-      # +options+::
-      #   An optional Hash for controlling additional behavior. (+Hash+)
-      # <code>options[:name]</code>::
+      # +name+::
       #   A descriptive name for the dataset. (+String+)
-      # <code>options[:description]</code>::
+      # +description+::
       #   A user-friendly description of the dataset. (+String+)
-      # <code>options[:expiration]</code>::
+      # +expiration+::
       #   The default lifetime of all tables in the dataset, in milliseconds.
       #   The minimum value is 3600000 milliseconds (one hour). (+Integer+)
-      # <code>options[:access]</code>::
+      # +access+::
       #   The access rules for a Dataset using the Google Cloud Datastore API
       #   data structure of an array of hashes. See {BigQuery Access
       #   Control}[https://cloud.google.com/bigquery/access-control] for more
@@ -336,21 +342,21 @@ module Gcloud
       #     access.add_writer_user "writers@example.com"
       #   end
       #
-      def create_dataset dataset_id, options = {}
+      def create_dataset dataset_id, name: nil, description: nil,
+                         expiration: nil, access: nil
         if block_given?
           access_builder = Dataset::Access.new connection.default_access_rules,
                                                "projectId" => project
           yield access_builder
-          options[:access] = access_builder.access if access_builder.changed?
+          access = access_builder.access if access_builder.changed?
         end
 
         ensure_connection!
+        options = { name: name, description: description,
+                    expiration: expiration, access: access }
         resp = connection.insert_dataset dataset_id, options
-        if resp.success?
-          Dataset.from_gapi resp.data, connection
-        else
-          fail ApiError.from_response(resp)
-        end
+        return Dataset.from_gapi(resp.data, connection) if resp.success?
+        fail ApiError.from_response(resp)
       end
 
       ##
@@ -358,15 +364,13 @@ module Gcloud
       #
       # === Parameters
       #
-      # +options+::
-      #   An optional Hash for controlling additional behavior. (+Hash+)
-      # <code>options[:all]</code>::
+      # +all+::
       #   Whether to list all datasets, including hidden ones. The default is
       #   +false+. (+Boolean+)
-      # <code>options[:token]</code>::
+      # +token+::
       #   A previously-returned page token representing part of the larger set
       #   of results to view. (+String+)
-      # <code>options[:max]</code>::
+      # +max+::
       #   Maximum number of datasets to return. (+Integer+)
       #
       # === Returns
@@ -415,8 +419,9 @@ module Gcloud
       #     tmp_datasets = bigquery.datasets token: tmp_datasets.token
       #   end
       #
-      def datasets options = {}
+      def datasets all: nil, token: nil, max: nil
         ensure_connection!
+        options = { all: all, token: token, max: max }
         resp = connection.list_datasets options
         if resp.success?
           Dataset::List.from_response resp, connection
@@ -462,17 +467,15 @@ module Gcloud
       #
       # === Parameters
       #
-      # +options+::
-      #   An optional Hash for controlling additional behavior. (+Hash+)
-      # <code>options[:all]</code>::
+      # +all+::
       #   Whether to display jobs owned by all users in the project.
       #   The default is +false+. (+Boolean+)
-      # <code>options[:token]</code>::
+      # +token+::
       #   A previously-returned page token representing part of the larger set
       #   of results to view. (+String+)
-      # <code>options[:max]</code>::
+      # +max+::
       #   Maximum number of jobs to return. (+Integer+)
-      # <code>options[:filter]</code>::
+      # +filter+::
       #   A filter for job state. (+String+)
       #
       #   Acceptable values are:
@@ -522,8 +525,9 @@ module Gcloud
       #     tmp_jobs = bigquery.jobs token: tmp_jobs.token
       #   end
       #
-      def jobs options = {}
+      def jobs all: nil, token: nil, max: nil, filter: nil
         ensure_connection!
+        options = { all: all, token: token, max: max, filter: filter }
         resp = connection.list_jobs options
         if resp.success?
           Job::List.from_response resp, connection

data/lib/gcloud/bigquery/query_job.rb

@@ -47,7 +47,7 @@ module Gcloud
       # Checks if the the query job allows arbitrarily large results at a slight
       # cost to performance.
       def large_results?
-        val = config["query"]["preserveNulls"]
+        val = config["query"]["allowLargeResults"]
         return false if val.nil?
         val
       end
@@ -99,16 +99,14 @@ module Gcloud
       #
       # === Parameters
       #
-      # +options+::
-      #   An optional Hash for controlling additional behavior. (+Hash+)
-      # <code>options[:token]</code>::
+      # +token+::
       #   Page token, returned by a previous call, identifying the result set.
       #   (+String+)
-      # <code>options[:max]</code>::
+      # +max+::
       #   Maximum number of results to return. (+Integer+)
-      # <code>options[:start]</code>::
+      # +start+::
       #   Zero-based index of the starting row to read. (+Integer+)
-      # <code>options[:timeout]</code>::
+      # +timeout+::
       #   How long to wait for the query to complete, in milliseconds, before
       #   returning. Default is 10,000 milliseconds (10 seconds). (+Integer+)
       #
@@ -133,8 +131,9 @@ module Gcloud
       #   end
       #   data = data.next if data.next?
       #
-      def query_results options = {}
+      def query_results token: nil, max: nil, start: nil, timeout: nil
         ensure_connection!
+        options = { token: token, max: max, start: start, timeout: timeout }
         resp = connection.job_query_results job_id, options
         if resp.success?
           QueryData.from_gapi resp.data, connection

data/lib/gcloud/bigquery/table.rb

@@ -300,9 +300,7 @@ module Gcloud
       #
       # === Parameters
       #
-      # +options+::
-      #   An optional Hash for controlling additional behavior. (+Hash+)
-      # <code>options[:replace]</code>::
+      # +replace+::
       #   Whether to replace the existing schema with the new schema. If
       #   +true+, the fields will replace the existing schema. If
       #   +false+, the fields will be added to the existing schema. When a table
@@ -328,13 +326,13 @@ module Gcloud
       #
       # :category: Attributes
       #
-      def schema options = {}
+      def schema replace: false
         ensure_full_data!
         g = @gapi
         g = g.to_hash if g.respond_to? :to_hash
         s = g["schema"] ||= {}
         return s unless block_given?
-        s = nil if options[:replace]
+        s = nil if replace
         schema_builder = Schema.new s
         yield schema_builder
         self.schema = schema_builder.schema if schema_builder.changed?
@@ -409,14 +407,12 @@ module Gcloud
       #
       # === Parameters
       #
-      # +options+::
-      #   An optional Hash for controlling additional behavior. (+Hash+)
-      # <code>options[:token]</code>::
+      # +token+::
       #   Page token, returned by a previous call, identifying the result set.
       #   (+String+)
-      # <code>options[:max]</code>::
+      # +max+::
       #   Maximum number of results to return. (+Integer+)
-      # <code>options[:start]</code>::
+      # +start+::
       #   Zero-based index of the starting row to read. (+Integer+)
       #
       # === Returns
@@ -440,8 +436,9 @@ module Gcloud
       #
       # :category: Data
       #
-      def data options = {}
+      def data token: nil, max: nil, start: nil
         ensure_connection!
+        options = { token: token, max: max, start: start }
         resp = connection.list_tabledata dataset_id, table_id, options
         if resp.success?
           Data.from_response resp, self
@@ -457,16 +454,14 @@ module Gcloud
       #
       # +destination_table+::
       #   The destination for the copied data. (+Table+ or +String+)
-      # +options+::
-      #   An optional Hash for controlling additional behavior. (+Hash+)
-      # <code>options[:create]</code>::
+      # +create+::
       #   Specifies whether the job is allowed to create new tables. (+String+)
       #
       #   The following values are supported:
       #   * +needed+ - Create the table if it does not exist.
       #   * +never+ - The table must already exist. A 'notFound' error is
       #     raised if the table does not exist.
-      # <code>options[:write]</code>::
+      # +write+::
       #   Specifies how to handle data already present in the destination table.
       #   The default value is +empty+. (+String+)
       #
@@ -509,8 +504,9 @@ module Gcloud
       #
       # :category: Data
       #
-      def copy destination_table, options = {}
+      def copy destination_table, create: nil, write: nil, dryrun: nil
         ensure_connection!
+        options = { create: create, write: write, dryrun: dryrun }
         resp = connection.copy_table table_ref,
                                      get_table_ref(destination_table),
                                      options
@@ -528,16 +524,14 @@ module Gcloud
       #
       # +source_url+::
       #   The URI of source table to link. (+String+)
-      # +options+::
-      #   An optional Hash for controlling additional behavior. (+Hash+)
-      # <code>options[:create]</code>::
+      # +create+::
       #   Specifies whether the job is allowed to create new tables. (+String+)
       #
       #   The following values are supported:
       #   * +needed+ - Create the table if it does not exist.
       #   * +never+ - The table must already exist. A 'notFound' error is
       #     raised if the table does not exist.
-      # <code>options[:write]</code>::
+      # +write+::
       #   Specifies how to handle data already present in the table.
       #   The default value is +empty+. (+String+)
       #
@@ -553,8 +547,9 @@ module Gcloud
       #
       # :category: Data
       #
-      def link source_url, options = {} #:nodoc:
+      def link source_url, create: nil, write: nil, dryrun: nil #:nodoc:
         ensure_connection!
+        options = { create: create, write: write, dryrun: dryrun }
         resp = connection.link_table table_ref, source_url, options
         if resp.success?
           Job.from_gapi resp.data, connection
@@ -574,22 +569,20 @@ module Gcloud
       #   The Google Storage file or file URI pattern(s) to which BigQuery
       #   should extract the table data.
       #   (+Gcloud::Storage::File+ or +String+ or +Array+)
-      # +options+::
-      #   An optional Hash for controlling additional behavior. (+Hash+)
-      # <code>options[:format]</code>::
+      # +format+::
       #   The exported file format. The default value is +csv+. (+String+)
       #
       #   The following values are supported:
       #   * +csv+ - CSV
       #   * +json+ - {Newline-delimited JSON}[http://jsonlines.org/]
       #   * +avro+ - {Avro}[http://avro.apache.org/]
-      # <code>options[:compression]</code>::
+      # +compression+::
       #   The compression type to use for exported files. Possible values
       #   include +GZIP+ and +NONE+. The default value is +NONE+. (+String+)
-      # <code>options[:delimiter]</code>::
+      # +delimiter+::
       #   Delimiter to use between fields in the exported data. Default is
       #   <code>,</code>. (+String+)
-      # <code>options[:header]</code>::
+      # +header+::
       #   Whether to print out a header row in the results. Default is +true+.
       #   (+Boolean+)
       #
@@ -611,8 +604,11 @@ module Gcloud
       #
       # :category: Data
       #
-      def extract extract_url, options = {}
+      def extract extract_url, format: nil, compression: nil, delimiter: nil,
+                  header: nil, dryrun: nil
         ensure_connection!
+        options = { format: format, compression: compression,
+                    delimiter: delimiter, header: header, dryrun: dryrun }
         resp = connection.extract_table table_ref, extract_url, options
         if resp.success?
           Job.from_gapi resp.data, connection
@@ -630,9 +626,7 @@ module Gcloud
       #   A file or the URI of a Google Cloud Storage file containing
       #   data to load into the table.
       #   (+File+ or +Gcloud::Storage::File+ or +String+)
-      # +options+::
-      #   An optional Hash for controlling additional behavior. (+Hash+)
-      # <code>options[:format]</code>::
+      # +format+::
       #   The exported file format. The default value is +csv+. (+String+)
       #
       #   The following values are supported:
@@ -640,14 +634,14 @@ module Gcloud
       #   * +json+ - {Newline-delimited JSON}[http://jsonlines.org/]
       #   * +avro+ - {Avro}[http://avro.apache.org/]
       #   * +datastore_backup+ - Cloud Datastore backup
-      # <code>options[:create]</code>::
+      # +create+::
       #   Specifies whether the job is allowed to create new tables. (+String+)
       #
       #   The following values are supported:
       #   * +needed+ - Create the table if it does not exist.
       #   * +never+ - The table must already exist. A 'notFound' error is
       #     raised if the table does not exist.
-      # <code>options[:write]</code>::
+      # +write+::
       #   Specifies how to handle data already present in the table.
       #   The default value is +empty+. (+String+)
       #
@@ -656,32 +650,32 @@ module Gcloud
       #   * +append+ - BigQuery appends the data to the table.
       #   * +empty+ - An error will be returned if the table already contains
       #     data.
-      # <code>options[:projection_fields]</code>::
+      # +projection_fields+::
       #   If the +format+ option is set to +datastore_backup+, indicates which
       #   entity properties to load from a Cloud Datastore backup. Property
       #   names are case sensitive and must be top-level properties. If not set,
       #   BigQuery loads all properties. If any named property isn't found in
       #   the Cloud Datastore backup, an invalid error is returned. (+Array+)
-      # <code>options[:jagged_rows]</code>::
+      # +jagged_rows+::
       #   Accept rows that are missing trailing optional columns. The missing
       #   values are treated as nulls. If +false+, records with missing trailing
       #   columns are treated as bad records, and if there are too many bad
       #   records, an invalid error is returned in the job result. The default
       #   value is +false+. Only applicable to CSV, ignored for other formats.
       #   (+Boolean+)
-      # <code>options[:quoted_newlines]</code>::
+      # +quoted_newlines+::
       #   Indicates if BigQuery should allow quoted data sections that contain
       #   newline characters in a CSV file. The default value is +false+.
       #   (+Boolean+)
-      # <code>options[:encoding]</code>::
+      # +encoding+::
       #   The character encoding of the data. The supported values are +UTF-8+
       #   or +ISO-8859-1+. The default value is +UTF-8+. (+String+)
-      # <code>options[:delimiter]</code>::
+      # +delimiter+::
       #   Specifices the separator for fields in a CSV file. BigQuery converts
       #   the string to +ISO-8859-1+ encoding, and then uses the first byte of
       #   the encoded string to split the data in its raw, binary state. Default
       #   is <code>,</code>. (+String+)
-      # <code>options[:ignore_unknown]</code>::
+      # +ignore_unknown+::
       #   Indicates if BigQuery should allow extra values that are not
       #   represented in the table schema. If true, the extra values are
       #   ignored. If false, records with extra columns are treated as bad
@@ -693,12 +687,12 @@ module Gcloud
       #
       #   * +CSV+: Trailing columns
       #   * +JSON+: Named values that don't match any column names
-      # <code>options[:max_bad_records]</code>::
+      # +max_bad_records+::
       #   The maximum number of bad records that BigQuery can ignore when
       #   running the job. If the number of bad records exceeds this value, an
       #   invalid error is returned in the job result. The default value is +0+,
       #   which requires that all records are valid. (+Integer+)
-      # <code>options[:quote]</code>::
+      # +quote+::
       #   The value that is used to quote data sections in a CSV file. BigQuery
       #   converts the string to ISO-8859-1 encoding, and then uses the first
       #   byte of the encoded string to split the data in its raw, binary state.
@@ -706,7 +700,7 @@ module Gcloud
       #   not contain quoted sections, set the property value to an empty
       #   string. If your data contains quoted newline characters, you must also
       #   set the allowQuotedNewlines property to true. (+String+)
-      # <code>options[:skip_leading]</code>::
+      # +skip_leading+::
       #   The number of rows at the top of a CSV file that BigQuery will skip
       #   when loading the data. The default value is +0+. This property is
       #   useful if you have header rows in the file that should be skipped.
@@ -784,15 +778,21 @@ module Gcloud
       #
       # :category: Data
       #
-      def load file, options = {}
+      def load file, format: nil, create: nil, write: nil,
+               projection_fields: nil, jagged_rows: nil, quoted_newlines: nil,
+               encoding: nil, delimiter: nil, ignore_unknown: nil,
+               max_bad_records: nil, quote: nil, skip_leading: nil, dryrun: nil
         ensure_connection!
-        if storage_url? file
-          load_storage file, options
-        elsif local_file? file
-          load_local file, options
-        else
-          fail Gcloud::Bigquery::Error, "Don't know how to load #{file}"
-        end
+        options = { format: format, create: create, write: write,
+                    projection_fields: projection_fields,
+                    jagged_rows: jagged_rows, quoted_newlines: quoted_newlines,
+                    encoding: encoding, delimiter: delimiter,
+                    ignore_unknown: ignore_unknown,
+                    max_bad_records: max_bad_records, quote: quote,
+                    skip_leading: skip_leading, dryrun: dryrun }
+        return load_storage(file, options) if storage_url? file
+        return load_local(file, options) if local_file? file
+        fail Gcloud::Bigquery::Error, "Don't know how to load #{file}"
       end
 
       ##
@@ -806,13 +806,11 @@ module Gcloud
       # +rows+::
       #   A hash object or array of hash objects containing the data.
       #   (+Array+ or +Hash+)
-      # +options+::
-      #   An optional Hash for controlling additional behavior. (+Hash+)
-      # <code>options[:skip_invalid]</code>::
+      # +skip_invalid+::
       #   Insert all valid rows of a request, even if invalid rows exist. The
       #   default value is +false+, which causes the entire request to fail if
       #   any invalid rows exist. (+Boolean+)
-      # <code>options[:ignore_unknown]</code>::
+      # +ignore_unknown+::
       #   Accept rows that contain values that do not match the schema. The
       #   unknown values are ignored. Default is false, which treats unknown
       #   values as errors. (+Boolean+)
@@ -838,9 +836,10 @@ module Gcloud
       #
       # :category: Data
       #
-      def insert rows, options = {}
+      def insert rows, skip_invalid: nil, ignore_unknown: nil
         rows = [rows] if rows.is_a? Hash
         ensure_connection!
+        options = { skip_invalid: skip_invalid, ignore_unknown: ignore_unknown }
         resp = connection.insert_tabledata dataset_id, table_id, rows, options
         if resp.success?
           InsertResponse.from_gapi rows, resp.data