Struktur Kueri

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

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

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

Klausul

Video: Kompatibilitas Kolom GAQL

PILIH

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

Contoh kueri di bawah ini menunjukkan contoh pemilihan atribut untuk referensi:

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 klausa SELECT karena hal berikut batasan:

  • Membuat kueri kolom yang tidak dapat dipilih. {i>Field<i} ini akan memiliki Atribut metadata Selectable ditandai sebagai false.
  • Memilih atribut kolom berulang. {i>Field<i} ini akan memiliki Atribut metadata isRepeated ditandai sebagai true.
  • Memilih kolom yang tidak tersedia untuk resource tertentu di FROM . Atribut dari sebagian resource tidak dapat dipilih bersamaan, hanya dari semua metrik dan segmen akan tersedia untuk referensi di Klausa FROM.
  • Memilih segmen atau metrik yang tidak kompatibel satu sama lain. Sebagai informasi selengkapnya tentang hal ini, bagian segmentasi.

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

FROM

Klausa FROM menentukan resource utama yang akan ditampilkan. Tujuan resource dalam klausa FROM menentukan kolom yang dapat digunakan klausa untuk kueri yang ditentukan. Hanya satu resource yang dapat ditentukan dalam Klausa FROM. Klausa FROM diperlukan dalam kueri untuk GoogleAdsService Penelusuran atau SearchStream metode, tetapi tidak boleh ditetapkan saat menggunakan GoogleAdsFieldService.

Meskipun hanya boleh terdapat 1 resource dalam klausa FROM untuk kueri tertentu, kolom dari Resource yang Diatribusikan mungkin juga tersedia. Resource ini secara implisit bergabung dengan resource dalam klausa FROM, sehingga Anda hanya perlu tambahkan 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 dari resource utama selalu ditampilkan. Pada 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 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 waktu tertentu periode:

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 di seluler di 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, 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, maka memerlukan tanggal yang terbatas rentang yang terdiri dari segmen tanggal inti dalam klausul 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 di atas adalah: segments.date, segments.week, Segment.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 saat ini. Lihat bagian Peka huruf besar/kecil untuk detail selengkapnya.

Untuk mengetahui daftar lengkap operator, lihat bahasa tata bahasa.

ORDER BY

Klausa ORDER BY menentukan urutan hasil dikembalikan. Hal ini memungkinkan Anda untuk mengatur data dalam urutan menaik atau menurun. berdasarkan nama kolom. Setiap pengurutan ditetapkan sebagai field_name yang diikuti dengan ASC atau DESC. Jika ASC atau DESC tidak ditentukan, pesanan akan ditetapkan secara default ke ASC. Klausa ORDER BY bersifat opsional dalam kueri.

Kueri berikut mengurutkan kampanye yang dihasilkan 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 karakter yang dipisahkan koma daftar. Pengurutan akan terjadi pada urutan yang sama seperti yang ditentukan dalam kueri. Misalnya, dalam kueri ini dengan memilih data grup iklan, hasilnya akan diurutkan dalam urutan menaik menurut nama kampanye, lalu dalam urutan menurun berdasarkan jumlah tayangan, 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. Fungsi 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 memungkinkan entity draf ditampilkan. Default-nya adalah false.

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

SELECT campaign.name
FROM campaign
PARAMETERS include_drafts=true

omit_unselected_resource_names

Setel omit_unselected_resource_names ke true untuk mencegah nama resource setiap jenis resource dalam respons yang ditampilkan, kecuali jika diminta secara eksplisit dalam klausa SELECT. Defaultnya adalah false.

contoh removed_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 ditetapkan sebagai true serta campaign.resource_name dan 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 ditetapkan 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 beberapa perilaku yang dapat dimanfaatkan:

  • Kolom resource utama tidak harus berada di SELECT untuk kueri. Misalnya, Anda mungkin hanya ingin menggunakan satu atau beberapa kolom resource 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 diperlukan dalam kueri:

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

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

    SELECT segments.device FROM campaign

  • Kolom resource_name (misalnya, campaign.resource_name) dapat berupa 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