Struktur Kueri

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

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

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

Klausul

Video: Kompatibilitas Kolom GAQL

PILIH

Klausa SELECT menentukan kumpulan 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 diperlukan dalam kueri.

Contoh kueri di bawah 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

    • campaign.id
    • campaign.name

  • Kolom resource

    • bidding_strategy.id
    • bidding_strategy.name

  • Kolom segmen

    • segments.device
    • segments.date

  • Metrik

    • metrics.impressions
    • metrics.clicks

Beberapa kolom mungkin tidak diizinkan dalam klausa SELECT, karena pembatasan berikut:

  • Membuat kueri 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 isRepeated yang ditandai sebagai true.
  • Memilih kolom yang tidak tersedia untuk resource tertentu dalam klausa FROM. Atribut dari beberapa resource tidak dapat dipilih secara bersamaan, dan hanya subkumpulan 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 di atas dapat ditemukan dalam dokumen referensi kami atau dari GoogleAdsFieldService.

FROM

Klausa FROM menentukan resource utama yang akan ditampilkan. Resource dalam klausa FROM menentukan kolom yang dapat digunakan oleh semua klausa lainnya untuk kueri yang diberikan. Hanya satu resource yang dapat ditentukan dalam klausa FROM. Klausa FROM diperlukan dalam kueri ke metode GoogleAdsService Search atau SearchStream, tetapi tidak boleh ditentukan saat menggunakan GoogleAdsFieldService.

Meskipun hanya 1 resource yang dapat ada dalam klausa FROM untuk kueri tertentu, kolom dari Resource Beratribut juga dapat tersedia. Resource ini digabungkan secara implisit dengan resource dalam klausa FROM, sehingga Anda hanya perlu menambahkan atributnya ke klausa SELECT untuk menampilkan nilainya. Tidak semua resource memiliki Resource Beratribut. 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. Setiap kondisi harus mengikuti pola field_name Operator value. Klausa WHERE bersifat opsional dalam kueri.

Berikut adalah contoh penggunaan WHERE untuk menampilkan metrik dari periode 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 berada dalam klausa SELECT, dengan segmen tanggal berikut, yang disebut sebagai segmen tanggal inti, merupakan 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 harus disediakan.

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

Semua segmen yang memenuhi kondisi di atas 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.

Saat memfilter, peka huruf besar/kecil operator Anda penting untuk diingat. Lihat Kasus sensitif untuk detail selengkapnya.

Untuk mengetahui daftar lengkap operator, lihat tata bahasa bahasa.

ORDER BY

Klausa ORDER BY menentukan urutan hasil yang akan ditampilkan. Dengan begitu, Anda dapat mengatur data dalam urutan menaik atau menurun berdasarkan nama kolom. Setiap pengurutan ditentukan sebagai field_name, diikuti dengan ASC atau DESC. Jika ASC atau 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 akan terjadi dalam urutan yang sama seperti yang ditentukan dalam kueri. Misalnya, dalam kueri ini yang memilih data grup iklan, hasilnya 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. Hal ini berguna jika Anda hanya tertarik pada 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.

Saat ini, parameter meta berikut didukung:

include_drafts

Tetapkan include_drafts ke true untuk mengizinkan entitas draf ditampilkan. 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 mencegah nama resource setiap jenis resource dalam respons ditampilkan, kecuali jika diminta secara eksplisit dalam klausa SELECT. Defaultnya adalah false.

contoh omit_unselected_resource_names
SELECT
  campaign.name,
  customer.id
FROM campaign
 		Returned resources:
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
 		Returned resources:
Tidak ada.
omit_unselected_resource_names ditentukan sebagai true dan campaign.resource_name serta customer.resource_name bukan bagian dari klausa SELECT. 
SELECT
  campaign.name,
  campaign.resource_name
FROM campaign
PARAMETERS omit_unselected_resource_names = true
 		Returned resource:
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 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 atau metrik resource 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'
Sebelumnya
Tata bahasa kueri
Berikutnya
Rentang tanggal