bq ツールを使用する

bq ツールを使用する

このチュートリアルでは、BigQuery 用の Python ベースのコマンドライン インターフェース（CLI）ツールである bq を使用して、データセットの作成、サンプルデータの読み込み、テーブルのクエリを行う方法について説明します。このチュートリアルを完了すると、bq と、CLI を使用して BigQuery を操作する方法を理解できます。

すべての bq コマンドとフラグの詳細なリファレンスについては、bq コマンドライン ツールのリファレンスをご覧ください。

---

このタスクを Google Cloud コンソールで直接行う際の順を追ったガイダンスについては、「ガイドを表示」をクリックしてください。

ガイドを表示

---

始める前に

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

このガイドで既存のプロジェクトを使用する場合は、このガイドを完了するために必要な権限があることを確認します。新しいプロジェクトを作成した場合は、必要な権限がすでに付与されています。

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

このガイドで既存のプロジェクトを使用する場合は、このガイドを完了するために必要な権限があることを確認します。新しいプロジェクトを作成した場合は、必要な権限がすでに付与されています。

1. Enable the BigQuery API.

   Roles required to enable APIs

   To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

   Enable the API

   新しいプロジェクトでは、BigQuery API が自動的に有効になります。

2. （省略可）プロジェクトに対する課金を有効にします。課金を有効にしない場合や、クレジット カードを指定しない場合でも、このドキュメントの手順は行えます。BigQuery には、この手順を実施するためのサンドボックスが用意されています。詳細については、BigQuery サンドボックスを有効にするをご覧ください。
   注: プロジェクトに請求先アカウントがあり、BigQuery サンドボックスを使用する場合は、プロジェクトの課金を無効にしてください。

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

必要なロール

データセットの作成、テーブルの作成、データの読み込み、データのクエリに必要な権限を取得するには、プロジェクトに対する次の IAM ロールを付与するよう管理者に依頼してください。

• 読み込みジョブとクエリジョブの実行: BigQuery ジョブユーザー （roles/bigquery.jobUser）
• データセットの作成、テーブルの作成、テーブルへのデータの読み込み、テーブルのクエリ: BigQuery データ編集者 （roles/bigquery.dataEditor）

ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

ソースデータを含むファイルをダウンロードする

ダウンロードするファイルには、人気のある新生児の名前に関する約 7 MB のデータが含まれます。これは米国社会保障局から提供されています。

このデータの詳細については、米国社会保障局の人気の名前の背景情報をご覧ください。

1. 新しいブラウザタブで次の URL を開き、米国社会保障局のデータをダウンロードします。

   https://www.ssa.gov/OACT/babynames/names.zip
   

2. ファイルを抽出します。

   データセット スキーマの詳細については、抽出した NationalReadMe.pdf ファイルをご覧ください。

3. データの内容を確認するには、yob2024.txt ファイルを開きます。このファイルには、名前、出生時の性別、その名前の子供の数の値がカンマ区切りで含まれています。このファイルにはヘッダー行がありません。

4. ファイルを作業ディレクトリに移動します。

   • Cloud Shell で作業している場合は、 [詳細]、[アップロード] の順にクリックし、[ファイル選択] をクリックして、yob2024.txt ファイルを選択後、[アップロード] をクリックします。

   • ローカルシェルで作業している場合は、bq ツールを実行しているディレクトリにファイル yob2024.txt をコピーまたは移動します。

データセットを作成する

1. ドキュメントから Cloud Shell を起動した場合は、次のコマンドを入力してプロジェクト ID を設定します。これにより、各 CLI コマンドでプロジェクト ID を指定する必要がなくなります。

   gcloud config set project PROJECT_ID
   

   PROJECT_ID は、実際のプロジェクト ID に置き換えます。

1. 次のコマンドを入力して、babynames という名前のデータセットを作成します。

   bq mk --dataset babynames
   

   出力は次のようになります。

   Dataset 'babynames' successfully created.
   

2. データセット babynames がプロジェクトに表示されることを確認します。

   bq ls --datasets=true
   

   出力は次のようになります。

     datasetId
   -------------
     babynames
   

テーブルにデータを読み込む

1. babynames データセットで、ソースファイル yob2024.txt を names2024 という名前の新しいテーブルに読み込みます。

   bq load babynames.names2024 yob2024.txt name:string,assigned_sex_at_birth:string,count:integer
   

   出力は次のようになります。

   Upload complete.
   Waiting on bqjob_r3c045d7cbe5ca6d2_0000018292f0815f_1 ... (1s) Current status: DONE
   

2. テーブル names2024 が babynames データセットに表示されることを確認します。

   bq ls --format=pretty babynames
   

   出力は次のようになります。出力を簡素化するために、一部の列は省略されています。

   +-----------+-------+
   |  tableId  | Type  |
   +-----------+-------+
   | names2024 | TABLE |
   +-----------+-------+
   

3. 新しい names2024 テーブルのテーブル スキーマが name: string、assigned_sex_at_birth: string、count: integer であることを確認します。

   bq show babynames.names2024
   

   出力は次のようになります。出力を簡素化するために、一部の列は省略されています。

     Last modified        Schema                      Total Rows   Total Bytes
   ----------------- ------------------------------- ------------ ------------
   14 Mar 17:16:45   |- name: string                    31904       607494
                     |- assigned_sex_at_birth: string
                     |- count: integer
   

テーブルデータをクエリする

1. データ内の最も人気のある女の子の名前を特定します。

   bq query \
       'SELECT
         name,
         count
       FROM
         babynames.names2024
       WHERE
         assigned_sex_at_birth = "F"
       ORDER BY
         count DESC
       LIMIT 5'
   

   出力は次のようになります。

   +-----------+-------+
   |   name    | count |
   +-----------+-------+
   | Olivia    | 14718 |
   | Emma      | 13485 |
   | Amelia    | 12740 |
   | Charlotte | 12552 |
   | Mia       | 12113 |
   +-----------+-------+
   

2. データの中から最も人気の低い男の子の名前を特定します。

   bq query \
       'SELECT
         name,
         count
       FROM
         babynames.names2024
       WHERE
         assigned_sex_at_birth = "M"
       ORDER BY
         count ASC
       LIMIT 5'
   

   出力は次のようになります。

   +---------+-------+
   |  name   | count |
   +---------+-------+
   | Aaran   |     5 |
   | Aadiv   |     5 |
   | Aadarsh |     5 |
   | Aarash  |     5 |
   | Aadrik  |     5 |
   +---------+-------+
   

   ソースデータは出現数が 5 未満の名前を除外するので、最小数は 5 です。

クリーンアップ

このページで使用したリソースについて、 Google Cloud アカウントに課金されないようにするには、リソースを含む Google Cloud プロジェクトを削除します。

プロジェクトを削除する

BigQuery サンドボックスを使用して一般公開データセットをクエリした場合、そのプロジェクトでは課金は有効になっていないため、プロジェクトを削除する必要はありません。

課金をなくす最も簡単な方法は、チュートリアル用に作成したプロジェクトを削除することです。

プロジェクトを削除するには:

注意: プロジェクトを削除すると、次のような影響があります。

• プロジェクト内のすべてのものが削除されます。このドキュメントのタスクで既存のプロジェクトを使用した場合、それを削除すると、そのプロジェクトで行った他の作業もすべて削除されます。
• カスタム プロジェクト ID が失われます。このプロジェクトを作成したときに、将来使用するカスタム プロジェクト ID を作成した可能性があります。そのプロジェクト ID を使用した URL（たとえば、appspot.com）を保持するには、プロジェクト全体ではなくプロジェクト内の選択したリソースだけを削除します。

複数のアーキテクチャ、チュートリアル、クイックスタートを実施する予定がある場合は、プロジェクトを再利用することで、プロジェクトの割り当て上限の超過を避けられます。

1. In the Google Cloud console, go to the Manage resources page.

   Go to Manage resources

2. In the project list, select the project that you want to delete, and then click Delete.
3. In the dialog, type the project ID, and then click Shut down to delete the project.

リソースを削除する

既存のプロジェクトを使用した場合は、作成したリソースを削除します。

1. babynames データセットを削除します。

   bq rm --recursive=true babynames
   

   --recursive フラグは、names2024 テーブルを含むデータセット内のすべてのテーブルを削除します。

   出力は次のようになります。

   rm: remove dataset 'myproject:babynames'? (y/N)
   

2. 削除コマンドを確定するには、「y」と入力します。

次のステップ

• bq ツールの使用の詳細を確認する。
• BigQuery サンドボックスについて学習する。
• BigQuery へのデータの読み込みの概要について詳細を確認する。
• BigQuery でのデータのクエリについて詳細を学習する。