Struktur Kueri

Kueri untuk kolom resource, segmen, dan metrik dapat dikirim ke metode GoogleAdsService Search atau SearchStream. 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

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

Klausul

Video: Kompatibilitas Kolom GAQL

SELECT

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

Contoh kueri di bawah ini menunjukkan contoh pemilihan atribut untuk resource tertentu:

SELECT
  campaign.id,
  campaign.name
FROM campaign

Anda dapat meminta jenis kolom yang berbeda 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 klausul SELECT karena pembatasan berikut:

  • Membuat kueri untuk 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 yang diberikan dalam klausa FROM. Atribut beberapa resource tidak dapat dipilih bersama, tetapi hanya sebagian dari semua metrik dan segmen yang akan tersedia untuk resource di klausa FROM.
  • Memilih segmen atau metrik yang tidak kompatibel satu sama lain. Untuk mengetahui informasi selengkapnya tentang hal ini, lihat bagian segmentasi.

Informasi yang terkait dengan kondisi di atas dapat ditemukan di dokumen referensi kami atau dari GoogleAdsFieldService.

FROM

Klausa FROM menentukan resource utama yang akan ditampilkan. Resource dalam klausa FROM menentukan kolom yang dapat digunakan semua klausa lain untuk kueri yang ditentukan. 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 boleh ada 1 resource di klausa FROM untuk kueri tertentu, kolom dari Resource yang Diatribusikan mungkin juga 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 Diatribusikan. Pada 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 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 saat minimal 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 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 menggunakan klausa SELECT, dengan segmen tanggal berikut, yang disebut sebagai segmen tanggal inti, sebagai 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, diperlukan rentang tanggal terbatas yang terdiri dari segmen tanggal inti dalam klausa WHERE untuk diberikan.

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, kepekaan huruf besar/kecil operator Anda penting untuk diperhatikan. Lihat Peka huruf besar/kecil untuk detail selengkapnya.

Untuk mengetahui daftar lengkap operator, lihat tata bahasa bahasa.

ORDER BY

Klausa ORDER BY menentukan urutan tampilan hasil. Hal ini memungkinkan Anda 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, urutannya akan ditetapkan secara default ke ASC. Klausa ORDER BY bersifat opsional dalam kueri.

Kueri berikut mengurutkan kampanye yang ditampilkan berdasarkan jumlah klik dari yang 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. Urutan akan terjadi dalam urutan yang sama seperti yang ditentukan dalam kueri. Misalnya, dalam kueri yang memilih data grup iklan ini, hasilnya akan diurutkan secara 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. 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

Setel include_drafts ke true untuk mengizinkan entitas draf 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

Setel 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.

contoh menghilangkan_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 yang 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 ada 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; kolom lain dari resource tidak diperlukan dalam kueri:

    SELECT
  metrics.impressions,
  metrics.clicks,
  metrics.costMicros
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