Menjalankan kueri

BigQuery memungkinkan Anda menjalankan kueri secara langsung (interaktif), dalam batch, atau terus-menerus, bergantung pada kasus penggunaan Anda. Untuk memvalidasi sintaksis SQL dan memperkirakan jumlah data yang diproses kueri agar dapat mengontrol biaya dengan lebih baik, Anda dapat melakukan uji coba.

Jenis kueri

Anda dapat membuat kueri data BigQuery menggunakan salah satu jenis tugas kueri berikut:

• Tugas kueri interaktif. Secara default, BigQuery menjalankan kueri sebagai tugas kueri interaktif, yang dimaksudkan untuk mulai dieksekusi secepat mungkin.

• Tugas kueri batch. Kueri batch memiliki prioritas lebih rendah daripada kueri interaktif. Saat project atau pemesanan menggunakan semua resource komputasi yang tersedia, kueri batch lebih mungkin dimasukkan ke dalam antrean dan tetap berada dalam antrean. Setelah kueri batch mulai berjalan, kueri batch akan berjalan sama seperti kueri interaktif. Untuk informasi selengkapnya, lihat antrean kueri.

• Tugas kueri berkelanjutan. Dengan tugas ini, kueri berjalan terus-menerus, sehingga Anda dapat menganalisis data yang masuk di BigQuery secara real time, lalu menulis hasilnya ke tabel BigQuery, atau mengekspor hasilnya ke Bigtable atau Pub/Sub. Anda dapat menggunakan kemampuan ini untuk melakukan tugas yang mendesak, seperti membuat dan segera menindaklanjuti insight, menerapkan inferensi machine learning (ML) real-time, dan membangun pipeline data berbasis peristiwa.

Anda dapat menjalankan tugas kueri menggunakan metode berikut:

• Buat dan jalankan kueri di konsolGoogle Cloud .
• Jalankan perintah bq query di alat command line bq.
• Secara terprogram panggil metode jobs.query atau jobs.insert di BigQuery REST API.
• Menggunakan library klien BigQuery.

BigQuery menyimpan hasil kueri ke tabel sementara (default) atau tabel permanen. Saat menentukan tabel permanen sebagai tabel tujuan untuk hasil, Anda dapat memilih apakah akan menambahkan atau menimpa tabel yang sudah ada, atau membuat tabel baru dengan nama unik.

Catatan: Jika Anda membuat kueri data dari project ke data yang disimpan dalam project lain, project yang di-kueri akan dikenai biaya untuk tugas kueri selagi project yang menyimpan data dikenai biaya untuk jumlah data yang disimpan di BigQuery.

Peran yang diperlukan

Untuk mendapatkan izin yang Anda perlukan untuk menjalankan tugas kueri, minta administrator untuk memberi Anda peran IAM berikut:

• Pengguna Tugas BigQuery (roles/bigquery.jobUser) pada project.
• Penampil Data BigQuery (roles/bigquery.dataViewer) pada semua tabel dan tampilan yang dirujuk oleh kueri Anda. Untuk membuat kueri tampilan, Anda juga memerlukan peran ini di semua tabel dan tampilan yang mendasarinya. Jika menggunakan tampilan yang diotorisasi atau set data yang diotorisasi, Anda tidak memerlukan akses ke data sumber pokok.

Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses ke project, folder, dan organisasi.

Peran yang telah ditetapkan ini berisi izin yang diperlukan untuk menjalankan tugas kueri. Untuk melihat izin yang benar-benar diperlukan, perluas bagian Izin yang diperlukan:

Izin yang diperlukan

Izin berikut diperlukan untuk menjalankan tugas kueri:

• bigquery.jobs.create pada project tempat kueri dijalankan, terlepas dari lokasi penyimpanan data.
• bigquery.tables.getData di semua tabel dan tampilan yang dirujuk oleh kueri Anda. Untuk membuat kueri tampilan, Anda juga memerlukan izin ini pada semua tabel dan tampilan yang mendasarinya. Jika menggunakan tampilan yang diotorisasi atau set data yang diotorisasi, Anda tidak memerlukan akses ke data sumber pokok.

Anda mungkin juga bisa mendapatkan izin ini dengan peran khusus atau peran bawaan lainnya.

Pemecahan masalah

Access Denied: Project [project_id]: User does not have bigquery.jobs.create
permission in project [project_id].

Error ini terjadi jika akun utama tidak memiliki izin untuk membuat tugas kueri dalam project.

Penyelesaian: Administrator harus memberi Anda izin bigquery.jobs.create pada project yang Anda kueri. Izin ini diperlukan selain izin yang diperlukan untuk mengakses data yang dikueri.

Untuk mengetahui informasi selengkapnya tentang izin BigQuery, lihat Kontrol akses dengan IAM.

Menjalankan kueri interaktif

Untuk menjalankan kueri interaktif, pilih salah satu opsi berikut:

Konsol

1. Buka halaman BigQuery.

   Buka BigQuery

2. Klik Kueri SQL.

3. Di editor kueri, masukkan kueri GoogleSQL yang valid.

   Misalnya, buat kueri set data publik BigQuery usa_names untuk menentukan nama yang paling umum di Amerika Serikat antara tahun 1910 dan 2013:

   SELECT
     name, gender,
     SUM(number) AS total
   FROM
     `bigquery-public-data.usa_names.usa_1910_2013`
   GROUP BY
     name, gender
   ORDER BY
     total DESC
   LIMIT
     10;
   

   Atau, Anda dapat menggunakan panel Reference untuk membuat kueri baru.

4. Opsional: Untuk menampilkan saran kode secara otomatis saat Anda mengetik kueri, klik Tools > Parser-based auto-completion. Jika Anda tidak memerlukan saran pelengkapan otomatis, batalkan pilihan Parser-based auto-completion. Tindakan ini juga akan menonaktifkan saran isi otomatis nama project.

5. Opsional: Untuk memilih setelan kueri tambahan, klik Edit > Setelan kueri.

6. Klik Run.

   Jika Anda tidak menentukan tabel tujuan, tugas kueri akan menulis output ke tabel sementara (cache).

   Sekarang Anda dapat mempelajari hasil kueri di tab Results pada panel Query results.

7. Opsional: Untuk mengurutkan hasil kueri berdasarkan kolom, klik Buka menu pengurutan di samping nama kolom, lalu pilih tata urutan. Jika estimasi byte yang diproses untuk pengurutan lebih dari nol, jumlah byte akan ditampilkan di bagian atas menu.

8. Opsional: Untuk melihat visualisasi hasil kueri Anda, buka tab Visualization. Anda dapat memperbesar atau memperkecil diagram, mendownload diagram sebagai file PNG, atau mengalihkan visibilitas legenda.

   Di panel Konfigurasi visualisasi, Anda dapat mengubah jenis visualisasi serta mengonfigurasi ukuran dan dimensi visualisasi. Kolom di panel ini diisi otomatis dengan konfigurasi awal yang disimpulkan dari skema tabel tujuan kueri. Konfigurasi dipertahankan di antara kueri berikut yang dijalankan di editor kueri yang sama.

   Untuk visualisasi Garis, Batang, atau Sebar, dimensi yang didukung adalah jenis data INT64, FLOAT64, NUMERIC, BIGNUMERIC, TIMESTAMP, DATE, DATETIME, TIME, dan STRING, sedangkan pengukuran yang didukung adalah jenis data INT64, FLOAT64, NUMERIC, dan BIGNUMERIC.

   Jika hasil kueri Anda menyertakan jenis GEOGRAPHY, Peta adalah jenis visualisasi default, yang memungkinkan Anda memvisualisasikan hasil di peta interaktif.

9. Opsional: Di tab JSON, Anda dapat menjelajahi hasil kueri dalam format JSON, dengan kunci sebagai nama kolom dan nilai sebagai hasil untuk kolom tersebut.

bq

1. Di konsol Google Cloud , aktifkan Cloud Shell.

   Aktifkan Cloud Shell

   Di bagian bawah konsol Google Cloud , sesi Cloud Shell akan dimulai dan menampilkan prompt command line. Cloud Shell adalah lingkungan shell dengan Google Cloud CLI yang sudah terinstal, dan dengan nilai yang sudah ditetapkan untuk project Anda saat ini. Diperlukan waktu beberapa detik untuk melakukan inisialisasi pada sesi.

2. Gunakan perintah bq query. Pada contoh berikut, flag --use_legacy_sql=false memungkinkan Anda menggunakan sintaksis GoogleSQL.

   bq query \
       --use_legacy_sql=false \
       'QUERY'

   Ganti QUERY dengan kueri GoogleSQL yang valid. Misalnya, buat kueri set data publik BigQuery usa_names untuk menentukan nama yang paling umum di Amerika Serikat antara tahun 1910 dan 2013:

   bq query \
       --use_legacy_sql=false \
       'SELECT
         name, gender,
         SUM(number) AS total
       FROM
         `bigquery-public-data.usa_names.usa_1910_2013`
       GROUP BY
         name, gender
       ORDER BY
         total DESC
       LIMIT
         10;'
   

   Tugas kueri menulis output ke tabel sementara (cache).

   Selain itu, Anda dapat menentukan tabel tujuan dan lokasi untuk hasil kueri. Untuk menulis hasilnya ke tabel yang sudah ada, sertakan flag yang sesuai untuk menambahkan (--append_table=true) atau menimpa (--replace=true) tabel.

   bq query \
       --location=LOCATION \
       --destination_table=TABLE \
       --use_legacy_sql=false \
       'QUERY'

   Ganti kode berikut:

   • LOCATION: region atau multi-region untuk tabel tujuan—misalnya, US

     Dalam contoh ini, set data usa_names disimpan di lokasi multi-region AS. Jika Anda menentukan tabel tujuan untuk kueri ini, set data yang berisi tabel tujuan juga harus berada di multi-region AS. Anda tidak dapat mengkueri set data di satu lokasi dan menulis hasilnya ke tabel di lokasi lain.

     Anda dapat menetapkan nilai default untuk lokasi menggunakan .bigqueryrc file.

   • TABLE: nama untuk tabel tujuan—misalnya, myDataset.myTable

     Jika tabel tujuan adalah tabel baru, BigQuery akan membuat tabel tersebut saat Anda menjalankan kueri. Namun, Anda harus menentukan set data yang sudah ada.

     Jika tabel tidak ada dalam project Anda saat ini, tambahkan project IDGoogle Cloud menggunakan format PROJECT_ID:DATASET.TABLE—misalnya, myProject:myDataset.myTable. Jika --destination_table tidak ditentukan, tugas kueri akan dibuat yang menulis output ke tabel sementara.

Terraform

Gunakan resource google_bigquery_job.

Catatan: Untuk membuat objek BigQuery menggunakan Terraform, Anda harus mengaktifkan Cloud Resource Manager API.

Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

Contoh berikut menjalankan kueri. Anda dapat mengambil hasil kueri dengan melihat detail tugas:

# Generate a unique job ID.
resource "random_string" "job_id" {
  lower   = true
  length  = 16
  special = false

  keepers = {
    uuid = uuid()
  }
}

# Create a query using the generated job ID.
resource "google_bigquery_job" "my_query_job" {
  job_id = random_string.job_id.id

  query {
    query = "SELECT name, SUM(number) AS total FROM `bigquery-public-data.usa_names.usa_1910_2013` GROUP BY name ORDER BY total DESC LIMIT 100;"
  }
}

Untuk menerapkan konfigurasi Terraform di project Google Cloud , selesaikan langkah-langkah di bagian berikut.

Menyiapkan Cloud Shell

1. Luncurkan Cloud Shell.

2. Tetapkan project Google Cloud default tempat Anda ingin menerapkan konfigurasi Terraform.

   Anda hanya perlu menjalankan perintah ini sekali per project, dan dapat dijalankan di direktori mana pun.

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   Variabel lingkungan akan diganti jika Anda menetapkan nilai eksplisit dalam file konfigurasi Terraform.

Menyiapkan direktori

Setiap file konfigurasi Terraform harus memiliki direktorinya sendiri (juga disebut modul root).

1. Di Cloud Shell, buat direktori dan file baru di dalam direktori tersebut. Nama file harus memiliki ekstensi .tf—misalnya main.tf. Dalam tutorial ini, file ini disebut sebagai main.tf.

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

2. Jika mengikuti tutorial, Anda dapat menyalin kode contoh di setiap bagian atau langkah.

   Salin kode contoh ke dalam main.tf yang baru dibuat.

   Atau, salin kode dari GitHub. Tindakan ini direkomendasikan jika cuplikan Terraform adalah bagian dari solusi menyeluruh.

3. Tinjau dan ubah contoh parameter untuk diterapkan pada lingkungan Anda.
4. Simpan perubahan Anda.
5. Lakukan inisialisasi Terraform. Anda hanya perlu melakukan ini sekali per direktori.

   terraform init

   Secara opsional, untuk menggunakan versi penyedia Google terbaru, sertakan opsi -upgrade:

   terraform init -upgrade

Menerapkan perubahan

1. Tinjau konfigurasi dan pastikan resource yang akan dibuat atau diupdate oleh Terraform sesuai yang Anda inginkan:

   terraform plan

   Koreksi konfigurasi jika diperlukan.

2. Terapkan konfigurasi Terraform dengan menjalankan perintah berikut dan memasukkan yes pada prompt:

   terraform apply

   Tunggu hingga Terraform menampilkan pesan "Apply complete!".

3. Buka project Google Cloud Anda untuk melihat hasilnya. Di konsol Google Cloud , buka resource Anda di UI untuk memastikan bahwa Terraform telah membuat atau mengupdatenya.

Catatan: Contoh Terraform biasanya mengasumsikan bahwa API yang diperlukan diaktifkan di project Google Cloud Anda.

API

Untuk menjalankan kueri menggunakan API, sisipkan tugas baru dan isi properti konfigurasi tugas query. Anda juga bisa menentukan lokasi di properti location di bagian jobReference di resource tugas.

Lakukan polling untuk hasil dengan memanggil getQueryResults. Polling hingga jobComplete sama dengan true. Periksa error dan peringatan dalam daftar errors.

C#

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan C# di Panduan memulai BigQuery menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi BigQuery C# API.

Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

using Google.Cloud.BigQuery.V2;
using System;

public class BigQueryQuery
{
    public void Query(
        string projectId = "your-project-id"
    )
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        string query = @"
            SELECT name FROM `bigquery-public-data.usa_names.usa_1910_2013`
            WHERE state = 'TX'
            LIMIT 100";
        BigQueryJob job = client.CreateQueryJob(
            sql: query,
            parameters: null,
            options: new QueryOptions { UseQueryCache = false });
        // Wait for the job to complete.
        job = job.PollUntilCompleted().ThrowOnAnyError();
        // Display the results
        foreach (BigQueryRow row in client.GetQueryResults(job.Reference))
        {
            Console.WriteLine($"{row["name"]}");
        }
    }
}

Go

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Go di Panduan memulai BigQuery menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi BigQuery Go API.

Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/bigquery"
	"google.golang.org/api/iterator"
)

// queryBasic demonstrates issuing a query and reading results.
func queryBasic(w io.Writer, projectID string) error {
	// projectID := "my-project-id"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	q := client.Query(
		"SELECT name FROM `bigquery-public-data.usa_names.usa_1910_2013` " +
			"WHERE state = \"TX\" " +
			"LIMIT 100")
	// Location must match that of the dataset(s) referenced in the query.
	q.Location = "US"
	// Run the query and print results when the query job is completed.
	job, err := q.Run(ctx)
	if err != nil {
		return err
	}
	status, err := job.Wait(ctx)
	if err != nil {
		return err
	}
	if err := status.Err(); err != nil {
		return err
	}
	it, err := job.Read(ctx)
	for {
		var row []bigquery.Value
		err := it.Next(&row)
		if err == iterator.Done {
			break
		}
		if err != nil {
			return err
		}
		fmt.Fprintln(w, row)
	}
	return nil
}

Java

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Java di Panduan memulai BigQuery menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi BigQuery Java API.

Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.QueryJobConfiguration;
import com.google.cloud.bigquery.TableResult;

public class SimpleQuery {

  public static void main(String[] args) {
    // TODO(developer): Replace this query before running the sample.
    String query =
        "SELECT name, SUM(number) as total_people "
            + "FROM `bigquery-public-data.usa_names.usa_1910_2013` "
            + "WHERE state = 'TX' "
            + "GROUP BY name, state "
            + "ORDER BY total_people DESC "
            + "LIMIT 100;";
    simpleQuery(query);
  }

  public static void simpleQuery(String query) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      // Create the query job.
      QueryJobConfiguration queryConfig = QueryJobConfiguration.newBuilder(query).build();

      // Execute the query.
      TableResult result = bigquery.query(queryConfig);

      // Print the results.
      result
          .iterateAll()
          .forEach(
              row -> {
                System.out.print("name:" + row.get("name").getStringValue());
                System.out.print(", count:" + row.get("total_people").getLongValue());
                System.out.println();
              });

      System.out.println("Query ran successfully");
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Query did not run \n" + e.toString());
    }
  }
}

Untuk menjalankan kueri dengan proxy, lihat Mengonfigurasi proxy.

Node.js

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Node.js di Panduan memulai BigQuery menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi BigQuery Node.js API.

Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

// Import the Google Cloud client library using default credentials
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();
async function query() {
  // Queries the U.S. given names dataset for the state of Texas.

  const query = `SELECT name
    FROM \`bigquery-public-data.usa_names.usa_1910_2013\`
    WHERE state = 'TX'
    LIMIT 100`;

  // For all options, see https://cloud.google.com/bigquery/docs/reference/rest/v2/jobs/query
  const options = {
    query: query,
    // Location must match that of the dataset(s) referenced in the query.
    location: 'US',
  };

  // Run the query as a job
  const [job] = await bigquery.createQueryJob(options);
  console.log(`Job ${job.id} started.`);

  // Wait for the query to finish
  const [rows] = await job.getQueryResults();

  // Print the results
  console.log('Rows:');
  rows.forEach(row => console.log(row));
}

PHP

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan PHP di Panduan memulai BigQuery menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi BigQuery PHP API.

Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

use Google\Cloud\BigQuery\BigQueryClient;
use Google\Cloud\Core\ExponentialBackoff;

/** Uncomment and populate these variables in your code */
// $projectId = 'The Google project ID';
// $query = 'SELECT id, view_count FROM `bigquery-public-data.stackoverflow.posts_questions`';

$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$jobConfig = $bigQuery->query($query);
$job = $bigQuery->startQuery($jobConfig);

$backoff = new ExponentialBackoff(10);
$backoff->execute(function () use ($job) {
    print('Waiting for job to complete' . PHP_EOL);
    $job->reload();
    if (!$job->isComplete()) {
        throw new Exception('Job has not yet completed', 500);
    }
});
$queryResults = $job->queryResults();

$i = 0;
foreach ($queryResults as $row) {
    printf('--- Row %s ---' . PHP_EOL, ++$i);
    foreach ($row as $column => $value) {
        printf('%s: %s' . PHP_EOL, $column, json_encode($value));
    }
}
printf('Found %s row(s)' . PHP_EOL, $i);

Python

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Python di Panduan memulai BigQuery menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi BigQuery Python API.

Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

query = """
    SELECT name, SUM(number) as total_people
    FROM `bigquery-public-data.usa_names.usa_1910_2013`
    WHERE state = 'TX'
    GROUP BY name, state
    ORDER BY total_people DESC
    LIMIT 20
"""
rows = client.query_and_wait(query)  # Make an API request.

print("The query data:")
for row in rows:
    # Row values can be accessed by field name or index.
    print("name={}, count={}".format(row[0], row["total_people"]))

Ruby

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Ruby di Panduan memulai BigQuery menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi BigQuery Ruby API.

Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

require "google/cloud/bigquery"

def query
  bigquery = Google::Cloud::Bigquery.new
  sql = "SELECT name FROM `bigquery-public-data.usa_names.usa_1910_2013` " \
        "WHERE state = 'TX' " \
        "LIMIT 100"

  # Location must match that of the dataset(s) referenced in the query.
  results = bigquery.query sql do |config|
    config.location = "US"
  end

  results.each do |row|
    puts row.inspect
  end
end

Uji coba

Uji coba di BigQuery memberikan informasi berikut:

• perkiraan tagihan dalam mode on demand
• validasi kueri
• perkiraan byte yang diproses oleh kueri dalam mode kapasitas

Uji coba tidak menggunakan slot kueri, dan Anda tidak dikenai biaya untuk melakukan uji coba. Anda dapat menggunakan perkiraan yang ditampilkan oleh uji coba untuk menghitung biaya kueri di kalkulator harga.

Catatan: Uji coba kueri gabungan yang menggunakan sumber data eksternal mungkin melaporkan batas bawah 0 byte data, meskipun baris ditampilkan. Hal ini karena jumlah data yang diproses dari tabel eksternal tidak dapat ditentukan hingga kueri sebenarnya selesai. Menjalankan kueri gabungan masih menimbulkan biaya untuk pemrosesan data ini.

Perhatian: Uji coba pada tabel yang disamarkan oleh keamanan tingkat baris selalu menampilkan 0 byte untuk mencegah serangan side-channel. Untuk tabel ini, Anda tidak dapat mengandalkan uji coba untuk memperkirakan biaya kueri.

Melakukan uji coba

Untuk melakukan uji coba, lakukan hal berikut:

Konsol

1. Buka halaman BigQuery.

   Buka BigQuery

2. Masukkan kueri Anda di editor kueri.

   Jika kueri valid, tanda centang akan muncul secara otomatis bersama dengan jumlah data yang akan diproses oleh kueri. Jika kueri tidak valid, tanda seru akan muncul bersama dengan pesan error.

bq

Masukkan kueri seperti berikut menggunakan flag --dry_run.

bq query \
--use_legacy_sql=false \
--dry_run \
'SELECT
   COUNTRY,
   AIRPORT,
   IATA
 FROM
   `project_id`.dataset.airports
 LIMIT
   1000'
 

Untuk kueri yang valid, perintah tersebut menghasilkan respons berikut:

Query successfully validated. Assuming the tables are not modified,
running this query will process 10918 bytes of data.

Catatan: Jika kueri memproses data dalam jumlah kecil, Anda mungkin perlu mengonversi byte yang diproses dari KB ke MB. MB adalah ukuran terkecil yang digunakan oleh kalkulator harga.

API

Untuk melakukan uji coba menggunakan API, kirim tugas kueri dengan dryRun ditetapkan ke true pada jenis JobConfiguration.

Go

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Go di Panduan memulai BigQuery menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi BigQuery Go API.

Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/bigquery"
)

// queryDryRun demonstrates issuing a dry run query to validate query structure and
// provide an estimate of the bytes scanned.
func queryDryRun(w io.Writer, projectID string) error {
	// projectID := "my-project-id"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	q := client.Query(`
	SELECT
		name,
		COUNT(*) as name_count
	FROM ` + "`bigquery-public-data.usa_names.usa_1910_2013`" + `
	WHERE state = 'WA'
	GROUP BY name`)
	q.DryRun = true
	// Location must match that of the dataset(s) referenced in the query.
	q.Location = "US"

	job, err := q.Run(ctx)
	if err != nil {
		return err
	}
	// Dry run is not asynchronous, so get the latest status and statistics.
	status := job.LastStatus()
	if err := status.Err(); err != nil {
		return err
	}
	fmt.Fprintf(w, "This query will process %d bytes\n", status.Statistics.TotalBytesProcessed)
	return nil
}

Java

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Java di Panduan memulai BigQuery menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi BigQuery Java API.

Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Job;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.JobStatistics;
import com.google.cloud.bigquery.QueryJobConfiguration;

// Sample to run dry query on the table
public class QueryDryRun {

  public static void runQueryDryRun() {
    String query =
        "SELECT name, COUNT(*) as name_count "
            + "FROM `bigquery-public-data.usa_names.usa_1910_2013` "
            + "WHERE state = 'WA' "
            + "GROUP BY name";
    queryDryRun(query);
  }

  public static void queryDryRun(String query) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      QueryJobConfiguration queryConfig =
          QueryJobConfiguration.newBuilder(query).setDryRun(true).setUseQueryCache(false).build();

      Job job = bigquery.create(JobInfo.of(queryConfig));
      JobStatistics.QueryStatistics statistics = job.getStatistics();

      System.out.println(
          "Query dry run performed successfully." + statistics.getTotalBytesProcessed());
    } catch (BigQueryException e) {
      System.out.println("Query not performed \n" + e.toString());
    }
  }
}

Node.js

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Node.js di Panduan memulai BigQuery menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi BigQuery Node.js API.

Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

// Import the Google Cloud client library
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

async function queryDryRun() {
  // Runs a dry query of the U.S. given names dataset for the state of Texas.

  const query = `SELECT name
    FROM \`bigquery-public-data.usa_names.usa_1910_2013\`
    WHERE state = 'TX'
    LIMIT 100`;

  // For all options, see https://cloud.google.com/bigquery/docs/reference/rest/v2/jobs/query
  const options = {
    query: query,
    // Location must match that of the dataset(s) referenced in the query.
    location: 'US',
    dryRun: true,
  };

  // Run the query as a job
  const [job] = await bigquery.createQueryJob(options);

  // Print the status and statistics
  console.log('Status:');
  console.log(job.metadata.status);
  console.log('\nJob Statistics:');
  console.log(job.metadata.statistics);
}

PHP

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan PHP di Panduan memulai BigQuery menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi BigQuery PHP API.

Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

use Google\Cloud\BigQuery\BigQueryClient;

/** Uncomment and populate these variables in your code */
// $projectId = 'The Google project ID';
// $query = 'SELECT id, view_count FROM `bigquery-public-data.stackoverflow.posts_questions`';

// Construct a BigQuery client object.
$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);

// Set job configs
$jobConfig = $bigQuery->query($query);
$jobConfig->useQueryCache(false);
$jobConfig->dryRun(true);

// Extract query results
$queryJob = $bigQuery->startJob($jobConfig);
$info = $queryJob->info();

printf('This query will process %s bytes' . PHP_EOL, $info['statistics']['totalBytesProcessed']);

Python

Tetapkan properti QueryJobConfig.dry_run ke True. Client.query() selalu menampilkan QueryJob yang telah selesai saat diberi konfigurasi kueri uji coba.

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Python di Panduan memulai BigQuery menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi BigQuery Python API.

Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

job_config = bigquery.QueryJobConfig(dry_run=True, use_query_cache=False)

# Start the query, passing in the extra configuration.
query_job = client.query(
    (
        "SELECT name, COUNT(*) as name_count "
        "FROM `bigquery-public-data.usa_names.usa_1910_2013` "
        "WHERE state = 'WA' "
        "GROUP BY name"
    ),
    job_config=job_config,
)  # Make an API request.

# A dry run query completes immediately.
print("This query will process {} bytes.".format(query_job.total_bytes_processed))

Memecahkan masalah kueri

Untuk mengetahui informasi tentang cara menyelesaikan masalah saat Anda menjalankan kueri, lihat Memecahkan masalah kueri.

Menjalankan kueri batch

Untuk menjalankan kueri batch, pilih salah satu opsi berikut:

Konsol

1. Buka halaman BigQuery.

   Buka BigQuery

2. Klik Kueri SQL.

3. Di editor kueri, masukkan kueri GoogleSQL yang valid.

   Misalnya, buat kueri set data publik BigQuery usa_names untuk menentukan nama yang paling umum di Amerika Serikat antara tahun 1910 dan 2013:

   SELECT
     name, gender,
     SUM(number) AS total
   FROM
     `bigquery-public-data.usa_names.usa_1910_2013`
   GROUP BY
     name, gender
   ORDER BY
     total DESC
   LIMIT
     10;
   

4. Klik Edit > Query settings.

5. Di bagian Resource management, pilih Batch.

6. Opsional: Sesuaikan setelan kueri Anda.

7. Klik Simpan.

8. Klik Run.

   Jika Anda tidak menentukan tabel tujuan, tugas kueri akan menulis output ke tabel sementara (cache).

bq

1. Di konsol Google Cloud , aktifkan Cloud Shell.

   Aktifkan Cloud Shell

   Di bagian bawah konsol Google Cloud , sesi Cloud Shell akan dimulai dan menampilkan prompt command line. Cloud Shell adalah lingkungan shell dengan Google Cloud CLI yang sudah terinstal, dan dengan nilai yang sudah ditetapkan untuk project Anda saat ini. Diperlukan waktu beberapa detik untuk melakukan inisialisasi pada sesi.

2. Gunakan perintah bq query dan tentukan flag --batch. Pada contoh berikut, flag --use_legacy_sql=false memungkinkan Anda menggunakan sintaksis GoogleSQL.

   bq query \
       --batch \
       --use_legacy_sql=false \
       'QUERY'

   Ganti QUERY dengan kueri GoogleSQL yang valid. Misalnya, buat kueri set data publik BigQuery usa_names untuk menentukan nama yang paling umum di Amerika Serikat antara tahun 1910 dan 2013:

   bq query \
       --batch \
       --use_legacy_sql=false \
       'SELECT
         name, gender,
         SUM(number) AS total
       FROM
         `bigquery-public-data.usa_names.usa_1910_2013`
       GROUP BY
         name, gender
       ORDER BY
         total DESC
       LIMIT
         10;'
   

   Tugas kueri menulis output ke tabel sementara (cache).

   Selain itu, Anda dapat menentukan tabel tujuan dan lokasi untuk hasil kueri. Untuk menulis hasilnya ke tabel yang sudah ada, sertakan flag yang sesuai untuk menambahkan (--append_table=true) atau menimpa (--replace=true) tabel.

   bq query \
       --batch \
       --location=LOCATION \
       --destination_table=TABLE \
       --use_legacy_sql=false \
       'QUERY'

   Ganti kode berikut:

   • LOCATION: region atau multi-region untuk tabel tujuan—misalnya, US

     Dalam contoh ini, set data usa_names disimpan di lokasi multi-region AS. Jika Anda menentukan tabel tujuan untuk kueri ini, set data yang berisi tabel tujuan juga harus berada di multi-region AS. Anda tidak dapat mengkueri set data di satu lokasi dan menulis hasilnya ke tabel di lokasi lain.

     Anda dapat menetapkan nilai default untuk lokasi menggunakan .bigqueryrc file.

   • TABLE: nama untuk tabel tujuan—misalnya, myDataset.myTable

     Jika tabel tujuan adalah tabel baru, BigQuery akan membuat tabel tersebut saat Anda menjalankan kueri. Namun, Anda harus menentukan set data yang sudah ada.

     Jika tabel tidak ada dalam project Anda saat ini, tambahkan project IDGoogle Cloud menggunakan format PROJECT_ID:DATASET.TABLE—misalnya, myProject:myDataset.myTable. Jika --destination_table tidak ditentukan, tugas kueri akan dibuat yang menulis output ke tabel sementara.

API

Untuk menjalankan kueri menggunakan API, sisipkan tugas baru dan isi properti konfigurasi tugas query. Anda juga bisa menentukan lokasi di properti location di bagian jobReference di resource tugas.

Saat Anda mengisi properti tugas kueri, sertakan properti configuration.query.priority dan tetapkan nilainya ke BATCH.

Lakukan polling untuk hasil dengan memanggil getQueryResults. Polling hingga jobComplete sama dengan true. Periksa error dan peringatan dalam daftar errors.

Go

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Go di Panduan memulai BigQuery menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi BigQuery Go API.

Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

import (
	"context"
	"fmt"
	"io"
	"time"

	"cloud.google.com/go/bigquery"
)

// queryBatch demonstrates issuing a query job using batch priority.
func queryBatch(w io.Writer, projectID, dstDatasetID, dstTableID string) error {
	// projectID := "my-project-id"
	// dstDatasetID := "mydataset"
	// dstTableID := "mytable"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	// Build an aggregate table.
	q := client.Query(`
		SELECT
  			corpus,
  			SUM(word_count) as total_words,
  			COUNT(1) as unique_words
		FROM ` + "`bigquery-public-data.samples.shakespeare`" + `
		GROUP BY corpus;`)
	q.Priority = bigquery.BatchPriority
	q.QueryConfig.Dst = client.Dataset(dstDatasetID).Table(dstTableID)

	// Start the job.
	job, err := q.Run(ctx)
	if err != nil {
		return err
	}
	// Job is started and will progress without interaction.
	// To simulate other work being done, sleep a few seconds.
	time.Sleep(5 * time.Second)
	status, err := job.Status(ctx)
	if err != nil {
		return err
	}

	state := "Unknown"
	switch status.State {
	case bigquery.Pending:
		state = "Pending"
	case bigquery.Running:
		state = "Running"
	case bigquery.Done:
		state = "Done"
	}
	// You can continue to monitor job progress until it reaches
	// the Done state by polling periodically.  In this example,
	// we print the latest status.
	fmt.Fprintf(w, "Job %s in Location %s currently in state: %s\n", job.ID(), job.Location(), state)

	return nil

}

Java

Untuk menjalankan kueri batch, tetapkan prioritas kueri ke QueryJobConfiguration.Priority.BATCH saat membuat QueryJobConfiguration.

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Java di panduan memulai BigQuery menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi BigQuery Java API.

Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.QueryJobConfiguration;
import com.google.cloud.bigquery.TableResult;

// Sample to query batch in a table
public class QueryBatch {

  public static void runQueryBatch() {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "MY_PROJECT_ID";
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    String query =
        "SELECT corpus"
            + " FROM `"
            + projectId
            + "."
            + datasetName
            + "."
            + tableName
            + " GROUP BY corpus;";
    queryBatch(query);
  }

  public static void queryBatch(String query) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      QueryJobConfiguration queryConfig =
          QueryJobConfiguration.newBuilder(query)
              // Run at batch priority, which won't count toward concurrent rate limit.
              .setPriority(QueryJobConfiguration.Priority.BATCH)
              .build();

      TableResult results = bigquery.query(queryConfig);

      results
          .iterateAll()
          .forEach(row -> row.forEach(val -> System.out.printf("%s,", val.toString())));

      System.out.println("Query batch performed successfully.");
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Query batch not performed \n" + e.toString());
    }
  }
}

Node.js

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Node.js di Panduan memulai BigQuery menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi BigQuery Node.js API.

Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

// Import the Google Cloud client library and create a client
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

async function queryBatch() {
  // Runs a query at batch priority.

  // Create query job configuration. For all options, see
  // https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#jobconfigurationquery
  const queryJobConfig = {
    query: `SELECT corpus
            FROM \`bigquery-public-data.samples.shakespeare\` 
            LIMIT 10`,
    useLegacySql: false,
    priority: 'BATCH',
  };

  // Create job configuration. For all options, see
  // https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#jobconfiguration
  const jobConfig = {
    // Specify a job configuration to set optional job resource properties.
    configuration: {
      query: queryJobConfig,
    },
  };

  // Make API request.
  const [job] = await bigquery.createJob(jobConfig);

  const jobId = job.metadata.id;
  const state = job.metadata.status.state;
  console.log(`Job ${jobId} is currently in state ${state}`);
}

Python

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Python di Panduan memulai BigQuery menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi BigQuery Python API.

Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

job_config = bigquery.QueryJobConfig(
    # Run at batch priority, which won't count toward concurrent rate limit.
    priority=bigquery.QueryPriority.BATCH
)

sql = """
    SELECT corpus
    FROM `bigquery-public-data.samples.shakespeare`
    GROUP BY corpus;
"""

# Start the query, passing in the extra configuration.
query_job = client.query(sql, job_config=job_config)  # Make an API request.

# Check on the progress by getting the job's updated state. Once the state
# is `DONE`, the results are ready.
query_job = client.get_job(
    query_job.job_id, location=query_job.location
)  # Make an API request.

print("Job {} is currently in state {}".format(query_job.job_id, query_job.state))

Menjalankan kueri berkelanjutan

Menjalankan tugas kueri berkelanjutan memerlukan konfigurasi tambahan. Untuk mengetahui informasi selengkapnya, lihat Membuat kueri berkelanjutan.

Menggunakan panel Referensi

Di editor kueri, panel Reference secara dinamis menampilkan informasi yang peka konteks tentang tabel, snapshot, tampilan, dan tampilan terwujud. Panel ini memungkinkan Anda melihat pratinjau detail skema resource ini, atau membukanya di tab baru. Anda juga dapat menggunakan panel Reference untuk membuat kueri baru atau mengedit kueri yang ada dengan menyisipkan cuplikan kueri atau nama kolom.

Untuk membuat kueri baru menggunakan panel Reference, ikuti langkah-langkah berikut:

1. Di konsol Google Cloud , buka halaman BigQuery.

   Buka BigQuery

2. Klik Kueri SQL.

3. Klik quick_reference_all Reference.

4. Klik tabel atau tampilan terbaru atau berbintang. Anda juga dapat menggunakan kotak penelusuran untuk menemukan tabel dan tampilan.

5. Klik View actions, lalu klik Insert query snippet.

   

6. Opsional: Anda dapat melihat pratinjau detail skema tabel atau tampilan, atau membukanya di tab baru.

7. Sekarang Anda dapat mengedit kueri secara manual atau menyisipkan nama kolom langsung ke kueri. Untuk menyisipkan nama kolom, arahkan kursor dan klik tempat di editor kueri tempat Anda ingin menyisipkan nama kolom, lalu klik nama kolom di panel Reference.

Setelan kueri

Saat menjalankan kueri, Anda dapat menentukan setelan berikut:

• Tabel tujuan untuk hasil kueri.

• Prioritas tugas.

• Apakah akan menggunakan hasil kueri yang di-cache.

• Waktu tunggu tugas dalam milidetik.

• Apakah akan menggunakan mode sesi.

• Jenis enkripsi yang akan digunakan.

• Jumlah byte maksimum yang ditagih untuk kueri.

• Dialek SQL yang akan digunakan.

• Lokasi tempat menjalankan kueri. Kueri harus berjalan di lokasi yang sama dengan tabel yang direferensikan dalam kueri.

• Pemesanan untuk menjalankan kueri Anda.

Mode pembuatan tugas opsional

Mode pembuatan tugas opsional dapat meningkatkan latensi keseluruhan kueri yang berjalan dalam durasi singkat, seperti kueri dari dasbor atau workload eksplorasi data. Mode ini menjalankan kueri dan menampilkan hasil inline untuk pernyataan SELECT tanpa memerlukan penggunaan jobs.getQueryResults untuk mengambil hasil. Kueri yang menggunakan mode pembuatan tugas opsional tidak membuat tugas saat dijalankan, kecuali jika BigQuery menentukan bahwa pembuatan tugas diperlukan untuk menyelesaikan kueri.

Untuk mengaktifkan mode pembuatan tugas opsional, tetapkan kolom jobCreationMode dari instance QueryRequest ke JOB_CREATION_OPTIONAL dalam isi permintaan jobs.query.

Jika nilai kolom ini ditetapkan ke JOB_CREATION_OPTIONAL, BigQuery akan menentukan apakah kueri dapat menggunakan mode pembuatan tugas opsional. Jika demikian, BigQuery akan menjalankan kueri dan menampilkan semua hasil di kolom rows respons. Karena tugas tidak dibuat untuk kueri ini, BigQuery tidak menampilkan jobReference dalam isi respons. Sebagai gantinya, fungsi ini menampilkan kolom queryId, yang dapat Anda gunakan untuk mendapatkan insight tentang kueri menggunakan tampilan INFORMATION_SCHEMA.JOBS. Karena tidak ada tugas yang dibuat, tidak ada jobReference yang dapat diteruskan ke API jobs.get dan jobs.getQueryResults untuk mencari kueri ini.

Jika BigQuery menentukan bahwa tugas diperlukan untuk menyelesaikan kueri, jobReference akan ditampilkan. Anda dapat memeriksa kolom job_creation_reason di tampilan INFORMATION_SCHEMA.JOBS untuk menentukan alasan tugas dibuat untuk kueri. Dalam hal ini, Anda harus menggunakan jobs.getQueryResults untuk mengambil hasil saat kueri selesai.

Saat Anda menggunakan nilai JOB_CREATION_OPTIONAL, kolom jobReference mungkin tidak ada dalam respons. Periksa apakah kolom tersebut ada sebelum mengaksesnya.

Jika JOB_CREATION_OPTIONAL ditentukan untuk kueri multi-pernyataan (skrip), BigQuery dapat mengoptimalkan proses eksekusi. Sebagai bagian dari pengoptimalan ini, BigQuery mungkin menentukan bahwa BigQuery dapat menyelesaikan skrip dengan membuat resource tugas yang lebih sedikit daripada jumlah pernyataan individual, bahkan berpotensi mengeksekusi seluruh skrip tanpa membuat tugas sama sekali. Pengoptimalan ini bergantung pada penilaian BigQuery terhadap skrip, dan pengoptimalan mungkin tidak diterapkan dalam setiap kasus. Pengoptimalan sepenuhnya diotomatiskan oleh sistem. Tidak diperlukan kontrol atau tindakan pengguna.

Untuk menjalankan kueri menggunakan mode pembuatan tugas opsional, pilih salah satu opsi berikut:

Konsol

1. Buka halaman BigQuery.

   Buka BigQuery

2. Klik Kueri SQL.

3. Di editor kueri, masukkan kueri GoogleSQL yang valid.

   Misalnya, buat kueri set data publik BigQuery usa_names untuk menentukan nama yang paling umum di Amerika Serikat antara tahun 1910 dan 2013:

   SELECT
     name, gender,
     SUM(number) AS total
   FROM
     `bigquery-public-data.usa_names.usa_1910_2013`
   GROUP BY
     name, gender
   ORDER BY
     total DESC
   LIMIT
     10;
   

4. Klik Edit > Query mode > Optional job creation. Untuk mengonfirmasi pilihan ini, klik Konfirmasi.

5. Klik Run.

bq

1. Di konsol Google Cloud , aktifkan Cloud Shell.

   Aktifkan Cloud Shell

   Di bagian bawah konsol Google Cloud , sesi Cloud Shell akan dimulai dan menampilkan prompt command line. Cloud Shell adalah lingkungan shell dengan Google Cloud CLI yang sudah terinstal, dan dengan nilai yang sudah ditetapkan untuk project Anda saat ini. Diperlukan waktu beberapa detik untuk melakukan inisialisasi pada sesi.

2. Gunakan perintah bq query dan tentukan flag --job_creation_mode=JOB_CREATION_OPTIONAL. Pada contoh berikut, flag --use_legacy_sql=false memungkinkan Anda menggunakan sintaksis GoogleSQL.

   bq query \
       --rpc=true \
       --use_legacy_sql=false \
       --job_creation_mode=JOB_CREATION_OPTIONAL \
       --location=LOCATION \
       'QUERY'

   Ganti QUERY dengan kueri GoogleSQL yang valid, dan ganti LOCATION dengan region yang valid tempat set data berada. Misalnya, buat kueri set data publik BigQuery usa_names untuk menentukan nama yang paling umum di Amerika Serikat antara tahun 1910 dan 2013:

   bq query \
       --rpc=true \
       --use_legacy_sql=false \
       --job_creation_mode=JOB_CREATION_OPTIONAL \
       --location=us \
       'SELECT
         name, gender,
         SUM(number) AS total
       FROM
         `bigquery-public-data.usa_names.usa_1910_2013`
       GROUP BY
         name, gender
       ORDER BY
         total DESC
       LIMIT
         10;'
   

   Tugas kueri menampilkan output inline dalam respons.

   Catatan: Anda dapat menggunakan --apilog=stdout untuk mencatat permintaan dan respons API ke dalam log guna mengekstrak queryId jika diperlukan.

API

Untuk menjalankan kueri dalam mode pembuatan tugas opsional menggunakan API, jalankan kueri secara sinkron dan isi properti QueryRequest. Sertakan properti jobCreationMode dan tetapkan nilainya ke JOB_CREATION_OPTIONAL.

Periksa responsnya. Jika jobComplete sama dengan true dan jobReference kosong, baca hasilnya dari kolom rows. Anda juga bisa mendapatkan queryId dari respons.

Jika jobReference ada, Anda dapat memeriksa jobCreationReason untuk mengetahui alasan tugas dibuat oleh BigQuery. Lakukan polling untuk hasil dengan memanggil getQueryResults. Polling hingga jobComplete sama dengan true. Periksa error dan peringatan dalam daftar errors.

Java

Versi yang tersedia: 2.51.0 dan yang lebih baru

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Java di Panduan memulai BigQuery menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi BigQuery Java API.

Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.JobId;
import com.google.cloud.bigquery.QueryJobConfiguration;
import com.google.cloud.bigquery.QueryJobConfiguration.JobCreationMode;
import com.google.cloud.bigquery.TableResult;

// Sample demonstrating short mode query execution.
//
// This feature is controlled by setting the defaultJobCreationMode
// field in the BigQueryOptions used for the client. JOB_CREATION_OPTIONAL
// allows for the execution of queries without creating a job.
public class QueryJobOptional {

  public static void main(String[] args) {
    String query =
        "SELECT name, gender, SUM(number) AS total FROM "
            + "bigquery-public-data.usa_names.usa_1910_2013 GROUP BY "
            + "name, gender ORDER BY total DESC LIMIT 10";
    queryJobOptional(query);
  }

  public static void queryJobOptional(String query) {
    try {
      // Initialize client that will be used to send requests. This client only needs
      // to be created once, and can be reused for multiple requests.
      BigQueryOptions options = BigQueryOptions.getDefaultInstance();
      options.setDefaultJobCreationMode(JobCreationMode.JOB_CREATION_OPTIONAL);
      BigQuery bigquery = options.getService();

      // Execute the query. The returned TableResult provides access information
      // about the query execution as well as query results.
      TableResult results = bigquery.query(QueryJobConfiguration.of(query));

      JobId jobId = results.getJobId();
      if (jobId != null) {
        System.out.println("Query was run with job state.  Job ID: " + jobId.toString());
      } else {
        System.out.println("Query was run in short mode.  Query ID: " + results.getQueryId());
      }

      // Print the results.
      results
          .iterateAll()
          .forEach(
              row -> {
                System.out.print("name:" + row.get("name").getStringValue());
                System.out.print(", gender: " + row.get("gender").getStringValue());
                System.out.print(", total: " + row.get("total").getLongValue());
                System.out.println();
              });

    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Query not performed \n" + e.toString());
    }
  }
}

Untuk menjalankan kueri dengan proxy, lihat Mengonfigurasi proxy.

Python

Versi yang tersedia: 3.34.0 dan yang lebih baru

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Python di Panduan memulai BigQuery menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi BigQuery Python API.

Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

# This example demonstrates executing a query without requiring an associated
# job.
from google.cloud import bigquery
from google.cloud.bigquery.enums import JobCreationMode

# Construct a BigQuery client object, specifying that the library should
# avoid creating jobs when possible.
client = bigquery.Client(
    default_job_creation_mode=JobCreationMode.JOB_CREATION_OPTIONAL
)

query = """
    SELECT
        name,
        gender,
        SUM(number) AS total
    FROM
        bigquery-public-data.usa_names.usa_1910_2013
    GROUP BY
        name, gender
    ORDER BY
        total DESC
    LIMIT 10
"""
# Run the query.  The returned `rows` iterator can return information about
# how the query was executed as well as the result data.
rows = client.query_and_wait(query)

if rows.job_id is not None:
    print("Query was run with job state.  Job ID: {}".format(rows.job_id))
else:
    print(
        "Query was run without creating a job.  Query ID: {}".format(rows.query_id)
    )

print("The query data:")
for row in rows:
    # Row values can be accessed by field name or index.
    print("name={}, gender={}, total={}".format(row[0], row[1], row["total"]))

Node

Versi yang tersedia: 8.1.0 dan yang lebih baru

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Node.js di Panduan memulai BigQuery menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi BigQuery Node.js API.

Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

// Demonstrates issuing a query that may be run in short query mode.

// Import the Google Cloud client library
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery({
  // default behavior is to create jobs when using the jobs.query API
  defaultJobCreationMode: 'JOB_CREATION_REQUIRED',
});

async function queryJobOptional() {
  // SQL query to run.

  const sqlQuery = `
    SELECT name, gender, SUM(number) AS total
    FROM bigquery-public-data.usa_names.usa_1910_2013
    GROUP BY name, gender
    ORDER BY total DESC
    LIMIT 10`;

  // Run the query
  const [rows, , res] = await bigquery.query({
    query: sqlQuery,
    // Skip job creation to enable short mode.
    jobCreationMode: 'JOB_CREATION_OPTIONAL',
  });

  if (!res.jobReference) {
    console.log(`Query was run in short mode. Query ID: ${res.queryId}`);
  } else {
    const jobRef = res.jobReference;
    const qualifiedId = `${jobRef.projectId}.${jobRef.location}.${jobRef.jobId}`;
    console.log(
      `Query was run with job state. Job ID: ${qualifiedId}, Query ID: ${res.queryId}`,
    );
  }
  // Print the results
  console.log('Rows:');
  rows.forEach(row => console.log(row));
}

Go

Versi yang tersedia: 1.69.0 dan yang lebih baru

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Go di Panduan memulai BigQuery menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi BigQuery Go API.

Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/bigquery"
	"google.golang.org/api/iterator"
)

// queryJobOptional demonstrates issuing a query that doesn't require a
// corresponding job.
func queryJobOptional(w io.Writer, projectID string) error {
	// projectID := "my-project-id"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID,
		bigquery.WithDefaultJobCreationMode(bigquery.JobCreationModeOptional),
	)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %w", err)
	}
	defer client.Close()

	q := client.Query(`
		SELECT
  			name, gender,
  			SUM(number) AS total
		FROM
			bigquery-public-data.usa_names.usa_1910_2013
		GROUP BY 
			name, gender
		ORDER BY
			total DESC
		LIMIT 10
		`)
	// Run the query and process the returned row iterator.
	it, err := q.Read(ctx)
	if err != nil {
		return fmt.Errorf("query.Read(): %w", err)
	}

	// The iterator provides information about the query execution.
	// Queries that were run in short query mode will not have the source job
	// populated.
	if it.SourceJob() == nil {
		fmt.Fprintf(w, "Query was run in optional job mode.  Query ID: %q\n", it.QueryID())
	} else {
		j := it.SourceJob()
		qualifiedJobID := fmt.Sprintf("%s:%s.%s", j.ProjectID(), j.Location(), j.ID())
		fmt.Fprintf(w, "Query was run with job state.  Job ID: %q, Query ID: %q\n",
			qualifiedJobID, it.QueryID())
	}

	// Print row data.
	for {
		var row []bigquery.Value
		err := it.Next(&row)
		if err == iterator.Done {
			break
		}
		if err != nil {
			return err
		}
		fmt.Fprintln(w, row)
	}
	return nil
}

Driver JDBC

Versi yang tersedia: JDBC v1.6.1 dan yang lebih baru

Memerlukan setelan JobCreationMode=2 dalam string koneksi.

    jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;JobCreationMode=2;Location=US;
  

Catatan: Anda dapat menambahkan LogLevel=6;LogPath=log.txt ke string koneksi untuk mengaktifkan logging level TRACE dan mengekstrak informasi pemecahan masalah, termasuk queryId, jika diperlukan.

Driver ODBC

Versi yang tersedia: ODBC v3.0.7.1016 dan yang lebih baru

Memerlukan setelan JobCreationMode=2 di file .ini.

    [ODBC Data Sources]
    Sample DSN=Simba Google BigQuery ODBC Connector 64-bit
    [Sample DSN]
    JobCreationMode=2
  

Catatan: Anda dapat menambahkan LogLevel=6 dan LogPath=log.txt ke file .ini untuk mengaktifkan logging tingkat mendetail dan mengekstrak informasi pemecahan masalah, termasuk queryId, jika diperlukan.

Kueri global

Kueri dijalankan di lokasi data yang dirujuk. Namun, jika kueri mereferensikan data yang disimpan di lebih dari satu lokasi, kueri global akan dijalankan. Saat menjalankan kueri global, BigQuery dapat mengumpulkan semua data yang diperlukan dari berbagai lokasi di satu tempat, menjalankan kueri, dan menampilkan hasilnya. Karena kueri global memerlukan transfer data antar-lokasi, kueri tersebut memerlukan izin tambahan dan dapat menimbulkan biaya tambahan.

Untuk mengetahui informasi selengkapnya tentang kueri global, lihat Kueri global.

Kuota

Untuk mengetahui informasi tentang kuota terkait kueri batch dan interaktif, baca Tugas kueri.

Untuk memecahkan masalah error kuota terkait kueri, lihat halaman Pemecahan Masalah BigQuery. Error kuota berikut dan informasi pemecahan masalahnya terkait langsung dengan kueri:

• Error batas antrean kueri
• Error kuota penambahan kueri atau impor tabel

Memantau kueri

Anda bisa mendapatkan informasi tentang kueri saat kueri tersebut dieksekusi menggunakan penjelajah tugas atau dengan membuat kueri tampilan INFORMATION_SCHEMA.JOBS_BY_PROJECT.

Runtime tingkat lanjut

Runtime BigQuery tingkat lanjut adalah serangkaian peningkatan performa yang dirancang untuk mempercepat workload analisis secara otomatis tanpa memerlukan tindakan pengguna atau perubahan kode. Kueri memanfaatkan pengoptimalan runtime tingkat lanjut secara otomatis saat vektorisasi yang ditingkatkan atau pengoptimalan kueri singkat tersedia.

Vektorisasi yang ditingkatkan

Eksekusi vektor adalah model pemrosesan kueri yang beroperasi pada kolom data dalam blok yang selaras dengan ukuran cache CPU dan menggunakan petunjuk single instruction, multiple data (SIMD). Vektorisasi yang ditingkatkan memperluas eksekusi kueri vektor di BigQuery ke aspek pemrosesan kueri berikut:

• Dengan memanfaatkan encoding data khusus dalam format penyimpanan Capacitor, operasi evaluasi filter dapat dijalankan pada data yang dienkode.
• Encoding khusus disebarkan melalui rencana kueri, sehingga lebih banyak data dapat diproses saat masih dienkode.
• Dengan menerapkan pelipatan ekspresi untuk mengevaluasi fungsi deterministik dan ekspresi konstan, BigQuery dapat menyederhanakan predikat kompleks menjadi nilai konstan.

Pengoptimalan kueri singkat

BigQuery biasanya menjalankan kueri di lingkungan terdistribusi menggunakan lapisan perantara shuffle. Pengoptimalan kueri singkat secara dinamis mengidentifikasi kueri yang dapat dijalankan sebagai satu tahap, sehingga mengurangi latensi dan konsumsi slot. Encoding khusus dapat digunakan secara lebih efektif saat kueri dijalankan dalam satu tahap. Pengoptimalan ini paling efektif jika digunakan dengan mode pembuatan tugas opsional, yang meminimalkan latensi startup tugas, pemeliharaan, dan pengambilan hasil.

Kelayakan untuk pengoptimalan kueri singkat bersifat dinamis dan dipengaruhi oleh faktor-faktor berikut:

• Perkiraan ukuran pemindaian data.
• Jumlah pemindahan data yang diperlukan.
• Selektivitas filter kueri.
• Jenis dan tata letak fisik data dalam penyimpanan.
• Struktur kueri secara keseluruhan.
• Statistik historis dari eksekusi kueri sebelumnya.

Memperkirakan dampak runtime tingkat lanjut

Untuk memperkirakan dampak runtime tingkat lanjut, Anda dapat menggunakan kueri SQL berikut untuk mengidentifikasi kueri project dengan perkiraan peningkatan waktu eksekusi terbesar:

WITH
  jobs AS (
    SELECT
      *,
      query_info.query_hashes.normalized_literals AS query_hash,
      TIMESTAMP_DIFF(end_time, start_time, MILLISECOND) AS elapsed_ms,
      EXISTS(
        SELECT 1
        FROM UNNEST(JSON_QUERY_ARRAY(query_info.optimization_details.optimizations)) AS o
        WHERE JSON_VALUE(o, '$.enhanced_vectorization') = 'applied'
      ) AS has_advanced_runtime
    FROM region-LOCATION.INFORMATION_SCHEMA.JOBS_BY_PROJECT
    WHERE EXTRACT(DATE FROM creation_time) > DATE_SUB(CURRENT_DATE(), INTERVAL 30 DAY)
  ),
  most_recent_jobs_without_advanced_runtime AS (
    SELECT *
    FROM jobs
    WHERE NOT has_advanced_runtime
    QUALIFY ROW_NUMBER() OVER (PARTITION BY query_hash ORDER BY end_time DESC) = 1
  )
SELECT
  job.job_id,
  100 * SAFE_DIVIDE(
    original_job.elapsed_ms - job.elapsed_ms,
    original_job.elapsed_ms) AS percent_execution_time_saved,
  job.elapsed_ms AS new_elapsed_ms,
  original_job.elapsed_ms AS original_elapsed_ms,
FROM jobs AS job
INNER JOIN most_recent_jobs_without_advanced_runtime AS original_job
  USING (query_hash)
WHERE
  job.has_advanced_runtime
  AND original_job.end_time < job.start_time
ORDER BY percent_execution_time_saved DESC
LIMIT 10;

Catatan: Anda hanya dapat membandingkan kueri yang dibuat pada atau setelah 30 Januari 2026, yaitu saat indikator pengoptimalan runtime lanjutan (enhanced_vectorization dan short_query_optimization) tersedia secara konsisten dalam tampilan INFORMATION_SCHEMA.JOBS.

Ganti kode berikut:

• LOCATION: lokasi tempat performa tugas harus diukur

Jika runtime tingkat lanjut diterapkan, hasil kueri ini mungkin mirip dengan berikut ini:

/*--------------+----------------------------+----------------+---------------------*
 |    job_id    | percent_elapsed_time_saved | new_elapsed_ms | original_elapsed_ms |
 +--------------+----------------------------+----------------+---------------------+
 | sample_job1  |         45.38834951456311  |            225 |                 412 |
 | sample_job2  |         45.19480519480519  |            211 |                 385 |
 | sample_job3  |         33.246753246753244 |            257 |                 385 |
 | sample_job4  |         29.28802588996764  |           1311 |                1854 |
 | sample_job5  |         28.18181818181818  |           1027 |                1430 |
 | sample_job6  |         25.804195804195807 |           1061 |                1430 |
 | sample_job7  |         25.734265734265733 |           1062 |                1430 |
 | sample_job8  |         25.454545454545453 |           1066 |                1430 |
 | sample_job9  |         25.384615384615383 |           1067 |                1430 |
 | sample_job10 |         25.034965034965033 |           1072 |                1430 |
 *--------------+----------------------------+----------------+---------------------*/

Hasil kueri ini hanyalah perkiraan dampak runtime tingkat lanjut. Banyak faktor yang dapat memengaruhi performa kueri, termasuk, tetapi tidak terbatas pada ketersediaan slot, perubahan data dari waktu ke waktu, definisi tampilan atau UDF, dan perbedaan nilai parameter kueri.

Jika hasil kueri ini kosong, berarti tidak ada tugas yang menggunakan runtime lanjutan, atau semua tugas telah dioptimalkan lebih dari 30 hari yang lalu.

Kueri ini dapat diterapkan ke metrik performa kueri lainnya seperti total_slot_ms dan total_bytes_billed. Untuk mengetahui informasi selengkapnya, lihat skema untuk INFORMATION_SCHEMA.JOBS_BY_PROJECT.

Langkah berikutnya

• Pelajari cara mengelola tugas kueri.
• Pelajari cara melihat histori kueri.
• Pelajari cara menyimpan dan membagikan kueri.
• Pelajari antrean kueri.
• Pelajari cara menulis hasil kueri.