Struktur dan klausa kueri

Kueri terdiri dari sejumlah klausa: SELECT, FROM, WHERE, ORDER BY, LIMIT, dan PARAMETERS.

Klausa menggunakan nama kolom, nama resource, operator, kondisi, dan urutan yang digabungkan menjadi satu permintaan kueri.

Secara umum, untuk membuat kueri, Anda harus:

  • Tentukan resource tempat data akan diambil.
  • Tambahkan kolom dan metrik untuk menentukan data yang ingin Anda tampilkan.
  • Tambahkan segmen untuk mengelompokkan hasil.
  • Menambahkan resource yang diatribusikan untuk secara implisit menggabungkan data resource terkait.
  • Filter, urutkan, dan batasi hasil.

Klausa SELECT

Klausa SELECT:

  • Merupakan klausa wajib dalam kueri.
  • Menentukan kumpulan kolom yang akan diambil dalam permintaan.
  • Mengambil daftar kolom resource, kolom kustom, variabel Floodlight kustom, kolom segmen, dan metrik yang dipisahkan koma, lalu menampilkan nilai dalam respons.

Contoh kueri ini menunjukkan cara memilih atribut resource campaign:

SELECT
  campaign.id,
  campaign.name
FROM campaign

Beberapa jenis kolom

Anda dapat meminta jenis kolom yang berbeda dalam permintaan yang sama.

Contoh kueri di bawah menunjukkan satu kueri dengan kombinasi:

  • Kolom resource: campaign.id, campaign.name, bidding_strategy.id, dan bidding_strategy.name.
  • Kolom segmen: segments.device dan segments.date.
  • Kolom metrik: metrics.impressions dan metrics.clicks.
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

Lihat Segmentasi untuk mempelajari lebih lanjut cara menyegmentasikan laporan penelusuran.

Kolom resource utama

Biasanya, Anda akan menyertakan kolom resource utama dalam klausa SELECT, tetapi hal ini bersifat opsional (tidak diperlukan).

Contoh kueri ini menggunakan kolom resource utama (ad_group.status) untuk hanya memfilter hasil.

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

Variabel Floodlight kustom

Anda dapat menyertakan variabel Floodlight kustom dalam klausa SELECT menggunakan ID-nya.

Dalam contoh ini, kueri menyertakan variabel kustom dengan ID 123454321 untuk resource kampanye.

SELECT
  conversion_custom_metrics.id[123454321]
FROM campaign

SELECT
  conversion_custom_dimensions.id[123454321]
FROM campaign

Kolom kustom

Anda dapat menyertakan kolom kustom dalam klausa SELECT menggunakan ID-nya.

Dalam contoh ini, kueri menyertakan kolom kustom dengan ID 12345678 untuk resource kampanye.

SELECT
  custom_columns.id[12345678]
FROM campaign

Lihat cara mendapatkan ID kolom kustom.

Kolom metrik

Anda dapat memilih kolom metrik untuk resource tertentu tanpa menyertakan kolom lain dari resource dalam klausa SELECT.

Contoh kueri ini memilih metrik impressions dan clicks untuk resource campaign.

SELECT
  metrics.impressions,
  metrics.clicks
FROM campaign

Lihat metrics untuk mengetahui daftar kolom metrik yang dapat Anda gunakan dalam kueri.

Kolom segmen

Anda dapat memilih kolom segmen tanpa menentukan kolom resource atau metrik yang menyertainya dalam klausa SELECT.

Contoh kueri ini menyegmentasikan hasil menurut perangkat.

SELECT segments.device
FROM campaign

Lihat segments untuk mengetahui daftar kolom segmen yang dapat Anda gunakan dalam kueri.

Kolom terlarang

Anda tidak dapat menggunakan kolom berikut dalam klausa SELECT:

  • Kolom yang tidak dapat dipilih, yaitu kolom dengan atribut metadata Selectable yang ditandai sebagai false.
  • Kolom berulang, yaitu kolom dengan atribut metadata Repeated yang ditandai sebagai true.
  • Kolom yang tidak tersedia untuk resource tertentu dalam klausa FROM. Atribut beberapa resource tidak dapat dipilih secara bersamaan. Beberapa resource hanya menyediakan subkumpulan dari semua metrik dan segmen.
  • Segmen atau metrik yang tidak kompatibel. Lihat Segmentasi untuk mengetahui informasi selengkapnya.

Lihat Dokumentasi referensi untuk mengetahui detail tentang tempat menemukan informasi ini untuk setiap resource.

Klausa FROM

Klausa FROM:

  • Merupakan klausa wajib untuk kueri ke SearchAds360Service (metode Search dan SearchStream).
  • Tidak boleh disertakan untuk kueri ke SearchAds360FieldService.
  • Menentukan resource utama yang ditampilkan kueri.
  • Hanya dapat menentukan satu resource.
  • Menentukan kolom yang dapat Anda gunakan di semua klausa lain dalam kueri.

Resource yang diatribusikan

Jika tersedia, resource yang diatribusikan akan secara implisit digabungkan dengan resource yang Anda tentukan dalam klausa FROM. Anda hanya perlu menambahkan atributnya ke klausa SELECT untuk menampilkan nilainya.

Contoh kueri ini menampilkan ID grup iklan dan ID kampanye, karena campaign adalah resource yang diatribusikan dari resource ad_group.

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

Kolom resource_name

Kolom resource_name dari resource utama dalam klausa FROM selalu ditampilkan.

Dalam contoh kueri ini, ad_group.resource_name akan disertakan dalam respons walaupun tidak dipilih secara eksplisit dalam kueri:

SELECT ad_group.id
FROM ad_group

Kolom resource_name dari resource yang diatribusikan ditampilkan jika setidaknya satu kolom dipilih.

Dalam contoh kueri ini, campaign.resource_name akan disertakan dalam respons karena campaign.id dipilih:

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

Klausa WHERE

Klausa WHERE:

  • Merupakan klausa opsional dalam kueri.
  • Menentukan kondisi untuk pemfilteran dan segmentasi data untuk permintaan. Kondisi mengikuti pola ini: FIELD_NAME OPERATOR VALUE (dipisahkan oleh spasi kosong).
  • Dapat menyertakan beberapa kondisi yang dipisahkan oleh pemisah AND.

Contoh kueri ini menunjukkan cara menggunakan klausa WHERE untuk menampilkan metrik impressions selama jangka waktu tertentu:

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

Lihat Segmentasi untuk mempelajari lebih lanjut cara menyegmentasikan laporan penelusuran.

Lihat Rentang tanggal untuk mempelajari lebih lanjut cara menentukan rentang tanggal dalam kueri Anda.

Filter menurut kolom resource_name

Anda dapat menggunakan kolom resource_name untuk memfilter atau mengurutkan data.

Contoh kueri ini menggunakan kolom campaign.resource_name untuk memfilter hasil berdasarkan kampanye tertentu:

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

Beberapa kondisi

Anda dapat menggabungkan beberapa kondisi untuk memfilter data.

Contoh kueri ini meminta jumlah metrik clicks untuk semua kampanye dengan metrik impressions di perangkat seluler selama 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

Lihat Segmentasi untuk mempelajari lebih lanjut cara menyegmentasikan laporan.

Kepekaan huruf besar/kecil

Saat memfilter berdasarkan nilai string, kepekaan huruf besar/kecil default setiap operator memainkan peran penting dalam memfilter hasil Anda dengan benar.

Tabel berikut menunjukkan sensitivitas huruf besar/kecil default dari setiap operator.

Kepekaan huruf besar/kecil default
=/!= Case sensitive
IN/NOT IN Case sensitive
LIKE/NOT LIKE Case insensitive
CONTAINS (...) Case sensitive
REGEXP_MATCH/NOT REGEXP_MATCH Case sensitive

Anda dapat menggunakan pengubah (?i) untuk mengubah sensitivitas default untuk REGEXP_MATCH dan NOT REGEXP_MATCH menjadi tidak peka huruf besar/kecil, misalnya:

SELECT campaign.id
FROM campaign
WHERE campaign.name REGEXP_MATCH "(?i).*test.*"

Lihat Referensi tata bahasa kueri untuk mengetahui daftar lengkap operator yang dapat Anda gunakan untuk memfilter data.

Segmen tanggal inti

Kolom segmen berikut dikenal sebagai segmen tanggal inti: segments.date, segments.week, segments.month, segments.quarter, dan segments.year.

Anda dapat menggunakan segmen tanggal inti dalam klausa WHERE untuk menentukan periode tanggal atau waktu.

Contoh kueri ini menentukan DURING LAST_30_DAYS untuk kolom segments.date dalam klausa WHERE:

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

Lihat Segmentasi > Segmen tanggal inti untuk mengetahui informasi terperinci tentang penggunaan segmen tanggal inti.

Pemfilteran yang dilarang

Pemfilteran tidak diizinkan:

  • Di kolom segmen yang tidak dipilih, kecuali untuk segmen tanggal inti.
  • Pada kolom jenis pesan apa pun, kecuali primitif (misalnya, Int64Value, StringValue, dll.).
  • Pada atribut kolom berulang dari jenis pesan apa pun, kecuali primitif (misalnya, Int64Value, StringValue, dll.).

Klausa ORDER BY

Klausa ORDER BY:

  • Merupakan klausa opsional dalam kueri.
  • Menentukan urutan hasil ditampilkan. Pengurutan mengikuti pola ini: FIELD_NAME ORDERING_OPTION (dipisahkan oleh spasi kosong).
  • Memungkinkan dua opsi: ASC (menaik) atau DESC (menurun). Defaultnya adalah menaik.

Contoh kueri ini mengurutkan kampanye menurut jumlah klik dalam urutan menurun (tertinggi ke terendah):

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

Beberapa pengurutan

Anda dapat menentukan beberapa kolom dalam klausa ORDER BY menggunakan daftar yang dipisahkan koma. Hasil akan diurutkan dalam urutan yang sama seperti yang Anda tentukan dalam kueri.

Kueri contoh ini memilih data grup iklan, dan mengurutkan hasil dalam urutan menaik menurut nama kampanye, kemudian dalam urutan menurun menurut jumlah tayangan, dan kemudian 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

Menggabungkan pengurutan dan batas

Anda dapat menggunakan klausa ORDER BY bersama klausa LIMIT untuk menyaring hasil.

Contoh kueri ini menampilkan lima kampanye dengan tayangan iklan tertinggi selama 30 hari terakhir:

SELECT
  campaign.id,
  campaign.name,
  metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
ORDER BY metrics.impressions DESC
LIMIT 5

Pemesanan terlarang

Pengurutan tidak diizinkan:

  • Menurut atribut resource yang tidak dipilih.
  • Berdasarkan metrik yang tidak dipilih.
  • Menurut segmen yang tidak dipilih.
  • Untuk jenis kolom berikut:
    • MESSAGE
    • Kolom berulang
    • Atribut kolom berulang.

Klausa LIMIT

Klausa LIMIT:

  • Merupakan klausa opsional dalam kueri.
  • Memungkinkan Anda membatasi jumlah hasil yang ditampilkan kueri.

Klausa ini berguna, misalnya, jika Anda hanya tertarik pada sampel atau ringkasan hasil.

Contoh kueri ini membatasi jumlah total hasil menjadi 50:

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

Klausa PARAMETERS

Klausa PARAMETERS memungkinkan Anda menentukan parameter meta untuk permintaan.

Sertakan draf

Parameter include_drafts mengontrol apakah entity draf disertakan dalam hasil. Defaultnya adalah false. Tetapkan ke true untuk menyertakan entity draf.

Contoh kueri ini menampilkan kampanye draf dan kampanye reguler:

SELECT campaign.name
FROM campaign
PARAMETERS include_drafts=true

Hapus resource_name yang batal dipilih

Parameter omit_unselected_resource_names memungkinkan Anda mengecualikan kolom resource_name dari semua resource yang tidak diminta secara eksplisit dalam klausa SELECT. Nilai default-nya adalah false. Jika Anda menetapkan parameter ini ke true, sebaiknya minta nama resource dari resource utama dan resource yang diatribusikan secara eksplisit dalam klausa SELECT.

Kueri contoh ini tidak menampilkan kolom campaign.resource_name atau customer.resource_name, karena tidak disertakan dalam klausa SELECT:

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

Contoh kueri ini menampilkan kolom campaign.resource_name, karena diminta secara eksplisit dalam klausa SELECT:

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

Mengubah mata uang yang digunakan dalam metrik

Parameter metrics_currency memungkinkan Anda menentukan mata uang yang akan digunakan saat menghitung metrik yang disertakan dalam klausa SELECT. Setelan defaultnya adalah menggunakan mata uang lokal untuk akun. Jika menetapkan parameter ini, Anda harus menggunakan kode mata uang 3 karakter ISO 4217. Misalnya: USD, EUR.

Contoh kueri ini menampilkan metrik cost_micros dalam mata uang lokal akun.

SELECT
  campaign.name,
  metrics.cost_micros
FROM campaign
WHERE segments.date >= "2018-08-15"
AND segments.date < "2018-08-16"

Contoh kueri ini menampilkan metrik cost_micros dalam peso Cile (CLP).

SELECT
  campaign.name,
  metrics.cost_micros
FROM campaign
WHERE segments.date >= "2018-08-15"
AND segments.date < "2018-08-16"
PARAMETERS metrics_currency = "CLP"

Pelajari lebih lanjut