Struktur kueri

Kueri untuk kolom resource, segmen, dan metrik dapat dikirim ke GoogleAdsService Search atau SearchStream metode. Untuk membuat kueri dalam Bahasa Kueri Google Ads, buat kueri menggunakan tata bahasa. Untuk ringkasan umum Bahasa Kueri Google Ads, lihat Ringkasan Bahasa Kueri Google Ads. Kueri terdiri dari sejumlah klausa:

  • SELECT
  • FROM
  • WHERE
  • ORDER BY
  • LIMIT
  • PARAMETERS

Klausa menggunakan nama kolom, nama resource, operator, kondisi, dan pengurutan untuk membantu Anda memilih data yang benar. Jika digabungkan menjadi satu kueri, Anda dapat mengirim permintaan ke Google Ads API.

Klausa

Bagian berikut menjelaskan tujuan dan sintaksis setiap klausa Bahasa Kueri Google Ads.

SELECT

Klausa SELECT menentukan kumpulan kolom yang akan diambil dalam permintaan. SELECT mengambil daftar kolom resource, kolom segmen, dan metrik yang dipisahkan koma, serta menampilkan nilai dalam respons. Klausa SELECT wajib ada dalam kueri.

Contoh kueri berikut menunjukkan contoh pemilihan atribut untuk resource tertentu:

SELECT
  campaign.id,
  campaign.name
FROM campaign

Anda dapat meminta berbagai jenis kolom dalam satu permintaan, misalnya:

SELECT
  campaign.id,
  campaign.name,
  bidding_strategy.id,
  bidding_strategy.name,
  segments.device,
  segments.date,
  metrics.impressions,
  metrics.clicks
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
  • Kolom resource utama
    • campaign.id
    • campaign.name
  • Kolom resource yang dikaitkan
    • bidding_strategy.id
    • bidding_strategy.name
  • Kolom segmen
    • segments.device
    • segments.date
  • Metrik
    • metrics.impressions
    • metrics.clicks
  • Mengkueri kolom yang tidak dapat dipilih. Kolom ini memiliki atribut metadata selectable yang ditandai sebagai false.
  • Memilih atribut kolom berulang. Kolom ini memiliki atribut metadata is_repeated yang ditandai sebagai true.
  • Memilih kolom yang tidak tersedia untuk resource tertentu dalam klausa FROM. Atribut beberapa resource tidak dapat dipilih bersama-sama, dan hanya subkumpulan dari semua metrik dan segmen yang tersedia untuk resource dalam klausa FROM.
  • Memilih segmen atau metrik yang tidak kompatibel satu sama lain. Untuk mengetahui informasi selengkapnya, lihat Segmentasi.

Informasi terkait kondisi sebelumnya dapat ditemukan dalam dokumentasi referensi kami atau dari GoogleAdsFieldService.

FROM

Klausa FROM menentukan resource utama yang akan ditampilkan. Resource dalam klausa FROM menentukan kolom yang dapat digunakan di semua klausa lainnya untuk kueri tertentu. Hanya satu resource yang dapat ditentukan dalam klausa FROM. Klausa FROM wajib ada dalam kueri ke GoogleAdsService Search atau SearchStream metode. Namun, klausa FROM tidak boleh ditentukan saat menggunakan GoogleAdsFieldService.

Meskipun hanya satu resource yang dapat ada dalam klausa FROM untuk kueri tertentu, kolom dari resource yang dikaitkan juga mungkin tersedia. Resource ini secara implisit digabungkan dengan resource dalam klausa FROM, sehingga Anda hanya perlu menambahkan atributnya ke klausa SELECT untuk menampilkan nilainya. Tidak semua resource memiliki resource yang dikaitkan. Dalam contoh berikut, Anda dapat meminta ID grup iklan dan ID kampanye dari grup iklan:

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

Kolom resource_name dari resource utama selalu ditampilkan. Dalam contoh berikut, ad_group.resource_name disertakan dalam respons meskipun tidak dipilih secara eksplisit dalam kueri:

SELECT ad_group.id
FROM ad_group

Hal yang sama berlaku untuk resource yang dikaitkan jika setidaknya satu kolom dipilih. Misalnya, campaign.resource_name disertakan dalam respons untuk kueri berikut:

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

WHERE

Klausa WHERE menentukan kondisi yang akan diterapkan saat memfilter data untuk permintaan. Saat menggunakan klausa WHERE, tentukan satu atau beberapa kondisi yang dipisahkan oleh AND. Kondisi biasanya mengikuti pola field_name Operator value (atau menggunakan BETWEEN value AND value, IS NULL, atau IS NOT NULL). Klausa WHERE bersifat opsional dalam kueri.

Contoh berikut menggunakan WHERE untuk menampilkan metrik dari jangka waktu tertentu:

SELECT
  campaign.id,
  campaign.name,
  metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

Anda dapat menggabungkan beberapa kondisi untuk memfilter data. Contoh ini meminta jumlah klik untuk semua kampanye dengan tayangan iklan di perangkat seluler dalam 30 hari terakhir:

SELECT
  campaign.id,
  campaign.name,
  segments.device,
  metrics.clicks
FROM campaign
WHERE metrics.impressions > 0
  AND segments.device = 'MOBILE'
  AND segments.date DURING LAST_30_DAYS

Segmen dalam klausa WHERE juga harus berada dalam klausa SELECT, kecuali untuk segmen tanggal berikut, yang disebut sebagai segmen tanggal inti:

  • segments.date
  • segments.week
  • segments.month
  • segments.quarter
  • segments.year

Dalam kueri berikut, segments.date dipilih. Karena segmen ini adalah segmen tanggal inti, Anda harus memberikan rentang tanggal terbatas dalam klausa WHERE yang terdiri dari segmen tanggal inti:

SELECT
  campaign.id,
  campaign.name,
  segments.date,
  metrics.clicks
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

Semua segmen yang memenuhi kondisi sebelumnya adalah segments.date, segments.week, segments.month, segments.quarter, dan segments.year. Jika salah satu segmen ini dipilih, setidaknya satu segmen harus digunakan dalam klausa WHERE.

Untuk mengetahui detail selengkapnya tentang pemfilteran tanggal, lihat Rentang tanggal.

Saat memfilter, perhatikan sensitivitas huruf besar/kecil operator Anda. Untuk mengetahui informasi selengkapnya, lihat Sensitivitas huruf besar/kecil.

Untuk mengetahui daftar lengkap operator, lihat tata bahasa.

ORDER BY

Klausa ORDER BY menentukan urutan hasil yang ditampilkan. Dengan begitu, Anda dapat mengatur data dalam urutan menaik atau menurun berdasarkan nama kolom. Setiap pengurutan ditentukan sebagai field_name yang diikuti oleh ASC atau DESC. Jika ASC maupun DESC tidak ditentukan, urutan akan ditetapkan secara default ke ASC. Klausa ORDER BY bersifat opsional dalam kueri.

Kueri berikut mengurutkan kampanye yang ditampilkan berdasarkan jumlah klik dari tertinggi ke terendah:

SELECT
  campaign.name,
  metrics.clicks
FROM campaign
ORDER BY metrics.clicks DESC

Anda dapat menentukan beberapa kolom dalam klausa ORDER BY menggunakan daftar yang dipisahkan koma. Pengurutan terjadi dalam urutan yang sama seperti yang ditentukan dalam kueri. Misalnya, dalam kueri ini yang memilih data grup iklan, hasilnya diurutkan dalam urutan menaik berdasarkan nama kampanye, lalu dalam urutan menurun berdasarkan jumlah tayangan iklan, lalu dalam urutan menurun berdasarkan jumlah klik:

SELECT
  campaign.name,
  ad_group.name,
  metrics.impressions,
  metrics.clicks
FROM ad_group
ORDER BY
  campaign.name,
  metrics.impressions DESC,
  metrics.clicks DESC

LIMIT

Klausa LIMIT memungkinkan Anda menentukan jumlah hasil yang akan ditampilkan. Hal ini berguna jika Anda hanya memerlukan subkumpulan hasil.

Misalnya, LIMIT dapat membatasi jumlah total hasil untuk kueri berikut:

SELECT
  campaign.name,
  ad_group.name,
  segments.device,
  metrics.impressions
FROM ad_group
ORDER BY metrics.impressions DESC
LIMIT 50

PARAMETERS

Klausa PARAMETERS memungkinkan Anda menentukan parameter meta untuk permintaan. Parameter ini dapat memengaruhi jenis baris yang ditampilkan.

Parameter meta berikut didukung:

include_drafts

Tetapkan include_drafts ke true untuk menampilkan entity draf. Default-nya adalah false.

Misalnya, kueri berikut mengambil kampanye draf beserta kampanye reguler:

SELECT campaign.name
FROM campaign
PARAMETERS include_drafts = true

omit_unselected_resource_names

Tetapkan omit_unselected_resource_names ke true untuk menghapus nama resource setiap jenis resource dalam respons, kecuali jika diminta secara eksplisit dalam klausa SELECT. Default-nya adalah false.

Kueri Resource yang ditampilkan 
SELECT
  campaign.name,
  customer.id
FROM campaign
  • campaign.resource_name
  • customer.resource_name

omit_unselected_resource_names ditetapkan secara default ke false, sehingga semua kolom resource_name ditampilkan.

 
SELECT
  campaign.name,
  customer.id
FROM campaign
PARAMETERS omit_unselected_resource_names = true

Tidak ada

omit_unselected_resource_names ditentukan sebagai true, dan campaign.resource_name maupun customer.resource_name bukan bagian dari klausa SELECT.

 
SELECT
  campaign.name,
  campaign.resource_name
FROM campaign
PARAMETERS omit_unselected_resource_names = true
  • campaign.resource_name

omit_unselected_resource_names ditentukan sebagai true, dan campaign.resource_name diminta sebagai bagian dari klausa SELECT.

Aturan bahasa tambahan

Selain contoh untuk setiap klausa, Bahasa Kueri Google Ads mendukung perilaku berikut:

  • Kolom resource utama tidak diperlukan dalam klausa SELECT untuk kueri. Misalnya, Anda dapat menggunakan satu atau beberapa kolom resource utama untuk memfilter data tanpa memilihnya:

    SELECT campaign.id
FROM ad_group
WHERE ad_group.status = 'PAUSED'

  • Metrik dapat dipilih secara eksklusif untuk resource tertentu; tidak ada kolom lain dari resource yang diperlukan dalam kueri:

    SELECT
  metrics.impressions,
  metrics.clicks,
  metrics.cost_micros
FROM campaign

  • Kolom segmentasi dapat dipilih tanpa kolom resource atau metrik yang menyertainya:

    SELECT segments.device FROM campaign

  • Kolom resource_name (campaign.resource_name, misalnya) dapat di gunakan untuk memfilter atau mengurutkan data:

    SELECT
  campaign.id,
  campaign.name
FROM campaign
WHERE campaign.resource_name = 'customers/1234567/campaigns/987654'
Sebelumnya
Tata bahasa kueri
Berikutnya
Rentang tanggal