BigQuery API - Class Google::Cloud::Bigquery::Schema::Field (v1.50.0)

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

Schema Field

The fields of a table schema.

Inherits

Object

Example

require "google/cloud/bigquery"

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

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

Methods

#bignumeric

def bignumeric(name, description: nil, mode: :nullable, policy_tags: nil, precision: nil, scale: nil)

Adds a bignumeric number field to the schema. BIGNUMERIC is a decimal type with fixed precision and scale. Precision is the number of digits that the number contains. Scale is how many of these digits appear after the decimal point. It supports:

Precision: 76.76 (the 77th digit is partial) Scale: 38 Min: -5.7896044618658097711785492504343953926634992332820282019728792003956564819968E+38 Max: 5.7896044618658097711785492504343953926634992332820282019728792003956564819967E+38

This type can represent decimal fractions exactly, and is suitable for financial calculations.

This can only be called on fields that are of type RECORD.

Parameters

name (String) — The field name. The name must contain only letters ([A-Za-z]), numbers ([0-9]), or underscores (_), and must start with a letter or underscore. The maximum length is 128 characters.
description (String) (defaults to: nil) — A description of the field.
mode (Symbol) (defaults to: :nullable) — The field's mode. The possible values are :nullable, :required, and :repeated. The default value is :nullable.
policy_tags (Array<String>, String) (defaults to: nil) — The policy tag list or single policy tag for the field. Policy tag identifiers are of the form projects/*/locations/*/taxonomies/*/policyTags/*. At most 1 policy tag is currently allowed.
precision (Integer) (defaults to: nil) — The precision (maximum number of total digits) for the field. Acceptable values for precision must be: 1 ≤ (precision - scale) ≤ 38. Values for scale must be: 0 ≤ scale ≤ 38. If the scale value is set, the precision value must be set as well.
scale (Integer) (defaults to: nil) — The scale (maximum number of digits in the fractional part) for the field. Acceptable values for precision must be: 1 ≤ (precision - scale) ≤ 38. Values for scale must be: 0 ≤ scale ≤ 38. If the scale value is set, the precision value must be set as well.

#bignumeric?

def bignumeric?() -> Boolean

Checks if the type of the field is BIGNUMERIC.

Returns

(Boolean) — true when BIGNUMERIC, false otherwise.

#boolean

def boolean(name, description: nil, mode: :nullable, policy_tags: nil)

Adds a boolean field to the nested schema of a record field.

This can only be called on fields that are of type RECORD.

Parameters

name (String) — The field name. The name must contain only letters ([A-Za-z]), numbers ([0-9]), or underscores (_), and must start with a letter or underscore. The maximum length is 128 characters.
description (String) (defaults to: nil) — A description of the field.
mode (Symbol) (defaults to: :nullable) — The field's mode. The possible values are :nullable, :required, and :repeated. The default value is :nullable.
policy_tags (Array<String>, String) (defaults to: nil) — The policy tag list or single policy tag for the field. Policy tag identifiers are of the form projects/*/locations/*/taxonomies/*/policyTags/*. At most 1 policy tag is currently allowed.

#boolean?

def boolean?() -> Boolean

Checks if the type of the field is BOOLEAN.

Returns

(Boolean) — true when BOOLEAN, false otherwise.

#bytes

def bytes(name, description: nil, mode: :nullable, policy_tags: nil, max_length: nil)

Adds a bytes field to the nested schema of a record field.

This can only be called on fields that are of type RECORD.

Parameters

name (String) — The field name. The name must contain only letters ([A-Za-z]), numbers ([0-9]), or underscores (_), and must start with a letter or underscore. The maximum length is 128 characters.
description (String) (defaults to: nil) — A description of the field.
mode (Symbol) (defaults to: :nullable) — The field's mode. The possible values are :nullable, :required, and :repeated. The default value is :nullable.
policy_tags (Array<String>, String) (defaults to: nil) — The policy tag list or single policy tag for the field. Policy tag identifiers are of the form projects/*/locations/*/taxonomies/*/policyTags/*. At most 1 policy tag is currently allowed.
max_length (Integer) (defaults to: nil) — The maximum the maximum number of bytes in the field.

#bytes?

def bytes?() -> Boolean

Checks if the type of the field is BYTES.

Returns

(Boolean) — true when BYTES, false otherwise.

#date

def date(name, description: nil, mode: :nullable, policy_tags: nil)

Adds a date field to the nested schema of a record field.

This can only be called on fields that are of type RECORD.

Parameters

name (String) — The field name. The name must contain only letters ([A-Za-z]), numbers ([0-9]), or underscores (_), and must start with a letter or underscore. The maximum length is 128 characters.
description (String) (defaults to: nil) — A description of the field.
mode (Symbol) (defaults to: :nullable) — The field's mode. The possible values are :nullable, :required, and :repeated. The default value is :nullable.
policy_tags (Array<String>, String) (defaults to: nil) — The policy tag list or single policy tag for the field. Policy tag identifiers are of the form projects/*/locations/*/taxonomies/*/policyTags/*. At most 1 policy tag is currently allowed.

#date?

def date?() -> Boolean

Checks if the type of the field is DATE.

Returns

(Boolean) — true when DATE, false otherwise.

#datetime

def datetime(name, description: nil, mode: :nullable, policy_tags: nil)

Adds a datetime field to the nested schema of a record field.

This can only be called on fields that are of type RECORD.

Parameters

name (String) — The field name. The name must contain only letters ([A-Za-z]), numbers ([0-9]), or underscores (_), and must start with a letter or underscore. The maximum length is 128 characters.
description (String) (defaults to: nil) — A description of the field.
mode (Symbol) (defaults to: :nullable) — The field's mode. The possible values are :nullable, :required, and :repeated. The default value is :nullable.
policy_tags (Array<String>, String) (defaults to: nil) — The policy tag list or single policy tag for the field. Policy tag identifiers are of the form projects/*/locations/*/taxonomies/*/policyTags/*. At most 1 policy tag is currently allowed.

#datetime?

def datetime?() -> Boolean

Checks if the type of the field is DATETIME.

Returns

(Boolean) — true when DATETIME, false otherwise.

#default_value_expression

def default_value_expression() -> String

The default value of a field using a SQL expression. It can only be set for top level fields (columns). Default value for the entire struct or array is set using a struct or array expression. The valid SQL expressions are:

Literals for all data types, including STRUCT and ARRAY.
The following functions: CURRENT_TIMESTAMP CURRENT_TIME CURRENT_DATE CURRENT_DATETIME GENERATE_UUID RAND SESSION_USER ST_GEOPOINT
Struct or array composed with the above allowed functions, for example: "[CURRENT_DATE(), DATE '2020-01-01'"]

Returns

(String) — The default value expression of the field.

#default_value_expression=

def default_value_expression=(default_value_expression)

Updates the default value expression of the field.

Parameter

default_value_expression (String) —
The default value of a field using a SQL expression. It can only be set for top level fields (columns). Use a struct or array expression to specify default value for the entire struct or array. The valid SQL expressions are:
- Literals for all data types, including STRUCT and ARRAY.
- The following functions: CURRENT_TIMESTAMP CURRENT_TIME CURRENT_DATE CURRENT_DATETIME GENERATE_UUID RAND SESSION_USER ST_GEOPOINT
- Struct or array composed with the above allowed functions, for example: "[CURRENT_DATE(), DATE '2020-01-01'"]

#description

def description() -> String

The description of the field.

Returns

(String) — The field description. The maximum length is 1,024 characters.

#description=

def description=(new_description)

Updates the description of the field.

Parameter

new_description (String) — The field description. The maximum length is 1,024 characters.

#field

def field(name) -> Field, nil

Retrieve a nested field by name, if the type property is set to RECORD. Will return nil otherwise.

Yields

Returns

(Field, nil) — The nested schema field object, or nil.

#fields

def fields() -> Array<Field>, nil

The nested fields if the type property is set to RECORD. Will be empty otherwise.

Returns

(Array<Field>, nil) — The nested schema fields if the type is set to RECORD.

#float

def float(name, description: nil, mode: :nullable, policy_tags: nil)

Adds a floating-point number field to the nested schema of a record field.

This can only be called on fields that are of type RECORD.

Parameters

name (String) — The field name. The name must contain only letters ([A-Za-z]), numbers ([0-9]), or underscores (_), and must start with a letter or underscore. The maximum length is 128 characters.
description (String) (defaults to: nil) — A description of the field.
mode (Symbol) (defaults to: :nullable) — The field's mode. The possible values are :nullable, :required, and :repeated. The default value is :nullable.
policy_tags (Array<String>, String) (defaults to: nil) — The policy tag list or single policy tag for the field. Policy tag identifiers are of the form projects/*/locations/*/taxonomies/*/policyTags/*. At most 1 policy tag is currently allowed.

#float?

def float?() -> Boolean

Checks if the type of the field is FLOAT.

Returns

(Boolean) — true when FLOAT, false otherwise.

#geography

def geography(name, description: nil, mode: :nullable, policy_tags: nil)

Adds a geography field to the nested schema of a record field.

Parameters

name (String) — The field name. The name must contain only letters ([A-Za-z]), numbers ([0-9]), or underscores (_), and must start with a letter or underscore. The maximum length is 128 characters.
description (String) (defaults to: nil) — A description of the field.
mode (Symbol) (defaults to: :nullable) — The field's mode. The possible values are :nullable, :required, and :repeated. The default value is :nullable.
policy_tags (Array<String>, String) (defaults to: nil) — The policy tag list or single policy tag for the field. Policy tag identifiers are of the form projects/*/locations/*/taxonomies/*/policyTags/*. At most 1 policy tag is currently allowed.

#geography?

def geography?() -> Boolean

Checks if the type of the field is GEOGRAPHY.

Returns

(Boolean) — true when GEOGRAPHY, false otherwise.

#headers

def headers() -> Array<Symbol>, nil

The names of the nested fields as symbols if the type property is set to RECORD. Will be empty otherwise.

Returns

(Array<Symbol>, nil) — The names of the nested schema fields if the type is set to RECORD.

#integer

def integer(name, description: nil, mode: :nullable, policy_tags: nil)

Adds an integer field to the nested schema of a record field.

This can only be called on fields that are of type RECORD.

Parameters

name (String) — The field name. The name must contain only letters ([A-Za-z]), numbers ([0-9]), or underscores (_), and must start with a letter or underscore. The maximum length is 128 characters.
description (String) (defaults to: nil) — A description of the field.
mode (Symbol) (defaults to: :nullable) — The field's mode. The possible values are :nullable, :required, and :repeated. The default value is :nullable.
policy_tags (Array<String>, String) (defaults to: nil) — The policy tag list or single policy tag for the field. Policy tag identifiers are of the form projects/*/locations/*/taxonomies/*/policyTags/*. At most 1 policy tag is currently allowed.

#integer?

def integer?() -> Boolean

Checks if the type of the field is INTEGER.

Returns

(Boolean) — true when INTEGER, false otherwise.

#json

def json(name, description: nil, mode: :nullable, policy_tags: nil)

Adds a json field to the nested schema of a record field.

https://cloud.google.com/bigquery/docs/reference/standard-sql/data-types#json_type

Parameters

name (String) — The field name. The name must contain only letters (a-z, A-Z), numbers (0-9), or underscores (_), and must start with a letter or underscore. The maximum length is 128 characters.
description (String) (defaults to: nil) — A description of the field.
mode (Symbol) (defaults to: :nullable) — The field's mode. The possible values are :nullable, :required, and :repeated. The default value is :nullable.
policy_tags (Array<String>, String) (defaults to: nil) — The policy tag list or single policy tag for the field. Policy tag identifiers are of the form projects/*/locations/*/taxonomies/*/policyTags/*. At most 1 policy tag is currently allowed.

#json?

def json?() -> Boolean

Checks if the type of the field is JSON.

Returns

(Boolean) — true when JSON, false otherwise.

#max_length

def max_length() -> Integer, nil

The maximum length of values of this field for #string? or #bytes? fields. If max_length is not specified, no maximum length constraint is imposed on this field. If type = STRING, then max_length represents the maximum UTF-8 length of strings in this field. If type = BYTES, then max_length represents the maximum number of bytes in this field.

Returns

(Integer, nil) — The maximum length of values of this field, or nil.

#mode

def mode() -> String

The mode of the field.

Returns

(String) — The field mode. Possible values include NULLABLE, REQUIRED and REPEATED. The default value is NULLABLE.

#mode=

def mode=(new_mode)

Updates the mode of the field.

Parameter

new_mode (String) — The field mode. Possible values include NULLABLE, REQUIRED and REPEATED. The default value is NULLABLE.

#name

def name() -> String

The name of the field.

Returns

(String) — The field name. The name must contain only letters ([A-Za-z]), numbers ([0-9]), or underscores (_), and must start with a letter or underscore. The maximum length is 128 characters.

#name=

def name=(new_name)

Updates the name of the field.

Parameter

new_name (String) — The field name. The name must contain only letters ([A-Za-z]), numbers ([0-9]), or underscores (_), and must start with a letter or underscore. The maximum length is 128 characters.

#nullable?

def nullable?() -> Boolean

Checks if the type of the field is NULLABLE.

Returns

(Boolean) — true when NULLABLE, false otherwise.

#numeric

def numeric(name, description: nil, mode: :nullable, policy_tags: nil, precision: nil, scale: nil)

Adds a numeric number field to the schema. NUMERIC is a decimal type with fixed precision and scale. Precision is the number of digits that the number contains. Scale is how many of these digits appear after the decimal point. It supports:

Precision: 38 Scale: 9 Min: -9.9999999999999999999999999999999999999E+28 Max: 9.9999999999999999999999999999999999999E+28

This type can represent decimal fractions exactly, and is suitable for financial calculations.

This can only be called on fields that are of type RECORD.

Parameters

name (String) — The field name. The name must contain only letters ([A-Za-z]), numbers ([0-9]), or underscores (_), and must start with a letter or underscore. The maximum length is 128 characters.
description (String) (defaults to: nil) — A description of the field.
mode (Symbol) (defaults to: :nullable) — The field's mode. The possible values are :nullable, :required, and :repeated. The default value is :nullable.
policy_tags (Array<String>, String) (defaults to: nil) — The policy tag list or single policy tag for the field. Policy tag identifiers are of the form projects/*/locations/*/taxonomies/*/policyTags/*. At most 1 policy tag is currently allowed.
precision (Integer) (defaults to: nil) — The precision (maximum number of total digits) for the field. Acceptable values for precision must be: 1 ≤ (precision - scale) ≤ 29. Values for scale must be: 0 ≤ scale ≤ 9. If the scale value is set, the precision value must be set as well.
scale (Integer) (defaults to: nil) — The scale (maximum number of digits in the fractional part) for the field. Acceptable values for precision must be: 1 ≤ (precision - scale) ≤ 29. Values for scale must be: 0 ≤ scale ≤ 9. If the scale value is set, the precision value must be set as well.

#numeric?

def numeric?() -> Boolean

Checks if the type of the field is NUMERIC.

Returns

(Boolean) — true when NUMERIC, false otherwise.

#param_type

def param_type() -> Symbol, Array, Hash

The types of the field, using the same format as the optional query parameter types.

The parameter types are one of the following BigQuery type codes:

:BOOL
:INT64
:FLOAT64
:NUMERIC
:BIGNUMERIC
:STRING
:DATETIME
:DATE
:TIMESTAMP
:TIME
:BYTES
Array - Lists are specified by providing the type code in an array. For example, an array of integers are specified as [:INT64].
Hash - Types for STRUCT values (Hash objects) are specified using a Hash object, where the keys are the nested field names, and the values are the the nested field types.

Returns

(Symbol, Array, Hash) — The type.

#policy_tags

def policy_tags() -> Array<String>, nil

The policy tag list for the field. Policy tag identifiers are of the form projects//locations//taxonomies//policyTags/. At most 1 policy tag is currently allowed.

Returns

(Array<String>, nil) — The policy tag list for the field, or nil.

Example

require "google/cloud/bigquery"

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

table.schema.field("age").policy_tags

#policy_tags=

def policy_tags=(new_policy_tags)

Updates the policy tag list for the field.

Parameter

new_policy_tags (Array<String>, String, nil) — The policy tag list or single policy tag for the field, or nil to remove the existing policy tags. Policy tag identifiers are of the form projects/*/locations/*/taxonomies/*/policyTags/*. At most 1 policy tag is currently allowed.

Example

require "google/cloud/bigquery"

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

policy_tag = "projects/my-project/locations/us/taxonomies/my-taxonomy/policyTags/my-policy-tag"
table.schema do |schema|
  schema.field("age").policy_tags = policy_tag
end

table.schema.field("age").policy_tags

#precision

def precision() -> Integer, nil

The precision (maximum number of total digits) for NUMERIC or BIGNUMERIC types. For #numeric? fields, acceptable values for precision must be 1 ≤ (precision - scale) ≤ 29 and values for scale must be 0 ≤ scale ≤ 9. For #bignumeric? fields, acceptable values for precision must be 1 ≤ (precision - scale) ≤ 38 and values for scale must be 0 ≤ scale ≤ 38. If the scale value is set, the precision value must be set as well.

Returns

(Integer, nil) — The precision for the field, or nil.

#record

def record(name, description: nil, mode: nil) { |nested_schema| ... }

Adds a record field to the nested schema of a record field. A block must be passed describing the nested fields of the record. For more information about nested and repeated records, see Preparing Data for BigQuery.

This can only be called on fields that are of type RECORD.

Parameters

name (String) — The field name. The name must contain only letters ([A-Za-z]), numbers ([0-9]), or underscores (_), and must start with a letter or underscore. The maximum length is 128 characters.
description (String) (defaults to: nil) — A description of the field.
mode (Symbol) (defaults to: nil) — The field's mode. The possible values are :nullable, :required, and :repeated. The default value is :nullable.

Yields

(nested_schema) — a block for setting the nested schema

Yield Parameter

nested_schema (Schema) — the object accepting the nested schema

Raises

(ArgumentError)

Example

require "google/cloud/bigquery"

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

table.schema do |schema|
  schema.string "first_name", mode: :required
  schema.record "cities_lived", mode: :repeated do |cities_lived|
    cities_lived.record "city", mode: :required do |city|
      city.string "name", mode: :required
      city.string "country", mode: :required
    end
    cities_lived.integer "number_of_years", mode: :required
  end
end

#record?

def record?() -> Boolean

Aliases

#struct?

Checks if the type of the field is RECORD.

Returns

(Boolean) — true when RECORD, false otherwise.

#repeated?

def repeated?() -> Boolean

Checks if the type of the field is REPEATED.

Returns

(Boolean) — true when REPEATED, false otherwise.

#required?

def required?() -> Boolean

Checks if the type of the field is REQUIRED.

Returns

(Boolean) — true when REQUIRED, false otherwise.

#scale

def scale() -> Integer, nil

The scale (maximum number of digits in the fractional part) for NUMERIC or BIGNUMERIC types. For #numeric? fields, acceptable values for precision must be 1 ≤ (precision - scale) ≤ 29 and values for scale must be 0 ≤ scale ≤ 9. For #bignumeric? fields, acceptable values for precision must be 1 ≤ (precision - scale) ≤ 38 and values for scale must be 0 ≤ scale ≤ 38. If the scale value is set, the precision value must be set as well.

Returns

(Integer, nil) — The scale for the field, or nil.

#string

def string(name, description: nil, mode: :nullable, policy_tags: nil, max_length: nil)

Adds a string field to the nested schema of a record field.

This can only be called on fields that are of type RECORD.

Parameters

name (String) — The field name. The name must contain only letters ([A-Za-z]), numbers ([0-9]), or underscores (_), and must start with a letter or underscore. The maximum length is 128 characters.
description (String) (defaults to: nil) — A description of the field.
mode (Symbol) (defaults to: :nullable) — The field's mode. The possible values are :nullable, :required, and :repeated. The default value is :nullable.
policy_tags (Array<String>, String) (defaults to: nil) — The policy tag list or single policy tag for the field. Policy tag identifiers are of the form projects/*/locations/*/taxonomies/*/policyTags/*. At most 1 policy tag is currently allowed.
max_length (Integer) (defaults to: nil) — The maximum UTF-8 length of strings allowed in the field.

#string?

def string?() -> Boolean

Checks if the type of the field is STRING.

Returns

(Boolean) — true when STRING, false otherwise.

#struct?

def struct?() -> Boolean

Alias Of: #record?

Checks if the type of the field is RECORD.

Returns

(Boolean) — true when RECORD, false otherwise.

#time

def time(name, description: nil, mode: :nullable, policy_tags: nil)

Adds a time field to the nested schema of a record field.

This can only be called on fields that are of type RECORD.

Parameters

name (String) — The field name. The name must contain only letters ([A-Za-z]), numbers ([0-9]), or underscores (_), and must start with a letter or underscore. The maximum length is 128 characters.
description (String) (defaults to: nil) — A description of the field.
mode (Symbol) (defaults to: :nullable) — The field's mode. The possible values are :nullable, :required, and :repeated. The default value is :nullable.
policy_tags (Array<String>, String) (defaults to: nil) — The policy tag list or single policy tag for the field. Policy tag identifiers are of the form projects/*/locations/*/taxonomies/*/policyTags/*. At most 1 policy tag is currently allowed.

#time?

def time?() -> Boolean

Checks if the type of the field is TIME.

Returns

(Boolean) — true when TIME, false otherwise.

#timestamp

def timestamp(name, description: nil, mode: :nullable, policy_tags: nil)

Adds a timestamp field to the nested schema of a record field.

This can only be called on fields that are of type RECORD.

Parameters

name (String) — The field name. The name must contain only letters ([A-Za-z]), numbers ([0-9]), or underscores (_), and must start with a letter or underscore. The maximum length is 128 characters.
description (String) (defaults to: nil) — A description of the field.
mode (Symbol) (defaults to: :nullable) — The field's mode. The possible values are :nullable, :required, and :repeated. The default value is :nullable.
policy_tags (Array<String>, String) (defaults to: nil) — The policy tag list or single policy tag for the field. Policy tag identifiers are of the form projects/*/locations/*/taxonomies/*/policyTags/*. At most 1 policy tag is currently allowed.

#timestamp?

def timestamp?() -> Boolean

Checks if the type of the field is TIMESTAMP.

Returns

(Boolean) — true when TIMESTAMP, false otherwise.

#type

def type() -> String

The data type of the field.

Returns

(String) —
The field data type. Possible values include:
- BIGNUMERIC
- BOOL
- BOOLEAN (same as BOOL)
- BYTES
- DATE
- DATETIME
- FLOAT
- FLOAT64 (same as FLOAT)
- GEOGRAPHY
- JSON
- INTEGER
- INT64 (same as INTEGER)
- NUMERIC
- RECORD (where RECORD indicates that the field contains a nested schema)
- STRING
- STRUCT (same as RECORD)
- TIME
- TIMESTAMP

#type=

def type=(new_type)

Updates the data type of the field.

Parameter

new_type (String) —
The data type. Possible values include:
- BIGNUMERIC
- BOOL
- BOOLEAN (same as BOOL)
- BYTES
- DATE
- DATETIME
- FLOAT
- FLOAT64 (same as FLOAT)
- GEOGRAPHY
- JSON
- INTEGER
- INT64 (same as INTEGER)
- NUMERIC
- RECORD (where RECORD indicates that the field contains a nested schema)
- STRING
- STRUCT (same as RECORD)
- TIME
- TIMESTAMP