Struktur kueri

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

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

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

Klausul

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

PILIH

Klausul SELECT menentukan sekumpulan kolom yang akan diambil dalam permintaan. SELECT menggunakan daftar kolom resource, kolom segmen, dan metrik yang dipisahkan koma, yang 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 diatribusikan
  • bidding_strategy.id
  • bidding_strategy.name
• Kolom segmen
  • segments.device
  • segments.date
• Metrik
  • metrics.impressions
  • metrics.clicks

• Mengirim kueri ke kolom yang tidak dapat dipilih. Kolom ini akan memiliki atribut metadata selectable yang ditandai sebagai false.
• Memilih atribut kolom berulang. Kolom ini akan 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, dan hanya subset dari semua metrik dan segmen yang akan tersedia untuk resource dalam klausa FROM.
• Memilih segmen atau metrik yang tidak kompatibel satu sama lain. Untuk mengetahui informasi selengkapnya tentang hal ini, lihat bagian segmentasi.

Informasi terkait kondisi sebelumnya dapat ditemukan di dokumen referensi kami atau dari GoogleAdsFieldService.

FROM

Klausul FROM menentukan resource utama yang akan ditampilkan. Resource dalam klausa FROM menentukan kolom yang dapat digunakan dalam semua klausa lainnya untuk kueri tertentu. Hanya satu resource yang dapat ditentukan dalam klausa FROM. Klausul FROM wajib ada dalam kueri ke metode GoogleAdsService Search atau SearchStream. 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 diatribusikan juga dapat tersedia. Resource ini digabungkan secara implisit dengan resource dalam klausa FROM, jadi Anda hanya perlu menambahkan atributnya ke klausa SELECT untuk menampilkan nilainya. Tidak semua resource memiliki resource yang diatribusikan. 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 akan disertakan dalam respons meskipun tidak dipilih secara eksplisit dalam kueri:

SELECT ad_group.id
FROM ad_group

Hal yang sama berlaku untuk resource lain jika setidaknya satu kolom dipilih. Misalnya, campaign.resource_name akan 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, satu atau beberapa kondisi dapat ditentukan menggunakan AND untuk memisahkannya. 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.

Berikut adalah contoh penggunaan 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 akan 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 harus ada dalam klausa SELECT, dengan segmen tanggal berikut, yang disebut sebagai segmen tanggal inti, menjadi pengecualian:

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

Dalam kueri berikut, perhatikan bahwa segments.date dipilih. Karena segmen ini adalah segmen tanggal inti, segmen ini memerlukan rentang tanggal terbatas yang terdiri dari segmen tanggal inti dalam klausa WHERE yang akan diberikan:

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 salah satunya harus digunakan dalam klausa WHERE.

Lihat Rentang tanggal untuk mengetahui detail selengkapnya tentang pemfilteran tanggal.

Saat memfilter, kepekaan huruf besar/kecil operator penting untuk diingat. Lihat Sensitivitas huruf besar/kecil untuk mengetahui detail selengkapnya.

Untuk mengetahui daftar lengkap operator, lihat tata bahasa.

ORDER BY

Klausa ORDER BY menentukan urutan hasil yang akan ditampilkan. Dengan begitu, Anda dapat menyusun data dalam urutan menaik atau menurun berdasarkan nama kolom. Setiap pengurutan ditentukan sebagai field_name yang diikuti dengan ASC atau DESC. Jika ASC maupun DESC tidak ditentukan, urutan defaultnya adalah ASC. Klausa ORDER BY bersifat opsional dalam kueri.

Kueri berikut mengurutkan kampanye yang ditampilkan berdasarkan jumlah klik dari tertinggi hingga 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 akan terjadi dalam urutan yang sama seperti yang ditentukan dalam kueri. Misalnya, dalam kueri ini yang memilih data grup iklan, hasil akan diurutkan dalam urutan menaik menurut nama kampanye, lalu dalam urutan menurun menurut jumlah tayangan, lalu dalam urutan menurun menurut 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. Opsi ini berguna jika Anda hanya tertarik dengan ringkasan.

Misalnya, LIMIT dapat digunakan untuk 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

PARAMETER

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 agar entity draf dapat ditampilkan. Default-nya adalah false.

Misalnya, kueri berikut mengambil kampanye draf bersama dengan kampanye reguler:

SELECT campaign.name
FROM campaign
PARAMETERS include_drafts=true

omit_unselected_resource_names

Tetapkan omit_unselected_resource_names ke true agar nama resource setiap jenis resource dalam respons tidak ditampilkan kecuali jika diminta secara eksplisit dalam klausa SELECT. Defaultnya adalah false.

SELECT
  campaign.name,
  customer.id
FROM campaign

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

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

Aturan bahasa tambahan

Selain contoh untuk setiap klausa, Google Ads Query Language memiliki perilaku berikut yang dapat digunakan:

• Kolom resource utama tidak harus berada dalam klausa SELECT untuk kueri. Misalnya, Anda mungkin hanya ingin menggunakan satu atau beberapa kolom resource utama untuk memfilter data:

  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 (misalnya, campaign.resource_name) dapat digunakan untuk memfilter atau mengurutkan data:

  SELECT
    campaign.id,
    campaign.name
  FROM campaign
  WHERE campaign.resource_name = 'customers/1234567/campaigns/987654'