BigQuery API - Class Google::Cloud::Bigquery::Data (v1.41.0)

Reference documentation and code samples for the BigQuery API class Google::Cloud::Bigquery::Data.

Data

Represents a page of results (rows) as an array of hashes. Because Data delegates to Array, methods such as Array#count represent the number of rows in the page. In addition, methods of this class include result set metadata such as total and provide access to the schema of the query or table. See Project#query, Google::Cloud::Bigquery::Dataset#query and Table#data.

Inherits

Array

Example

require "google/cloud/bigquery"

bigquery = Google::Cloud::Bigquery.new

sql = "SELECT word FROM `bigquery-public-data.samples.shakespeare`"
job = bigquery.query_job sql

job.wait_until_done!
data = job.data

data.count # 100000
data.total # 164656

# Iterate over the first page of results
data.each do |row|
  puts row[:word]
end
# Retrieve the next page of results
data = data.next if data.next?

Methods

#all

def all(request_limit: nil, &block) { |row| ... } -> Enumerator

Retrieves all rows by repeatedly loading #next until #next? returns false. Calls the given block once for each row, which is passed as the parameter.

An enumerator is returned if no block is given.

This method may make several API calls until all rows are retrieved. Be sure to use as narrow a search criteria as possible. Please use with caution.

Parameter

request_limit (Integer) (defaults to: nil) — The upper limit of API requests to make to load all data. Default is no limit.

Yields

(row) — The block for accessing each row of data.

Yield Parameter

row (Hash) — The row object.

Returns

(Enumerator) — An enumerator providing access to all of the data.

Examples

Iterating each rows by passing a block:

require "google/cloud/bigquery"

bigquery = Google::Cloud::Bigquery.new
dataset = bigquery.dataset "my_dataset"
table = dataset.table "my_table"

table.data.all do |row|
  puts row[:word]
end

Using the enumerator by not passing a block:

require "google/cloud/bigquery"

bigquery = Google::Cloud::Bigquery.new
dataset = bigquery.dataset "my_dataset"
table = dataset.table "my_table"

words = table.data.all.map do |row|
  row[:word]
end

Limit the number of API calls made:

require "google/cloud/bigquery"

bigquery = Google::Cloud::Bigquery.new
dataset = bigquery.dataset "my_dataset"
table = dataset.table "my_table"

table.data.all(request_limit: 10) do |row|
  puts row[:word]
end

#ddl?

def ddl?() -> Boolean

Whether the query that created this data was a DDL statement.

Returns

(Boolean)

Example

require "google/cloud/bigquery"

bigquery = Google::Cloud::Bigquery.new
data = bigquery.query "CREATE TABLE my_table (x INT64)"

data.statement_type #=> "CREATE_TABLE"
data.ddl? #=> true

#ddl_operation_performed

def ddl_operation_performed() -> String, nil

The DDL operation performed, possibly dependent on the pre-existence of the DDL target. (See #ddl_target_table.) Possible values (new values might be added in the future):

"CREATE": The query created the DDL target.
"SKIP": No-op. Example cases: the query is CREATE TABLE IF NOT EXISTS while the table already exists, or the query is DROP TABLE IF EXISTS while the table does not exist.
"REPLACE": The query replaced the DDL target. Example case: the query is CREATE OR REPLACE TABLE, and the table already exists.
"DROP": The query deleted the DDL target.

Returns

(String, nil) — The DDL operation performed.

#ddl_target_routine

def ddl_target_routine() -> Google::Cloud::Bigquery::Routine, nil

The DDL target routine, in reference state. (See Routine#reference?.) Present only for CREATE/DROP FUNCTION/PROCEDURE queries. (See #statement_type.)

Returns

(Google::Cloud::Bigquery::Routine, nil) — The DDL target routine, in reference state.

#ddl_target_table

def ddl_target_table() -> Google::Cloud::Bigquery::Table, nil

The DDL target table, in reference state. (See Table#reference?.) Present only for CREATE/DROP TABLE/VIEW queries. (See #statement_type.)

Returns

(Google::Cloud::Bigquery::Table, nil) — The DDL target table, in reference state.

#deleted_row_count

def deleted_row_count() -> Integer, nil

The number of deleted rows. Present only for DML statements DELETE, MERGE and TRUNCATE. (See #statement_type.)

Returns

(Integer, nil) — The number of deleted rows, or nil if not applicable.

#dml?

def dml?() -> Boolean

Whether the query that created this data was a DML statement.

Returns

(Boolean)

Example

require "google/cloud/bigquery"

bigquery = Google::Cloud::Bigquery.new
data = bigquery.query "UPDATE my_table " \
                      "SET x = x + 1 " \
                      "WHERE x IS NOT NULL"

data.statement_type #=> "UPDATE"
data.dml? #=> true

#etag

def etag() -> String

An ETag hash for the page of results represented by the data instance.

Returns

(String) — The ETag hash.

#fields

def fields() -> Array<Schema::Field>

The fields of the data, obtained from the schema of the table from which the data was read.

Returns

(Array<Schema::Field>) — An array of field objects.

Example

require "google/cloud/bigquery"

bigquery = Google::Cloud::Bigquery.new
dataset = bigquery.dataset "my_dataset"
table = dataset.table "my_table"

data = table.data

data.fields.each do |field|
  puts field.name
end

#headers

def headers() -> Array<Symbol>

The names of the columns in the data, obtained from the schema of the table from which the data was read.

Returns

(Array<Symbol>) — An array of column names.

Example

require "google/cloud/bigquery"

bigquery = Google::Cloud::Bigquery.new
dataset = bigquery.dataset "my_dataset"
table = dataset.table "my_table"

data = table.data

data.headers.each do |header|
  puts header
end

#inserted_row_count

def inserted_row_count() -> Integer, nil

The number of inserted rows. Present only for DML statements INSERT and MERGE. (See #statement_type.)

Returns

(Integer, nil) — The number of inserted rows, or nil if not applicable.

#kind

def kind() -> String

The resource type of the API response.

Returns

(String) — The resource type.

#next

def next() -> Data

Retrieves the next page of data.

Returns

(Data) — A new instance providing the next page of data.

Example

require "google/cloud/bigquery"

bigquery = Google::Cloud::Bigquery.new

sql = "SELECT word FROM `bigquery-public-data.samples.shakespeare`"
job = bigquery.query_job sql

job.wait_until_done!
data = job.data

data.count # 100000
data.total # 164656

# Iterate over the first page of results
data.each do |row|
  puts row[:word]
end
# Retrieve the next page of results
data = data.next if data.next?

#next?

def next?() -> Boolean

Whether there is a next page of data.

Returns

(Boolean) — true when there is a next page, false otherwise.

Example

require "google/cloud/bigquery"

bigquery = Google::Cloud::Bigquery.new

sql = "SELECT word FROM `bigquery-public-data.samples.shakespeare`"
job = bigquery.query_job sql

job.wait_until_done!
data = job.data

data.count # 100000
data.total # 164656

# Iterate over the first page of results
data.each do |row|
  puts row[:word]
end
# Retrieve the next page of results
data = data.next if data.next?

#num_dml_affected_rows

def num_dml_affected_rows() -> Integer, nil

The number of rows affected by a DML statement. Present only for DML statements INSERT, UPDATE or DELETE. (See #statement_type.)

Returns

(Integer, nil) — The number of rows affected by a DML statement, or nil if the query is not a DML statement.

#param_types

def param_types() -> Hash

The types of the fields in the data, obtained from the schema of the table from which the data was read. Types use the same format as the optional query parameter types.

Returns

(Hash) — A hash with field names as keys, and types as values.

Example

require "google/cloud/bigquery"

bigquery = Google::Cloud::Bigquery.new
dataset = bigquery.dataset "my_dataset"
table = dataset.table "my_table"

data = table.data

data.param_types

#schema

def schema() -> Schema

The schema of the table from which the data was read.

The returned object is frozen and changes are not allowed. Use Table#schema to update the schema.

Returns

(Schema) — A schema object.

Example

require "google/cloud/bigquery"

bigquery = Google::Cloud::Bigquery.new
dataset = bigquery.dataset "my_dataset"
table = dataset.table "my_table"

data = table.data

schema = data.schema
field = schema.field "name"
field.required? #=> true

#statement_type

def statement_type() -> String, nil

The type of query statement, if valid. Possible values (new values might be added in the future):

"ALTER_TABLE": DDL statement, see Using Data Definition Language Statements
"CREATE_MODEL": DDL statement, see Using Data Definition Language Statements
"CREATE_TABLE": DDL statement, see Using Data Definition Language Statements
"CREATE_TABLE_AS_SELECT": DDL statement, see Using Data Definition Language Statements
"CREATE_VIEW": DDL statement, see Using Data Definition Language Statements
"DELETE": DML statement, see Data Manipulation Language Syntax
"DROP_MODEL": DDL statement, see Using Data Definition Language Statements
"DROP_TABLE": DDL statement, see Using Data Definition Language Statements
"DROP_VIEW": DDL statement, see Using Data Definition Language Statements
"INSERT": DML statement, see Data Manipulation Language Syntax
"MERGE": DML statement, see Data Manipulation Language Syntax
"SELECT": SQL query, see Standard SQL Query Syntax
"UPDATE": DML statement, see Data Manipulation Language Syntax

Returns

(String, nil) — The type of query statement.

#token

def token() -> String

A token used for paging results. Used by the data instance to retrieve subsequent pages. See #next.

Returns

(String) — The pagination token.

#total

def total() -> Integer

The total number of rows in the complete table.

Returns

(Integer) — The number of rows.

Example

require "google/cloud/bigquery"

bigquery = Google::Cloud::Bigquery.new

sql = "SELECT word FROM `bigquery-public-data.samples.shakespeare`"
job = bigquery.query_job sql

job.wait_until_done!
data = job.data

data.count # 100000
data.total # 164656

# Iterate over the first page of results
data.each do |row|
  puts row[:word]
end
# Retrieve the next page of results
data = data.next if data.next?

#updated_row_count

def updated_row_count() -> Integer, nil

The number of updated rows. Present only for DML statements UPDATE and MERGE. (See #statement_type.)

Returns

(Integer, nil) — The number of updated rows, or nil if not applicable.