Python 專用的 BigQuery 用戶端程式庫 v0.28，包含針對舊版用戶端程式庫 v0.27 以下版本的設計所做出的一些重大變更。以下是摘要說明：
- 查詢與檢視表操作預設採用標準 SQL 方言。
- 如執行查詢等與工作相關的用戶端功能會立即啟動工作。
- 建立、取得、更新、刪除資料集與資料表的功能已移至用戶端類別。
這個主題提供您需要對 BigQuery 用戶端程式庫的 Python 程式碼進行變更，才能使用最新版本 Python 用戶端程式庫的詳細資訊。
執行舊版用戶端程式庫
您不需要將 Python 用戶端程式碼更新至最新版本。但是，只有 v0.28 以上版本中才支援 BigQuery API 中的新功能。
如果您要繼續使用舊版 Python 用戶端程式庫，而且不想遷移程式碼，請指定應用程式使用的 Python 用戶端程式庫版本。如要指定特定的程式庫版本，請編輯 requirements.txt 檔案，如以下範例所示：
google-cloud-bigquery==0.27
執行最新版本的用戶端程式庫。
如要安裝最新版本的 Python 用戶端程式庫，請使用 pip 指令。
pip install --upgrade google-cloud-bigquery
如需詳細指示，請參閱 BigQuery 用戶端程式庫。
匯入程式庫並建立用戶端
匯入 Python 用戶端並建立用戶端物件的動作在舊版與新版程式庫中是相同的。
from google.cloud import bigquery
client = bigquery.Client()
查詢程式碼變更
使用標準 SQL 方言查詢資料
v0.28 與更新版本中的變更包括：
- 標準 SQL 是預設 SQL 方言。
- 使用
QueryJobConfig類別來設定查詢工作。 client.query()可提出立即啟動查詢的 API 要求。- 工作 ID 是選用的。若未提供，用戶端程式庫會為您產生一個 工作 ID。
以下範例顯示如何執行查詢。
舊版用戶端程式庫：
client = bigquery.Client()
query_job = client.run_async_query(str(uuid.uuid4()), query)
# Use standard SQL syntax.
query_job.use_legacy_sql = False
# Set a destination table.
dest_dataset = client.dataset(dest_dataset_id)
dest_table = dest_dataset.table(dest_table_id)
query_job.destination = dest_table
# Allow the results table to be overwritten.
query_job.write_disposition = 'WRITE_TRUNCATE'
query_job.begin()
query_job.result() # Wait for query to finish.
rows = query_job.query_results().fetch_data()
for row in rows:
print(row)
在 0.25.0 或更早版本的 google-cloud-bigquery 程式庫中，等待工作物件完成並不需要 job.result()，而是需要下列程式碼：
while True:
job.reload() # Refreshes the state via a GET request.
if job.state == 'DONE':
if job.error_result:
raise RuntimeError(job.errors)
return
time.sleep(1)
在 0.25.0 或更早版本的 google-cloud-bigquery 程式庫中，不會使用 job.query_results().fetch_data() 來取得結果資料列，而是會使用下列程式碼：
rows = query_job.results().fetch_data()
最新版本的用戶端程式庫：
根據預設，Python 用戶端程式庫現在使用標準 SQL。
Python
在嘗試這個範例之前，請先按照 BigQuery 快速入門導覽課程：使用用戶端程式庫中的 Python 設定操作說明來進行。詳情請參閱 BigQuery Python API 參考資料說明文件。
如需使用最新 Python 用戶端程式庫版本執行查詢的更多範例，請參閱：
將查詢結果下載為 pandas DataFrame
以下範例顯示如何執行查詢並將結果下載為 pandas DataFrame。
舊版用戶端程式庫：
舊版用戶端程式庫不支援將結果下載至 pandas DataFrame。
最新版本的用戶端程式庫：
Python
在嘗試這個範例之前，請先按照 BigQuery 快速入門導覽課程：使用用戶端程式庫中的 Python 設定操作說明來進行。詳情請參閱 BigQuery Python API 參考資料說明文件。
使用舊版 SQL 方言查詢資料
以下範例顯示如何使用舊版 SQL 方言執行查詢：
舊版用戶端程式庫：
舊版用戶端程式庫預設使用舊版 SQL 語法。如要瞭解如何設定及執行查詢，請參閱查詢範例。
最新版本的用戶端程式庫：
用戶端程式庫預設使用標準 SQL 語法。將 use_legacy_sql 設為 true 即可使用舊版 SQL。如要瞭解如何設定及執行查詢，請參閱查詢範例。
同步查詢資料
在 v0.28 與更新版本中建議使用 Client.query() 方法，因為這個方法可以存取 QueryJob 中的統計資料和查詢的其他屬性。
舊版用戶端程式庫：
query_results = client.run_sync_query(query)
query_results.use_legacy_sql = False
query_results.run()
# The query might not complete in a single request. To account for a
# long-running query, force the query results to reload until the query
# is complete.
while not query_results.complete:
query_iterator = query_results.fetch_data()
try:
six.next(iter(query_iterator))
except StopIteration:
pass
rows = query_results.fetch_data()
for row in rows:
print(row)
最新版本的用戶端程式庫：
Python
在嘗試這個範例之前，請先按照 BigQuery 快速入門導覽課程：使用用戶端程式庫中的 Python 設定操作說明來進行。詳情請參閱 BigQuery Python API 參考資料說明文件。
資料表程式碼變更
資料表參照
使用 TableReference 物件來參照沒有其他屬性的資料表，並使用 Table 來參照完整資料表資源。之前使用 Table 類別的數個屬性，現在都使用 v0.28 與更新版本中的 TableReference 類別。例如：
QueryJob.destination現在是TableReference。client.dataset('mydataset').table('mytable')現在會傳回TableReference。
如需同時使用 TableReference 和 Table 類別的範例，請參閱如何建立資料表。
從本機檔案載入資料
以下範例顯示如何將本機檔案載入到 BigQuery 資料表。
舊版用戶端程式庫：
dataset = client.dataset(dataset_name)
table = dataset.table(table_name)
# Reload the table to get the schema.
table.reload()
with open(source_file_name, 'rb') as source_file:
# This example uses CSV, but you can use other formats.
# See https://cloud.google.com/bigquery/loading-data
job = table.upload_from_file(
source_file, source_format='text/csv')
# Wait for the load job to complete.
while True:
job.reload()
if job.state == 'DONE':
if job.error_result:
raise RuntimeError(job.errors)
return
time.sleep(1)
最新版本的用戶端程式庫：
Python
在嘗試這個範例之前，請先按照 BigQuery 快速入門導覽課程：使用用戶端程式庫中的 Python 設定操作說明來進行。詳情請參閱 BigQuery Python API 參考資料說明文件。
詳情請參閱從本機資料來源載入資料。
從 pandas DataFrame 載入資料
以下範例說明如何將 pandas DataFrame 上傳到 BigQuery 資料表。
舊版用戶端程式庫：
舊版用戶端程式庫不支援從 pandas DataFrame 上傳資料。
最新版本的用戶端程式庫：
Python
在嘗試這個範例之前，請先按照 BigQuery 快速入門導覽課程：使用用戶端程式庫中的 Python 設定操作說明來進行。詳情請參閱 BigQuery Python API 參考資料說明文件。
從 Cloud Storage 載入資料
下列範例說明如何將檔案從 Cloud Storage 載入到 BigQuery 表格。
舊版用戶端程式庫：
dataset = client.dataset(dataset_name)
table = dataset.table(table_name)
job_id = str(uuid.uuid4())
job = client.load_table_from_storage(
job_id, table, 'gs://bucket_name/object_name')
job.begin()
# Wait for the load job to complete.
while True:
job.reload()
if job.state == 'DONE':
if job.error_result:
raise RuntimeError(job.errors)
return
time.sleep(1)
最新版本的用戶端程式庫：
Python
在嘗試這個範例之前，請先按照 BigQuery 快速入門導覽課程：使用用戶端程式庫中的 Python 設定操作說明來進行。詳情請參閱 BigQuery Python API 參考資料說明文件。
詳情請參閱從 Cloud Storage 載入資料。
將資料表擷取至 Cloud Storage
下列範例說明如何將資料表擷取至 Cloud Storage：
舊版用戶端程式庫：
dataset = client.dataset(dataset_name)
table = dataset.table(table_name)
job_id = str(uuid.uuid4())
job = client.extract_table_to_storage(
job_id, table, 'gs://bucket_name/object_name')
job.begin()
# Wait for the job to complete.
while True:
job.reload()
if job.state == 'DONE':
if job.error_result:
raise RuntimeError(job.errors)
return
time.sleep(1)
最新版本的用戶端程式庫：
Python
在嘗試這個範例之前，請先按照 BigQuery 快速入門導覽課程：使用用戶端程式庫中的 Python 設定操作說明來進行。詳情請參閱 BigQuery Python API 參考資料說明文件。
詳情請參閱匯出資料表資料。
複製資料表
以下範例顯示如何將資料表複製到另一個資料表。
舊版用戶端程式庫：
dataset = client.dataset(dataset_name)
table = dataset.table(table_name)
destination_table = dataset.table(new_table_name)
job_id = str(uuid.uuid4())
job = client.copy_table(job_id, destination_table, table)
job.create_disposition = (
google.cloud.bigquery.job.CreateDisposition.CREATE_IF_NEEDED)
job.begin()
# Wait for the job to complete.
while True:
job.reload()
if job.state == 'DONE':
if job.error_result:
raise RuntimeError(job.errors)
return
time.sleep(1)
最新版本的用戶端程式庫：
Python
在嘗試這個範例之前，請先按照 BigQuery 快速入門導覽課程：使用用戶端程式庫中的 Python 設定操作說明來進行。詳情請參閱 BigQuery Python API 參考資料說明文件。
詳情請參閱複製資料表。
以串流方式將資料傳入資料表
以下範例顯示如何將資料列寫入到資料表的串流緩衝區。
舊版用戶端程式庫：
dataset = client.dataset(dataset_name)
table = dataset.table(table_name)
# Reload the table to get the schema.
table.reload()
rows = [('values', 'in', 'same', 'order', 'as', 'schema')]
errors = table.insert_data(rows)
if not errors:
print('Loaded 1 row into {}:{}'.format(dataset_name, table_name))
else:
do_something_with(errors)
最新版本的用戶端程式庫：
Python
在嘗試這個範例之前，請先按照 BigQuery 快速入門導覽課程：使用用戶端程式庫中的 Python 設定操作說明來進行。詳情請參閱 BigQuery Python API 參考資料說明文件。
詳情請參閱以串流方式將資料傳入 BigQuery。
列出資料表
以下範例顯示如何列出資料集中的資料表。
舊版用戶端程式庫：
dataset = client.dataset(dataset_name)
for table in dataset.list_tables():
print(table.name)
最新版本的用戶端程式庫：
Python
在嘗試這個範例之前，請先按照 BigQuery 快速入門導覽課程：使用用戶端程式庫中的 Python 設定操作說明來進行。詳情請參閱 BigQuery Python API 參考資料說明文件。
詳情請參閱列出資料表。
取得資料表
以下範例顯示如何取得資料表。
舊版用戶端程式庫：
dataset = client.dataset(dataset_name)
table = dataset.table(table_name)
table.reload()
最新版本的用戶端程式庫：
Python
在嘗試這個範例之前，請先按照 BigQuery 快速入門導覽課程：使用用戶端程式庫中的 Python 設定操作說明來進行。詳情請參閱 BigQuery Python API 參考資料說明文件。
詳情請參閱取得資料表的相關資訊。
檢查資料表是否存在
BigQuery API 不提供原生 exists 方法。而是會取得資料表資源並檢查那個要求是否產生 404 錯誤。先前，用戶端程式庫提供 exists() 輔助函式來執行這項檢查。然而，exists() 輔助函式允許一些不太有效率的使用案例，例如在嘗試取得完整資源之前呼叫 exists()。因此，exists() 輔助函式已從用戶端程式庫中移除。
以下範例顯示如何檢查資料表是否存在。
舊版用戶端程式庫：
dataset = client.dataset(dataset_name)
table = dataset.table(table_name)
if table.exists():
# do something
else:
# do something else
最新版本的用戶端程式庫：
Python
在嘗試這個範例之前，請先按照 BigQuery 快速入門導覽課程：使用用戶端程式庫中的 Python 設定操作說明來進行。詳情請參閱 BigQuery Python API 參考資料說明文件。
建立資料表
以下範例顯示如何建立資料表。
舊版用戶端程式庫：
dataset = client.dataset(dataset_name)
table = dataset.table(table_name)
table.create()
最新版本的用戶端程式庫：
Python
在嘗試這個範例之前，請先按照 BigQuery 快速入門導覽課程：使用用戶端程式庫中的 Python 設定操作說明來進行。詳情請參閱 BigQuery Python API 參考資料說明文件。
詳情請參閱建立資料表。
更新資料表
以下範例顯示如何更新資料表。
舊版用戶端程式庫：
dataset = client.dataset(dataset_name)
table = dataset.table(table_name)
table.patch(description='new description')
請注意，舊版程式庫不會透過 etag 屬性檢查資料表資源的版本，所以讀取-修改-寫入的程序並不安全。
最新版本的用戶端程式庫：
Python
在嘗試這個範例之前，請先按照 BigQuery 快速入門導覽課程：使用用戶端程式庫中的 Python 設定操作說明來進行。詳情請參閱 BigQuery Python API 參考資料說明文件。
詳情請參閱更新資料表屬性。
刪除資料表
以下範例顯示如何刪除資料表。
舊版用戶端程式庫：
dataset = client.dataset(dataset_name)
table = dataset.table(table_name)
table.delete()
最新版本的用戶端程式庫：
Python
在嘗試這個範例之前，請先按照 BigQuery 快速入門導覽課程：使用用戶端程式庫中的 Python 設定操作說明來進行。詳情請參閱 BigQuery Python API 參考資料說明文件。
詳情請參閱刪除資料表。
資料集程式碼變更
資料集參照
使用 DatasetReference 物件來參照沒有其他屬性的資料集，並使用 Dataset 來參照完整的資料集資源。以前使用 Dataset 類別的某些方法，現在都使用 v0.28 及更高版本中的 DatasetReference 類別。例如：
client.dataset('mydataset')現在會傳回DatasetReference。
如需同時使用 DatasetReference 和 Dataset 類別的範例，請參閱如何建立資料集。
列出資料集
以下範例顯示如何列出專案中的資料集。
舊版用戶端程式庫：
for dataset in client.list_datasets():
print(dataset.name)
最新版本的用戶端程式庫：
Python
在嘗試這個範例之前，請先按照 BigQuery 快速入門導覽課程：使用用戶端程式庫中的 Python 設定操作說明來進行。詳情請參閱 BigQuery Python API 參考資料說明文件。
詳情請參閱列出資料集。
取得資料集
以下範例顯示如何取得資料集。
舊版用戶端程式庫：
dataset = client.dataset(dataset_name)
dataset.reload()
最新版本的用戶端程式庫：
Python
在嘗試這個範例之前，請先按照 BigQuery 快速入門導覽課程：使用用戶端程式庫中的 Python 設定操作說明來進行。詳情請參閱 BigQuery Python API 參考資料說明文件。
詳情請參閱取得資料集相關資訊。
檢查資料集是否存在
BigQuery API 不提供原生 exists 方法。
而是會取得資料集資源並檢查該要求是否產生 404 錯誤。先前，用戶端程式庫提供 exists() 輔助函式來執行這項檢查。然而，exists() 輔助函式允許一些不太有效率的使用案例，例如在嘗試取得完整資源之前呼叫 exists()。因此，exists() 輔助函式已從用戶端程式庫中移除。
下列範例說明如何檢查資料集是否存在。
舊版用戶端程式庫：
dataset = client.dataset(dataset_name)
if dataset.exists():
# do something
else:
# do something else
最新版本的用戶端程式庫：
Python
在嘗試這個範例之前，請先按照 BigQuery 快速入門導覽課程：使用用戶端程式庫中的 Python 設定操作說明來進行。詳情請參閱 BigQuery Python API 參考資料說明文件。
建立資料集
以下範例顯示如何建立資料集。
舊版用戶端程式庫：
dataset = client.dataset(dataset_name)
dataset.create()
最新版本的用戶端程式庫：
Python
在嘗試這個範例之前，請先按照 BigQuery 快速入門導覽課程：使用用戶端程式庫中的 Python 設定操作說明來進行。詳情請參閱 BigQuery Python API 參考資料說明文件。
詳情請參閱建立資料集。
更新資料集
以下範例顯示如何更新資料集。
舊版用戶端程式庫：
dataset = client.dataset(dataset_name)
dataset.patch(description='new description')
請注意，舊版程式庫不會透過 etag 屬性檢查資料集資源的版本，所以讀取-修改-寫入的程序並不安全。
最新版本的用戶端程式庫：
Python
在嘗試這個範例之前，請先按照 BigQuery 快速入門導覽課程：使用用戶端程式庫中的 Python 設定操作說明來進行。詳情請參閱 BigQuery Python API 參考資料說明文件。
詳情請參閱更新資料集屬性。
刪除資料集
以下範例顯示如何刪除資料集。
舊版用戶端程式庫：
dataset = client.dataset(dataset_name)
dataset.delete()
最新版本的用戶端程式庫：
Python
在嘗試這個範例之前，請先按照 BigQuery 快速入門導覽課程：使用用戶端程式庫中的 Python 設定操作說明來進行。詳情請參閱 BigQuery Python API 參考資料說明文件。
詳情請參閱刪除資料集一文。