建立與使用資料集

本文件將說明如何在 BigQuery 中建立和使用資料集。建立資料集後,您可以:

  • 指派資料集的存取權控制
  • 取得資料集相關資訊
  • 列出資料集
  • 使用中繼資料表取得資料集中繼資料

如需管理資料集的相關資訊,包括更新資料集屬性、重新命名資料集、刪除資料集,以及複製資料集,請參閱管理資料集

資料集的限制

BigQuery 資料集有下列限制:

  • 您只能在建立時設定地理位置。建立資料集後,位置會變成無法改變,而且無法在 BigQuery 網頁版 UI、指令列工具中或者透過呼叫 patchupdate API 方法進行變更。
  • 在查詢中參考的所有資料表都必須儲存在資料集中的同一個位置。

  • 複製資料表時,包含來源資料表和目標資料表的資料集必須位於同一個位置。

  • 每個專案的資料集名稱不得重複。
  • 當專案中的資料集接近數千個時,網頁版 UI 的效能會開始降低,列出資料集的速度會變慢。

建立資料集

您可以使用 BigQuery 網頁版 UI、bq mk CLI 指令或透過呼叫 datasets.insert API 方法來建立資料集。

當您在 BigQuery 中建立資料集時,每個專案的資料集名稱不得重複。資料集名稱:

  • 最多可以包含 1,024 個字元
  • 可以包含字母 (大寫或小寫)、數字和底線
  • 須區分大小寫 (mydatasetMyDataset 可以共存於同一個專案中)

資料集名稱不能:

  • 包含空格或特殊字元 (例如 -、&、@ 或 %)

所需權限

如要建立資料集,您必須取得提供 bigquery.datasets.create 權限的專案層級bigquery.datasets.create角色或預先定義的 IAM 角色。以下是擁有 bigquery.datasets.create 權限的預先定義專案層級 IAM 角色:

如要深入瞭解 BigQuery 中的 IAM 角色和權限,請參閱存取權控制

建立資料集

如何建立資料集:

網頁版 UI

  1. 在導覽列中點選專案名稱旁的向下箭號圖示 向下箭號圖示,然後按一下 [Create new dataset]

  2. 在「Create Dataset」對話方塊中:

    • 針對「Dataset ID」,輸入唯一的資料集名稱。
    • 針對「Data location」,選擇資料集的位置。預設值為「未指定」,該值會將資料集的位置設定為 US。建立資料集後,就無法變更位置。

    • 針對「Data expiration」,選擇下列其中一個選項:

      • [Never]:(預設) 在資料集中建立的資料表永遠不會自動刪除。您必須手動將其刪除。
      • [In [INTEGER] days]:在資料集中建立的任何資料表都會在距建立時間 [INTEGER] 天後刪除。如果您未在建立資料表時設定資料表到期時間,則將會套用這個值。

        建立資料集

    • 點選 [確定]

指令列

使用 bq mk 指令並搭配使用 --location 標記來建立新的資料集。選用的參數包含 --default_table_expiration--description。如要在預設專案以外的專案中建立資料集,請使用下列格式將專案 ID 新增至資料集名稱: [PROJECT_ID]:[DATASET]
bq --location=[LOCATION] mk --dataset --default_table_expiration [INTEGER] --description [DESCRIPTION] [PROJECT_ID]:[DATASET]

其中:

  • [LOCATION] 是資料集的位置。 建立資料集後,就無法變更位置。您可以使用 .bigqueryrc 檔案設定位置的預設值。

  • [INTEGER] 是新建立資料表的預設生命週期 (以秒為單位)。最小值是 3600 秒 (1 小時)。到期時間的時間值為目前時間加整數值。在資料集中建立的任何資料表都會在距建立時間 [INTEGER] 秒後刪除。如果您未在建立資料表時設定資料表到期時間,則將會套用這個值。

  • [DESCRIPTION] 是括號中資料集的說明。
  • [PROJECT_ID] 是您的專案 ID。
  • [DATASET] 是您要建立之資料集的名稱。

例如,下列指令會建立名為 mydataset 的資料集,並將資料位置設定為 US,資料表的預設到期時間為 3600 秒 (1 小時),以及 This is my dataset 的說明。這個指令不使用 --dataset 標記,而是改用 -d 捷徑。如果您省略 -d--dataset,則該指令預設會建立資料集。

bq --location=US mk -d --default_table_expiration 3600 --description "This is my dataset." mydataset

您可以輸入 bq ls 指令來確認是否已建立該資料集。此外,您可以在使用以下格式建立新的資料集時建立資料表: bq mk -t [DATASET].[TABLE]。如要深入瞭解如何建立資料表,請參閱建立資料表

API

使用定義的資料集資源呼叫 datasets.insert 方法。

C#

若要進一步瞭解如何安裝和建立 BigQuery 用戶端,請參閱 BigQuery 用戶端程式庫

public void CreateDataset(string datasetId, BigQueryClient client)
{
    var dataset = client.GetOrCreateDataset(datasetId);
}

Go

若要進一步瞭解如何安裝和建立 BigQuery 用戶端,請參閱 BigQuery 用戶端程式庫

meta := &bigquery.DatasetMetadata{
	Location: "US", // Create the dataset in the US.
}
if err := client.Dataset(datasetID).Create(ctx, meta); err != nil {
	return err
}

Java

若要進一步瞭解如何安裝和建立 BigQuery 用戶端,請參閱 BigQuery 用戶端程式庫

Dataset dataset = null;
DatasetInfo datasetInfo = DatasetInfo.newBuilder(datasetName).build();
try {
  // the dataset was created
  dataset = bigquery.create(datasetInfo);
} catch (BigQueryException e) {
  // the dataset was not created
}

Node.js

若要進一步瞭解如何安裝和建立 BigQuery 用戶端,請參閱 BigQuery 用戶端程式庫

// Imports the Google Cloud client library
const BigQuery = require('@google-cloud/bigquery');

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// const projectId = "your-project-id";
// const datasetId = "my_new_dataset";

// Creates a client
const bigquery = new BigQuery({
  projectId: projectId,
});

// Creates a new dataset
bigquery
  .createDataset(datasetId)
  .then(results => {
    const dataset = results[0];
    console.log(`Dataset ${dataset.id} created.`);
  })
  .catch(err => {
    console.error('ERROR:', err);
  });

PHP

若要進一步瞭解如何安裝和建立 BigQuery 用戶端,請參閱 BigQuery 用戶端程式庫

use Google\Cloud\BigQuery\BigQueryClient;

/**
 * @param string $projectId The Google project ID.
 * @param string $dataset   The BigQuery dataset ID.
 */
function create_dataset($projectId, $datasetId)
{
    $bigQuery = new BigQueryClient([
        'projectId' => $projectId,
    ]);
    $dataset = $bigQuery->createDataset($datasetId);
    return $dataset;
}

Python

若要進一步瞭解如何安裝和建立 BigQuery 用戶端,請參閱 BigQuery 用戶端程式庫

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

# Create a DatasetReference using a chosen dataset ID.
# The project defaults to the Client's project if not specified.
dataset_ref = client.dataset(dataset_id)

# Construct a full Dataset object to send to the API.
dataset = bigquery.Dataset(dataset_ref)
# Specify the geographic location where the dataset should reside.
dataset.location = 'US'

# Send the dataset to the API for creation.
# Raises google.api_core.exceptions.AlreadyExists if the Dataset already
# exists within the project.
dataset = client.create_dataset(dataset)  # API request

Ruby

若要進一步瞭解如何安裝和建立 BigQuery 用戶端,請參閱 BigQuery 用戶端程式庫

# project_id = "Your Google Cloud project ID"
# dataset_id = "ID of the dataset to create"

require "google/cloud/bigquery"

bigquery = Google::Cloud::Bigquery.new project: project_id

bigquery.create_dataset dataset_id

puts "Created dataset: #{dataset_id}"

指派資料集的存取權控制

您可以使用專案層級 IAM 角色和資料集層級存取權控制來共用 BigQuery 資料表和視圖的存取權。目前,您無法直接將存取權控制套用至資料表或視圖。

專案層級存取權控制可以決定允許存取專案中的所有資料集、資料表、視圖及資料表資料的使用者、群組和服務帳戶。資料集層級存取權控制可以決定允許存取特定資料集中的資料表、視圖及資料表資料的使用者、群組和服務帳戶。

例如,如果您將專案層級的 bigquery.dataOwner 角色指派給使用者,該使用者便可以建立、更新及刪除專案的所有資料集中的資料表和視圖。如果您指派資料集層級的 OWNER 角色,則該使用者只能建立、更新及刪除該資料集中的資料表和視圖。資料集層級 OWNER 原始角色相當於授予資料集的 bigquery.dataOwner 角色。

如果您為使用者或群組指派專案層級限制較多的角色,則也必須授予個別資料集的存取權。例如,如果您授予使用者或群組專案層級的 bigquery.user 角色,則該使用者可以建立資料集,並且可以針對這些資料集中的資料表執行查詢工作。如要查詢資料集中非該使用者建立的資料表,您必須針對該使用者需要查詢的每個資料集 指派至少資料集層級的 READER 存取權給該使用者。資料集層級 READER 原始角色相當於授予資料集的 bigquery.dataViewer 角色。

如要深入瞭解預先定義的專案層級 IAM 角色和資料集層級存取權控制,請參閱存取權控制

所需權限

如要指派或更新資料集存取權控制,您必須具備資料集層級的 OWNER 存取權,或必須取得擁有 bigquery.datasets.update 權限的專案層級 IAM 角色。以下是擁有 bigquery.datasets.update 權限的預先定義專案層級 IAM 角色:

此外,因為 bigquery.user 角色擁有 bigquery.datasets.create 權限,所以經指派為 bigquery.user 角色的使用者可以更新自己建立的任何資料集。當取得 bigquery.user 角色的使用者建立資料集時,該使用者即被授予該資料集的 OWNER 存取權。 OWNER 存取權可讓使用者完全控管該資料集。

如要深入瞭解 BigQuery 中的 IAM 角色和權限,請參閱存取權控制。如要深入瞭解資料集層級角色,請參閱資料集的原始角色

控制資料集的存取權

您可以在使用 BigQuery 網頁版 UI 或 bq update CLI 指令建立資料集後套用該資料集的存取權控制。在 UI 或指令列工具中建立資料集期間無法套用存取權控制。

使用 API,則可以在透過呼叫 datasets.insert 方法建立資料集期間套用存取權控制。您也可以在透過呼叫 datasets.patch 方法建立資料集後套用存取權控制。

當您套用資料集的存取權控制時,可以授予存取權給下列使用者和群組:

  • 依電子郵件指定的使用者 - 將資料集的存取權授予個別 Google 帳戶
  • 依電子郵件指定的群組 - 將資料集的存取權授予 Google 群組的所有成員
  • 網域 - 將資料集的存取權授予某個 Google 網域內的所有使用者和群組
  • 所有已驗證的使用者 - 將資料集的存取權授予所有 Google 帳戶持有人 (公開資料集)
  • 專案擁有者 - 將資料集的存取權授予所有專案擁有者
  • 專案檢視者 - 將資料集的存取權授予所有專案檢視者
  • 專案編輯者 - 將資料集的存取權授予所有專案編輯者
  • 已授權視圖 - 將資料集的存取權授予某個視圖

如何指派資料集的存取權控制:

網頁版 UI

  1. 按一下資料集右側的下拉式箭頭,然後選擇 [Share Dataset]

  2. 在「Share Dataset」對話方塊中,針對「Add People」,按一下欄位左側的下拉式選單,然後選擇適當的選項。

  3. 在文字方塊中輸入值。例如,如果您選擇 [User by e-mail] 或 [Group by e-mail],請輸入使用者或群組的電子郵件地址。

  4. 在「Add People」欄位的右側,按一下 [Can view],然後從清單中選擇適當的角色。

    將使用者加入資料集

  5. 按一下 [Add],然後點選 [Save changes]

指令列

  1. 使用 show 指令將現有的資料集資訊 (包括存取權控制) 寫入 JSON 檔案。如果資料集位於預設專案以外的專案中,請使用下列格式將專案 ID 新增至資料集名稱: [PROJECT_ID]:[DATASET]

    bq show --format=prettyjson [PROJECT_ID]:[DATASET] > [PATH_TO_FILE]
    

    其中:

    • [PROJECT_ID] 是您的專案 ID。
    • [DATASET] 是您的資料集名稱。
    • [PATH_TO_FILE] 是您本機上的 JSON 檔案路徑。

    範例:

    輸入下列指令,將 mydataset 的存取權控制寫入 JSON 檔案。mydataset 位於預設專案中。

    bq show --format=prettyjson mydataset > /tmp/mydataset.json
    

    輸入下列指令,將 mydataset 的存取權控制寫入 JSON 檔案。mydataset 位於 myotherproject 中。

    bq show --format=prettyjson myotherproject:mydataset > /tmp/mydataset.json
    
  2. 變更 JSON 檔案的 "access" 區段。您可以新增或移除任何 specialGroup 項目:projectOwnersprojectWritersprojectReadersallAuthenticatedUsers。您也可以新增、移除或修改下列任一項目: userByEmailgroupByEmaildomain

    例如,資料集的 JSON 檔案的存取權區段會如下所示:

    {
     "access": [
      {
       "role": "READER",
       "specialGroup": "projectReaders"
      },
      {
       "role": "WRITER",
       "specialGroup": "projectWriters"
      },
      {
       "role": "OWNER",
       "specialGroup": "projectOwners"
      },
      {
       "role": "READER",
       "specialGroup": "allAuthenticatedUsers"
      },
      {
       "role": "READER",
       "domain": "[DOMAIN_NAME]"
      },
      {
       "role": "WRITER",
       "userByEmail": "[USER_EMAIL]"
      },
      {
       "role": "READER",
       "groupByEmail": "[GROUP_EMAIL]"
      }
     ],
     ...
    }
    

  3. 編輯完成後,請使用 update 指令並使用 --source 標記加入 JSON 檔案。如果資料集位於預設專案以外的專案中,請使用下列格式將專案 ID 新增至資料集名稱: [PROJECT_ID]:[DATASET]

    bq update --source [PATH_TO_FILE] [PROJECT_ID]:[DATASET]
    

    其中:

    • [PATH_TO_FILE] 是您本機上的 JSON 檔案路徑。
    • [PROJECT_ID] 是您的專案 ID。
    • [DATASET] 是您的資料集名稱。

    範例:

    輸入下列指令,更新 mydataset 的存取權控制。mydataset 位於預設專案中。

    bq update --source /tmp/mydataset.json mydataset
    

    輸入下列指令,更新 mydataset 的存取權控制。mydataset 位於 myotherproject 中。

    bq update --source /tmp/mydataset.json myotherproject:mydataset
    
  4. 如要驗證您的存取權控制變更,請再次輸入 show 指令,而不要將資訊寫入檔案。

    bq show --format=prettyjson [DATASET]

    bq show --format=prettyjson [PROJECT_ID]:[DATASET]

API

呼叫 datasets.insert,並搭配已定義的資料集資源,以在建立資料集時套用存取權控制。呼叫 datasets.patch 並使用資料集資源中的 access 屬性更新您的存取權控制。

因為 datasets.update 方法會取代整個資料集資源,因此更新存取權控制時建議使用 datasets.patch 方法。

詳情請參閱資料集

Go

利用資料集的存取權控制設定 dataset.access_entries 屬性。然後呼叫 client.update_dataset() 函式來更新屬性。

ds := client.Dataset(datasetID)
meta, err := ds.Metadata(ctx)
if err != nil {
	return err
}
// Append a new access control entry to the existing access list.
update := bigquery.DatasetMetadataToUpdate{
	Access: append(meta.Access, &bigquery.AccessEntry{
		Role:       bigquery.ReaderRole,
		EntityType: bigquery.UserEmailEntity,
		Entity:     "sample.bigquery.dev@gmail.com"},
	),
}

// Leverage the ETag for the update to assert there's been no modifications to the
// dataset since the metadata was originally read.
if _, err := ds.Update(ctx, update, meta.ETag); err != nil {
	return err
}

Python

若要進一步瞭解如何安裝和建立 BigQuery 用戶端,請參閱 BigQuery 用戶端程式庫

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

entry = bigquery.AccessEntry(
    role='READER',
    entity_type='userByEmail',
    entity_id='sample.bigquery.dev@gmail.com')
assert entry not in dataset.access_entries
entries = list(dataset.access_entries)
entries.append(entry)
dataset.access_entries = entries

dataset = client.update_dataset(dataset, ['access_entries'])  # API request

assert entry in dataset.access_entries

使用資料集

取得資料集相關資訊

您可以使用 BigQuery 網頁版 UI、bq show CLI 指令或透過呼叫 datasets.get API 方法來取得資料集資訊。

所需權限

如要取得資料集相關資訊,您必須取得資料集層級 READER 的角色,或必須取得擁有 bigquery.datasets.get 權限的專案層級 IAM 角色。所有預先定義的專案層級 IAM 角色都擁有 bigquery.jobUser 除外的 bigquery.datasets.get 權限。

如要深入瞭解 BigQuery 中的 IAM 角色和權限,請參閱存取權控制。如要深入瞭解資料集層級角色,請參閱資料集的原始角色

取得資料集資訊

如要取得專案中的資料集相關資訊:

網頁版 UI

按一下資料集名稱。「Dataset Details」頁面會顯示資料集的說明、詳細資料和資料表。

查看資料集

指令列

發出 bq show 指令。--format 標記可用來控制輸出。如果您要取得在預設專案以外的專案中的資料集相關資訊,請使用下列格式將專案 ID 新增至資料集名稱: [PROJECT_ID]:[DATASET]

bq show --format=prettyjson [PROJECT_ID]:[DATASET]

其中:

  • [PROJECT_ID] 是您的專案名稱。
  • [DATASET] 是資料集的名稱。

範例:

輸入下列指令,顯示您預設專案中的 mydataset 相關資訊。

bq show --format=prettyjson mydataset

輸入下列指令,顯示 myotherproject 中的 mydataset 相關資訊。

bq show --format=prettyjson myotherproject:mydataset

API

呼叫 datasets.get API 方法並提供任何相關參數。

Go

若要進一步瞭解如何安裝和建立 BigQuery 用戶端,請參閱 BigQuery 用戶端程式庫

meta, err := client.Dataset(datasetID).Metadata(ctx)
if err != nil {
	return err
}

fmt.Printf("Dataset ID: %s\n", datasetID)
fmt.Printf("Description: %s\n", meta.Description)
fmt.Println("Labels:")
for k, v := range meta.Labels {
	fmt.Printf("\t%s: %s", k, v)
}
fmt.Println("Tables:")
it := client.Dataset(datasetID).Tables(ctx)

cnt := 0
for {
	t, err := it.Next()
	if err == iterator.Done {
		break
	}
	cnt++
	fmt.Printf("\t%s\n", t.TableID)
}
if cnt == 0 {
	fmt.Println("\tThis dataset does not contain any tables.")
}

Java

若要進一步瞭解如何安裝和建立 BigQuery 用戶端,請參閱 BigQuery 用戶端程式庫

DatasetId datasetId = DatasetId.of(projectId, datasetName);
Dataset dataset = bigquery.getDataset(datasetId);

Python

若要進一步瞭解如何安裝和建立 BigQuery 用戶端,請參閱 BigQuery 用戶端程式庫

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

dataset_ref = client.dataset(dataset_id)
dataset = client.get_dataset(dataset_ref)  # API request

# View dataset properties
print('Dataset ID: '.format(dataset_id))
print('Description: '.format(dataset.description))
print('Labels:')
for label, value in dataset.labels.items():
    print('\t{}: {}'.format(label, value))
# View tables in dataset
print('Tables:')
tables = list(client.list_tables(dataset_ref))  # API request(s)
if tables:
    for table in tables:
        print('\t{}'.format(table.table_id))
else:
    print('\tThis dataset does not contain any tables.')

列出資料集

您可以使用 BigQuery 網頁版 UI、bq ls CLI 指令或透過呼叫 datasets.list API 方法來列出資料集。

所需權限

當您列出資料集時,只會傳回您擁有 bigquery.datasets.get 權限的資料集。其中包括任何您已被授予資料集層級 READER 存取權的資料集。所有預先定義的專案層級 IAM 角色都擁有 bigquery.jobUser 除外的 bigquery.datasets.get 權限。如果您取得預先定義的專案層級 IAM 角色 (bigquery.jobUser 除外),則可以列出專案中的所有資料集。

如要深入瞭解 BigQuery 中的 IAM 角色和權限,請參閱存取權控制。如要深入瞭解資料集層級角色,請參閱資料集的原始角色

列出專案中的資料集

如何列出專案中的資料集:

網頁版 UI

網頁版 UI 的導覽窗格中會依專案列出資料集。

指令列

發出 bq ls 指令來依資料集 ID 列出資料集。--format 標記可用來控制輸出。如果您要列出在預設專案以外的專案中的資料集,請將 --project_id 標記新增至該指令。

bq ls --format=prettyjson --project_id [PROJECT_ID]

其中:

  • [PROJECT_ID] 是您的專案名稱。

範例:

輸入下列指令,列出預設專案中的資料集。

bq ls --format=prettyjson

輸入下列指令,列出 myotherproject 中的資料集。

bq ls --format=prettyjson --project_id myotherproject

API

如要使用 API 列出資料集,請呼叫 datasets.list API 方法。

C#

若要進一步瞭解如何安裝和建立 BigQuery 用戶端,請參閱 BigQuery 用戶端程式庫

public List<BigQueryDataset> ListDatasets(BigQueryClient client)
{
    var datasets = client.ListDatasets().ToList();
    return datasets;
}

Go

若要進一步瞭解如何安裝和建立 BigQuery 用戶端,請參閱 BigQuery 用戶端程式庫

it := client.Datasets(ctx)
for {
	dataset, err := it.Next()
	if err == iterator.Done {
		break
	}
	fmt.Println(dataset.DatasetID)
}

Java

若要進一步瞭解如何安裝和建立 BigQuery 用戶端,請參閱 BigQuery 用戶端程式庫

// List datasets in the default project
Page<Dataset> datasets = bigquery.listDatasets(DatasetListOption.pageSize(100));
for (Dataset dataset : datasets.iterateAll()) {
  // do something with the dataset
}
// List datasets in a specified project
Page<Dataset> datasets = bigquery.listDatasets(projectId, DatasetListOption.pageSize(100));
for (Dataset dataset : datasets.iterateAll()) {
  // do something with the dataset
}

Node.js

若要進一步瞭解如何安裝和建立 BigQuery 用戶端,請參閱 BigQuery 用戶端程式庫

// Imports the Google Cloud client library
const BigQuery = require('@google-cloud/bigquery');

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// const projectId = "your-project-id";

// Creates a client
const bigquery = new BigQuery({
  projectId: projectId,
});

// Lists all datasets in the specified project
bigquery
  .getDatasets()
  .then(results => {
    const datasets = results[0];
    console.log('Datasets:');
    datasets.forEach(dataset => console.log(dataset.id));
  })
  .catch(err => {
    console.error('ERROR:', err);
  });

PHP

若要進一步瞭解如何安裝和建立 BigQuery 用戶端,請參閱 BigQuery 用戶端程式庫

use Google\Cloud\BigQuery\BigQueryClient;

/**
 * @param string $projectId The Google project ID.
 */
function list_datasets($projectId)
{
    $bigQuery = new BigQueryClient([
        'projectId' => $projectId,
    ]);
    $datasets = $bigQuery->datasets();
    foreach ($datasets as $dataset) {
        print($dataset->id() . PHP_EOL);
    }
}

Python

若要進一步瞭解如何安裝和建立 BigQuery 用戶端,請參閱 BigQuery 用戶端程式庫

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

datasets = list(client.list_datasets())
project = client.project

if datasets:
    print('Datasets in project {}:'.format(project))
    for dataset in datasets:  # API request(s)
        print('\t{}'.format(dataset.dataset_id))
else:
    print('{} project does not contain any datasets.'.format(project))

Ruby

若要進一步瞭解如何安裝和建立 BigQuery 用戶端,請參閱 BigQuery 用戶端程式庫

# project_id = "Your Google Cloud project ID"

require "google/cloud/bigquery"

bigquery = Google::Cloud::Bigquery.new project: project_id

bigquery.datasets.each do |dataset|
  puts dataset.dataset_id
end

使用中繼資料表取得資料集中繼資料

BigQuery 提供一些特殊的資料表,其內容代表中繼資料,例如資料集中的資料表和視圖清單。「中繼資料表」皆為唯讀。如要存取關於資料集中的資料表和視圖的中繼資料,請在查詢的 SELECT 陳述式中使用 __TABLES_SUMMARY__ 中繼資料表。您可以使用 BigQuery 網頁版 UI、指令列工具的 bq query 指令或透過呼叫 jobs.insert API 方法並設定查詢工作來執行查詢。

使用 __TABLES_SUMMARY__ 中繼資料表的查詢如下所示:

    SELECT [FIELD] FROM [DATASET].__TABLES_SUMMARY__

其中:

  • DATASET 是您的資料集名稱
  • FIELD 是下列其中一項:
說明
project_id 專案名稱。
dataset_id 資料集名稱。
table_id 資料表或視圖名稱。
creation_time 資料表或視圖的建立時間,從世界標準時間 1970 年 1 月 1 日開始計算並以毫秒為單位。
type 整數代表資料表類型:一般資料表 (1) 或視圖 (2)。

所需權限

如要執行使用 __TABLES_SUMMARY__ 中繼資料表的查詢工作,您必須擁有 bigquery.jobs.create 權限。以下是擁有 bigquery.jobs.create 權限的預先定義專案層級 IAM 角色:

您也必須接受資料集層級的 READER 角色,或必須取得擁有 bigquery.tables.getData 權限的專案層級 IAM 角色。bigquery.userbigquery.jobUser 除外的所有預先定義專案層級 IAM 角色都擁有 bigquery.tables.getData 權限。

中繼資料表的限制

中繼資料表有下列限制:

  • 一般來說,對於內含數千個資料表的資料集,__TABLES_SUMMARY__ 的處理速度相當快。但對於更大容量的資料集,__TABLES_SUMMARY__ 的速度會變慢,並且可能會超出可用資源。
  • 中繼資料表無法與 tables.insert 方法搭配使用。
  • 中繼資料表無法作為目的地資料表使用。
  • 中繼資料表不支援舊版 SQL 中的資料表裝飾器。
  • 當您列出資料集中的資料表時,中繼資料表不會顯示。

中繼資料表範例

下列查詢會擷取 bigquery-public-data.samples 資料集的所有中繼資料。

網頁版 UI

#standardSQL
SELECT
  *
FROM
  `bigquery-public-data.samples.__TABLES_SUMMARY__`

指令列

bq --location=US query --use_legacy_sql=false '
SELECT
  *
FROM
  `bigquery-public-data.samples.__TABLES_SUMMARY__`'

輸出如下所示:

+----------------------+------------+-----------------+---------------+------+
| project_id           | dataset_id |    table_id     | creation_time | type |
+----------------------+------------+-----------------+---------------+------+
| bigquery-public-data | samples    | github_nested   | 1348782587310 |    1 |
| bigquery-public-data | samples    | github_timeline | 1335915950690 |    1 |
| bigquery-public-data | samples    | gsod            | 1335916040125 |    1 |
| bigquery-public-data | samples    | natality        | 1335916045005 |    1 |
| bigquery-public-data | samples    | shakespeare     | 1335916045099 |    1 |
| bigquery-public-data | samples    | trigrams        | 1335916127449 |    1 |
| bigquery-public-data | samples    | wikipedia       | 1335916132870 |    1 |
+----------------------+------------+-----------------+---------------+------+

下列查詢會列出 bigquery-public-data.samples 資料集中的所有資料表和視圖。

網頁版 UI

#standardSQL
SELECT
  table_id
FROM
  `bigquery-public-data.samples.__TABLES_SUMMARY__`

指令列

bq --location=US query --use_legacy_sql=false '
SELECT
  table_id
FROM
  `bigquery-public-data.samples.__TABLES_SUMMARY__`'

輸出如下所示:

+-----------------+
|    table_id     |
+-----------------+
| github_nested   |
| github_timeline |
| gsod            |
| natality        |
| shakespeare     |
| trigrams        |
| wikipedia       |
+-----------------+

下列查詢會列出 bigquery-public-data.samples 資料集中每個資料表的類型。

網頁版 UI

#standardSQL
SELECT
  table_id, type
FROM
  `bigquery-public-data.samples.__TABLES_SUMMARY__`

指令列

bq --location=US query --use_legacy_sql=false '
SELECT
  table_id, type
FROM
  `bigquery-public-data.samples.__TABLES_SUMMARY__`'

輸出如下所示:

+-----------------+------+
|    table_id     | type |
+-----------------+------+
| github_nested   |   1  |
| github_timeline |   1  |
| gsod            |   1  |
| natality        |   1  |
| shakespeare     |   1  |
| trigrams        |   1  |
| wikipedia       |   1  |
+-----------------+------+

後續步驟

本頁內容對您是否有任何幫助?請提供意見:

傳送您對下列選項的寶貴意見...

這個網頁