Struktur dan klausa kueri

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

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

Secara sederhana, untuk membuat kueri, Anda:

• Menentukan resource tempat mengambil data.
• Menambahkan kolom dan metrik untuk menentukan data yang ingin ditampilkan.
• Menambahkan segmen untuk mengelompokkan hasil.
• Menambahkan resource yang diatribusikan untuk menggabungkan data resource terkait secara implisit.
• Memfilter, mengurutkan, dan membatasi hasil.

Klausa SELECT

Klausa SELECT:

• Adalah klausa wajib dalam kueri.
• Menentukan kumpulan kolom yang akan diambil dalam permintaan.
• Menggunakan daftar kolom resource, kolom kustom, variabel Floodlight kustom, kolom segmen, dan metrik yang dipisahkan koma, serta 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 berbagai jenis kolom 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 wajib).

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

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 yang dilarang

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 bersama-sama. Beberapa resource hanya menyediakan subset 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:

• Adalah 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.

Catatan: Ada kolom pilihan Ya/Tidak di setiap halaman resource di bagian Referensi yang memfilter kolom resource, kolom segmen, dan kolom metrik yang tidak dapat digunakan saat resource ditentukan dalam klausa FROM.

Resource yang diatribusikan

Jika tersedia, resource yang diatribusikan akan digabungkan secara implisit 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

Catatan: Tidak semua resource memiliki resource yang diatribusikan. Bagian Referensi menyertakan detail resource yang diatribusikan yang tersedia dengan setiap resource.

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 meskipun tidak dipilih secara eksplisit dalam kueri:

SELECT ad_group.id
FROM ad_group

Kolom resource_name dari resource yang diatribusikan akan 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

Catatan: Jika resource dalam klausa FROM mencantumkan resource lain sebagai segment, memilih atribut resource tersebut akan bertindak sebagai segmen.

Klausa WHERE

Klausa WHERE:

• Adalah klausa opsional dalam kueri.

• Menentukan kondisi untuk memfilter dan menyegmentasikan 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 periode 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.

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 menurut 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

Catatan: Pemisah AND hanya dapat digunakan di antara kondisi operator (WHERE segments.device != "DESKTOP" AND segments.device != "MOBILE"), dan tidak dalam satu kondisi operator (WHERE segments.device != "DESKTOP" AND "MOBILE").

Lihat Segmentasi untuk mempelajari lebih lanjut cara menyegmentasikan laporan.

Kepekaan huruf besar/kecil

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

Tabel berikut menunjukkan kepekaan huruf besar/kecil default 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 kepekaan 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 tanggal atau periode 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 mendetail tentang penggunaan segmen tanggal inti.

Pemfilteran yang dilarang

Pemfilteran tidak diizinkan:

• Pada 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:

• Adalah klausa opsional dalam kueri.
• Menentukan urutan hasil ditampilkan. Pengurutan mengikuti pola ini: FIELD_NAME ORDERING_OPTION (dipisahkan oleh spasi kosong).
• Mengizinkan 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.

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

Menggabungkan pengurutan dan batas

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

Contoh kueri ini menampilkan lima kampanye dengan tayangan 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

Pengurutan yang dilarang

Pengurutan tidak diizinkan:

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

Klausa LIMIT

Klausa LIMIT:

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

Klausa ini berguna, misalnya, jika Anda hanya tertarik dengan 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.

Menyertakan draf

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

Contoh kueri ini menampilkan kampanye draf dan kampanye reguler:

SELECT campaign.name
FROM campaign
PARAMETERS include_drafts=true

Menghilangkan resource_name yang tidak dipilih

Parameter omit_unselected_resource_names memungkinkan Anda mengecualikan resource_name dari semua resource yang tidak diminta secara eksplisit dalam SELECT. Defaultnya 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.

Contoh kueri ini tidak menampilkan kolom campaign.resource_name maupun 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. Defaultnya adalah menggunakan mata uang akun yang ditentukan oleh customer_id. Jika Anda 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 akun yang ditentukan oleh customer_id.

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"

Mengaktifkan perluasan MCC

Parameter enable_mcc_expansion, jika ditetapkan ke benar (true), memungkinkan Anda menyertakan metrik, kolom, dan segmen dari semua akun yang berakar di customer_id, untuk resource dalam klausa FROM. Respons akan menggunakan mata uang customer_id, kecuali jika ditentukan secara eksplisit dalam parameter metrics_currency.

Catatan: Parameter enable_mcc_expansion hanya kompatibel dengan bidding_strategy. API akan menyertakan resource tambahan dari waktu ke waktu.

Contoh kueri ini menampilkan bidding_strategy.name, bidding_strategy.type, dan metrics.cost_micros dari semua akun dalam hierarki akun yang berakar di customer_id, karena parameter enable_mcc_expansion ditetapkan ke true.

SELECT
  bidding_strategy.name,
  bidding_strategy.type,
  metrics.cost_micros
FROM bidding_strategy
WHERE segments.date DURING LAST_14_DAYS
PARAMETERS enable_mcc_expansion = true

Pelajari lebih lanjut

• Tata bahasa kueri