Loading Avro data from Cloud Storage

Loading Avro files from Cloud Storage

Avro is an open source data format that bundles serialized data with the data's schema in the same file.

When you load Avro data from Cloud Storage, you can load the data into a new table or partition, or you can append to or overwrite an existing table or partition. When your data is loaded into BigQuery, it is converted into columnar format for Capacitor (BigQuery's storage format).

When you load data from Cloud Storage into a BigQuery table, the dataset that contains the table must be in the same regional or multi- regional location as the Cloud Storage bucket.

For information about loading Avro data from a local file, see Loading data into BigQuery from a local data source.

Advantages of Avro

Avro is the preferred format for loading data into BigQuery. Loading Avro files has the following advantages over CSV and JSON (newline delimited):

• The Avro binary format:
  • Is faster to load. The data can be read in parallel, even if the data blocks are compressed.
  • Doesn't require typing or serialization.
  • Is easier to parse because there are no encoding issues found in other formats such as ASCII.
• When you load Avro files into BigQuery, the table schema is automatically retrieved from the self-describing source data.

Avro schemas

When you load Avro files into BigQuery, the table schema is automatically retrieved using the source data. When BigQuery retrieves the schema from the source data, the alphabetically last file is used.

For example, you have the following Avro files in Cloud Storage:

gs://mybucket/00/
  a.avro
  z.avro
gs://mybucket/01/
  b.avro

This command loads all of the files in a single CLI command (as a comma-separated list), and the schema is derived from mybucket/01/b.avro:

bq load \
--source_format=AVRO \
[DATASET].[TABLE_NAME] \
"gs://mybucket/00/*.avro","gs://mybucket/01/*.avro"

When importing multiple Avro files with different Avro schemas, all schemas must be compatible with Avro's schema resolution.

When BigQuery detects the schema, some Avro data types are converted to BigQuery data types to make them compatible with BigQuery SQL syntax. For more information, see Avro conversions.

Avro compression

Compressed Avro files are not supported, but compressed data blocks are. BigQuery supports the DEFLATE and Snappy codecs.

Required permissions

When you load data into BigQuery, you need permissions to run a load job and project or dataset-level permissions that allow you to load data into new or existing BigQuery tables and partitions. If you are loading data from Cloud Storage, you also need permissions to access to the bucket that contains your data.

BigQuery permissions

If you are loading data into a new table, you must have WRITER access at the dataset level, or you must be assigned a project-level IAM role that includes bigquery.tables.create permissions.

If you are using a load job to overwrite an existing table or to append data to an existing table, you must have WRITER access at the dataset level, or you must be assigned a project-level IAM role that includes bigquery.tables.updateData permissions.

The following predefined, project-level IAM roles include both bigquery.tables.create and bigquery.tables.updateData permissions:

• bigquery.dataEditor
• bigquery.dataOwner
• bigquery.admin

In addition, because the bigquery.user role has bigquery.datasets.create permissions, a user assigned to the bigquery.user role can create and update tables in any dataset that user creates. When a user assigned to the bigquery.user role creates a dataset, that user is given OWNER access to the dataset. OWNER access to a dataset gives the user full control over it and all the tables in it.

You also need bigquery.jobs.create permissions to run the load job. The following predefined, project-level IAM roles include bigquery.jobs.create permissions:

• bigquery.user
• bigquery.jobUser
• bigquery.admin

For more information on IAM roles and permissions in BigQuery, see Access control. For more information on dataset-level roles, see Primitive roles for datasets.

Cloud Storage permissions

In order to load data from a Cloud Storage bucket, you must be granted storage.objects.get permissions at the project level or on that individual bucket. If you are using a URI wildcard, you must also have storage.objects.list permissions.

The predefined IAM role storage.objectViewer can be granted to provide both storage.objects.get and storage.objects.list permissions.

Loading Avro data into a new table

To load Avro data from Cloud Storage into a new BigQuery table, or to append Avro data to an existing table:

Console

1. Open the BigQuery web UI in the GCP Console.
   Go to the BigQuery web UI

2. In the navigation panel, in the Resources section, expand your project and select a dataset.

3. On the right side of the window, in the details panel, click Create table. The process for loading data is the same as the process for creating an empty table.

   

4. On the Create table page, in the Source section:

   • For Create table from, select Cloud Storage.

   • In the source field, browse for the File/Cloud Storage bucket, or enter the Cloud Storage URI. Note that you cannot include multiple URIs in the BigQuery web UI, but wildcards are supported. The Cloud Storage bucket must be in the same location as the dataset that contains the table you're creating.

     

   • For File format, select Avro.

5. On the Create table page, in the Destination section:

   • For Dataset name, choose the appropriate dataset.

     

   • In the Table name field, enter the name of the table you're creating in BigQuery.

   • Verify that Table type is set to Native table.

6. In the Schema section, no action is necessary. The schema is inferred from Avro files.

7. Click Create table.

Classic UI

1. Go to the BigQuery web UI.
   Go to the BigQuery web UI

2. In the navigation panel, hover on a dataset, click the down arrow icon , and click Create new table. The process for loading data is the same as the process for creating an empty table.

3. On the Create Table page, in the Source Data section:

   • For Location, select Cloud Storage and in the source field, enter the Cloud Storage URI. Note that you cannot include multiple URIs in the BigQuery web UI, but wildcards are supported. The Cloud Storage bucket must be in the same location as the dataset that contains the table you're creating.
   • For File format, select Avro.

4. On the Create Table page, in the Destination Table section:

   • For Table name, choose the appropriate dataset, and in the table name field, enter the name of the table you're creating in BigQuery.
   • Verify that Table type is set to Native table.

5. In the Schema section, no action is necessary. The schema is inferred from Avro files.

6. Click Create Table.

Command-line

Use the bq load command, specify AVRO as the source_format, and include a Cloud Storage URI. You can include a single URI, a comma-separated list of URIs or a URI containing a wildcard.

(Optional) Supply the --location flag and set the value to your location.

bq --location=[LOCATION] load \
--source_format=[FORMAT] \
[DATASET].[TABLE] \
[PATH_TO_SOURCE]

where:

• [LOCATION] is your location. The --location flag is optional. For example, if you are using BigQuery in the Tokyo region, set the flag's value to asia-northeast1. You can set a default value for the location using the .bigqueryrc file.
• [FORMAT] is AVRO.
• [DATASET] is an existing dataset.
• [TABLE] is the name of the table into which you're loading data.
• [PATH_TO_SOURCE] is a fully-qualified Cloud Storage URI or a comma-separated list of URIs. Wildcards are also supported.

Examples:

The following command loads data from gs://mybucket/mydata.avro into a table named mytable in mydataset.

    bq load \
    --source_format=AVRO \
    mydataset.mytable \
    gs://mybucket/mydata.avro

The following command loads data from multiple files in gs://mybucket/ into a table named mytable in mydataset. The Cloud Storage URI uses a wildcard.

    bq load \
    --source_format=AVRO \
    mydataset.mytable \
    gs://mybucket/mydata*.avro

The following command loads data from multiple files in gs://mybucket/ into a table named mytable in mydataset. The command includes a comma-separated list of Cloud Storage URIs with wildcards.

    bq load --autodetect \
    --source_format=AVRO \
    mydataset.mytable \
    "gs://mybucket/00/*.avro","gs://mybucket/01/*.avro"

API

Set the following properties to load Avro data using the API.

1. Create a load job that points to the source data in Cloud Storage.

2. Specify your location in the location property in the jobReference section of the job resource.

3. The sourceUris must be fully-qualified, in the format gs://[BUCKET]/[OBJECT]. Each URI can contain one '*' wildcard character.

4. Specify the Avro data format by setting the sourceFormat property to AVRO.

5. To check the job status, call jobs.get([JOB_ID]*), where [JOB_ID] is the ID of the job returned by the initial request.

   • If status.state = DONE, the job completed successfully.
   • If the status.errorResult property is present, the request failed, and that object will include information describing what went wrong. When a request fails, no table is created and no data is added.
   • If status.errorResult is absent, the job finished successfully, although there might have been some non-fatal errors, such as problems importing a few rows. Non-fatal errors are listed in the returned job object's status.errors property.

API notes:

• Load jobs are atomic and consistent; if a load job fails, none of the data is available, and if a load job succeeds, all of the data is available.

• As a best practice, generate a unique ID and pass it as jobReference.jobId when calling jobs.insert() to create a load job. This approach is more robust to network failure because the client can poll or retry on the known job ID.

• Calling jobs.insert() on a given job ID is idempotent; in other words, you can retry as many times as you like on the same job ID, and at most one of those operations will succeed.

Python

Before trying this sample, follow the Python setup instructions in the BigQuery Quickstart Using Client Libraries . For more information, see the BigQuery Python API reference documentation .

View on GitHub Feedback

# from google.cloud import bigquery
# client = bigquery.Client()
# dataset_id = 'my_dataset'

dataset_ref = client.dataset(dataset_id)
job_config = bigquery.LoadJobConfig()
job_config.source_format = bigquery.SourceFormat.AVRO
uri = "gs://cloud-samples-data/bigquery/us-states/us-states.avro"

load_job = client.load_table_from_uri(
    uri, dataset_ref.table("us_states"), job_config=job_config
)  # API request
print("Starting job {}".format(load_job.job_id))

load_job.result()  # Waits for table load to complete.
print("Job finished.")

destination_table = client.get_table(dataset_ref.table("us_states"))
print("Loaded {} rows.".format(destination_table.num_rows))

Overwriting a table with Avro data

You can load additional data into a table either from source files or by appending query results.

In the console and the classic BigQuery web UI, you use the Write preference option to specify what action to take when you load data from a source file or from a query result.

You have the following options when you load additional data into a table:

Console option	Classic UI option	CLI flag	BigQuery API property	Description
Write if empty	Write if empty	None	WRITE_EMPTY	Writes the data only if the table is empty.
Append to table	Append to table	--noreplace or --replace=false; if --[no]replace is unspecified, the default is append	WRITE_APPEND	(Default) Appends the data to the end of the table.
Overwrite table	Overwrite table	--replace or --replace=true	WRITE_TRUNCATE	Erases all existing data in a table before writing the new data.

By default, load jobs append data to a table. To overwrite table data by using a load job:

Console

1. Open the BigQuery web UI in the GCP Console.
   Go to the BigQuery web UI

2. In the navigation panel, in the Resources section, expand your project and select a dataset.

3. On the right side of the window, in the details panel, click Create table. The process for loading data is the same as the process for creating an empty table.

4. On the Create table page, in the Source section:

   • For Create table from, select Cloud Storage, and in the source field, browse for the File/Cloud Storage bucket, or enter the Cloud Storage URI. Note that you cannot include multiple URIs in the BigQuery web UI, but wildcards are supported. The Cloud Storage bucket must be in the same location as the dataset that contains the table you're creating.
   • For File format, select Avro.

5. On the Create table page, in the Destination section:

   • For Dataset name, choose the appropriate dataset, and in the Table name field, enter the name of the table you're creating in BigQuery.
   • Verify that Table type is set to Native table.

6. In the Schema section, no action is necessary. The schema is inferred from Avro files.

7. In the Advance options section, for Write preference, choose Write if empty, Append to table, or Overwrite table.

8. Click Create table.

Classic UI

1. Go to the BigQuery web UI.
   Go to the BigQuery web UI

2. In the navigation panel, hover on a dataset, click the down arrow icon , and click Create new table. The process for loading data is the same as the process for creating an empty table.

3. On the Create Table page, in the Source Data section:

   • For Location, select Cloud Storage and in the source field, enter the Cloud Storage URI. Note that you cannot include multiple URIs in the UI, but wildcards are supported. The Cloud Storage bucket must be in the same location as the dataset that contains the table you're appending or overwriting.
   • For File format, select Avro.

4. On the Create Table page, in the Destination Table section:

   • For Table name, choose the appropriate dataset, and in the table name field, enter the name of the table you're appending or overwriting.
   • Verify that Table type is set to Native table.

5. In the Schema section, no action is necessary. Schema information is inferred from Avro files.

6. In the Options section, for Write preference, choose Write if empty, Append to table, or Overwrite table.

   

7. Click Create Table.

CLI

Enter the bq load command with the --replace flag to overwrite the table. Supply the --location flag and set the value to your location. Use the --noreplace flag to append data to the table. If no flag is specified, the default is to append data.

bq --location=[LOCATION] load \
--[no]replace \
[DATASET].[TABLE] \
[PATH_TO_SOURCE]

where:

• [LOCATION] is your location. The --location flag is optional. You can set a default value for the location using the .bigqueryrc file.
• [DATASET] is an existing dataset.
• [TABLE] is the name of the table into which you're loading data.
• [PATH_TO_SOURCE] is a fully-qualified Cloud Storage URI or a comma-separated list of URIs. Wildcards are also supported.

Examples:

The following command loads data from gs://mybucket/mydata.avro and overwrites a table named mytable in mydataset.

    bq load --replace \
    --source_format=AVRO \
    mydataset.mytable \
    gs://mybucket/mydata.avro

The following command loads data from gs://mybucket/mydata.avro and appends data to a table named mytable in mydataset.

    bq load --noreplace \
    --source_format=AVRO \
    mydataset.mytable \
    gs://mybucket/mydata.avro

API

Set the following properties to load CSV data using the API.

1. Create a load job that points to the source data in Cloud Storage.

2. Specify your location in the location property in the jobReference section of the job resource.

3. The sourceUris must be fully-qualified, in the format gs://[BUCKET]/[OBJECT]. You can include multiple URIs as a comma-separated list. Note that wildcards are also supported when loading CSV data from Cloud Storage.

4. Specify the data format by setting the sourceFormat property to AVRO.

5. Specify the write preference by setting the writeDisposition property to WRITE_TRUNCATE, WRITE_APPEND, or WRITE_EMPTY.

Python

Before trying this sample, follow the Python setup instructions in the BigQuery Quickstart Using Client Libraries . For more information, see the BigQuery Python API reference documentation .

View on GitHub Feedback

# from google.cloud import bigquery
# client = bigquery.Client()
# table_ref = client.dataset('my_dataset').table('existing_table')

job_config = bigquery.LoadJobConfig()
job_config.write_disposition = bigquery.WriteDisposition.WRITE_TRUNCATE
job_config.source_format = bigquery.SourceFormat.AVRO
uri = "gs://cloud-samples-data/bigquery/us-states/us-states.avro"
load_job = client.load_table_from_uri(
    uri, table_ref, job_config=job_config
)  # API request
print("Starting job {}".format(load_job.job_id))

load_job.result()  # Waits for table load to complete.
print("Job finished.")

destination_table = client.get_table(table_ref)
print("Loaded {} rows.".format(destination_table.num_rows))

Avro conversions

BigQuery converts Avro data types to the following BigQuery data types:

Primitive types

Avro data type	BigQuery data type	Notes
null	BigQuery ignores these values
boolean	BOOLEAN
int	INTEGER
long	INTEGER
float	FLOAT
double	FLOAT
bytes	BYTES
bytes with a decimal logical type	NUMERIC
string	STRING	UTF-8 only

Complex types

Avro data type	BigQuery data type	Notes
record	RECORD	Aliases are ignored Doc is converted into a field description Default values are set at read time Order is ignored Recursive fields are dropped — Only the first level of nesting is maintained for recursive fields
enum	STRING	The string is the symbolic value of the enum Aliases are ignored Doc is converted into a field description
array	repeated fields	Arrays of arrays are not supported. Arrays containing only NULL types are ignored.
map<T>	RECORD	BigQuery converts an Avro map<T> field to a repeated RECORD that contains two fields: a key and a value. BigQuery stores the key as a STRING, and converts the value to its corresponding data type in BigQuery.
union	Nullable field RECORD with a list of nullable fields	When union only has one non-null type, it converts to a nullable field. Otherwise it converts to a RECORD with a list of nullable fields. Only one of these fields will be set at read time.
fixed	BYTES	Aliases are ignored Size is ignored

Logical types

By default, BigQuery ignores the logicalType attribute and uses the underlying Avro type instead.

Avro logical type	BigQuery data type
date	INTEGER
time-millis	INTEGER
time-micros	INTEGER (converted from LONG)
timestamp-millis	INTEGER (converted from LONG)
timestamp-micros	INTEGER (converted from LONG)
duration	BYTES (converted from fixed type of size 12)
decimal	NUMERIC (see Decimal logical type)

To enable the conversion of Avro logical types to their corresponding BigQuery data types, set the --use_avro_logical_types flag to True using the command-line tool, or set the useAvroLogicalTypes property in the job resource when you call the jobs.insert method to create a load job.

The table below shows the conversion of Avro logical types to BigQuery data types.

Avro logical type	Converted BigQuery data type
date	DATE
time-millis	TIME
time-micros	TIME
timestamp-millis	TIMESTAMP
timestamp-micros	TIMESTAMP
duration	BYTES (converted from fixed type of size 12)
decimal	NUMERIC (see Decimal logical type)

For more information on Avro data types, see the Apache Avro™ 1.8.2 Specification.

Decimal logical type

An Avro bytes type with a decimal logical type may have at most a precision of 38 (total number of digits) and at most a scale of 9 (digits to the right of the decimal). The number of integer digits, which is the precision minus the scale, may be at most 29. For example, a decimal with a precision of 38 and a scale of 9 is supported because the number of integer digits is 29. A decimal with a precision of 38 and a scale of 5 is not supported because the number of integer digits is 33.

When you load an Avro file containing a bytes column with the decimal logical type into an existing table, the column's data type in the table's schema definition may be either BYTES or NUMERIC. If the column's data type is BYTES, the decimal logical type on the column in the Avro file is ignored.

For more information on the Avro decimal logical type, see the Apache Avro™ 1.8.2 Specification.