Merchant Center Query Language

Merchant Center Query Language (MCQL) adalah bahasa kueri, mirip dengan SQL. Anda dapat menggunakan MCQL dengan Merchant Reports API untuk mengambil data performa produk dan pasar tempat produk tersebut bersaing.

Tata Bahasa

Berikut adalah referensi tata bahasa MCQL (dalam notasi ekspresi reguler):

Query            -> SelectClause FromClause? WhereClause? OrderByClause? LimitClause?
SelectClause     -> SELECT FieldName (, FieldName)*
FromClause       -> FROM TableName
WhereClause      -> WHERE Condition (AND Condition)*
OrderByClause    -> ORDER BY Ordering (, Ordering)*
LimitClause      -> LIMIT PositiveInteger

Condition        -> FieldName Operator Value | FieldName BETWEEN Value AND Value
Operator         -> = | != | > | >= | < | <= | <> | IN | NOT IN |
                    CONTAINS ANY | CONTAINS ALL | CONTAINS NONE | DURING |
                    LIKE | NOT LIKE | REGEXP_MATCH | NOT REGEXP_MATCH
Value            -> Number | NumberList | String | StringList | Function
Ordering         -> FieldName (ASC | DESC)?

FieldName        -> [a-z] ([a-zA-Z0-9._])*
TableName        -> [A-Z] ([a-zA-Z_])*

StringList       -> ( String (, String)* )
NumberList       -> ( Number (, Number)* )

PositiveInteger  -> [1-9] ([0-9])*
Number           -> -? [0-9]+ (. [0-9] [0-9]*)?
String           -> (' Char* ') | (" Char* ")
Function         -> LAST_14_DAYS | LAST_30_DAYS | LAST_7_DAYS |
                    LAST_BUSINESS_WEEK | LAST_MONTH | LAST_WEEK_MON_SUN |
                    LAST_WEEK_SUN_SAT | THIS_MONTH | THIS_WEEK_MON_TODAY |
                    THIS_WEEK_SUN_TODAY | TODAY | YESTERDAY

Anda dapat menggunakan simbol berikut:

• ?menunjukkan elemen opsional.
• * berarti nol atau lebih; + berarti satu atau lebih.
• (xxxxxx) menunjukkan pengelompokan.
• [a-z0-9] menunjukkan rentang karakter.
• | adalah singkatan dari "atau".

Poin Penting: Operator REGEXP_MATCH menggunakan sintaksis RE2.

Kepekaan huruf besar/kecil

Sebagian besar operator MCQL peka huruf besar/kecil:

Operator	Kepekaan Huruf Besar/Kecil
= atau !=	Peka huruf besar/kecil
(NOT) IN	Peka huruf besar/kecil
(BUKAN) SUKA	Peka huruf besar/kecil
CONTAINS (...)	Peka huruf besar/kecil
REGEXP_MATCH	Opsional Keduanya

Poin Penting: REGEXP_MATCH dan NOT REGEXP_MATCH peka huruf besar/kecil secara default, tetapi Anda dapat menyertakan (?i) seperti yang dijelaskan dalam sintaksis RE2 agar tidak peka huruf besar/kecil.

Klausul

Berikut adalah klausa yang dapat Anda buat kueri dengan MCQL:

PILIH

Klausa SELECT menggunakan daftar kolom yang dipisahkan koma untuk diambil.

Penting: Klausa SELECT diperlukan untuk semua kueri. Anda harus memilih setidaknya satu kolom metrik dalam kueri performa.

Anda dapat memilih kolom mana pun dari tampilan yang digunakan. Berikut adalah beberapa contoh kolom yang dapat Anda pilih:

• Metrik

  • impressions
  • clicks

• Segmen

  • date
  • marketing_method

Anda dapat membuat kueri beberapa jenis kolom dalam satu permintaan. Berikut contohnya:

SELECT
  date,
  marketing_method,
  impressions,
  clicks
FROM product_performance_view
WHERE date BETWEEN '2023-08-01' AND '2023-08-31'

FROM

Klausa FROM menentukan tabel tempat data diambil dalam permintaan. Anda hanya dapat menentukan satu kolom dalam klausa FROM. Klausa FROM wajib diisi untuk semua kueri.

WHERE

Gunakan klausa WHERE untuk memfilter data untuk permintaan Anda. Klausa WHERE diperlukan untuk kueri performa. Anda dapat memfilter menurut semua kolom segmen, dan menurut kolom metrik tambahan jika menentukan kolom tersebut dalam klausa SELECT.

Berikut adalah contoh yang menggunakan WHERE untuk menampilkan tayangan hanya dari jangka waktu tertentu (bulan Agustus):

SELECT offer_id, impressions
FROM product_performance_view
WHERE date BETWEEN '2023-08-01' AND '2023-08-31'

Anda dapat memfilter menurut beberapa kondisi dalam satu kueri dengan operator AND. Gunakan AND di antara kondisi lengkap, misalnya: WHERE marketing_method != "ADS" AND marketing_method != "ORGANIC". Anda tidak dapat menggunakan AND di antara nilai dalam satu kondisi, misalnya: WHERE marketing_method != "ADS" AND "ORGANIC".

Berikut adalah contoh yang menampilkan jumlah klik per penawaran, dengan lebih dari 100 klik, untuk metode pemasaran ADS, selama bulan Agustus:

SELECT offer_id, clicks
FROM product_performance_view
WHERE clicks > 100
  AND marketing_method = 'ADS'
  AND date BETWEEN '2023-08-01' AND '2023-08-31'

Klausa WHERE tidak mendukung OR. Operator peka huruf besar/kecil. Untuk daftar lengkap operator, lihat tata bahasa.

ORDER BY (opsional)

Klausa ORDER BY memungkinkan Anda mengambil hasil dalam urutan yang ditentukan.

Tentukan urutan menurut field_name, lalu ASC atau DESC. Anda hanya dapat mengurutkan berdasarkan kolom yang ditentukan dalam klausa SELECT kueri Anda. ORDER BY ditetapkan secara default ke ASC jika Anda tidak menentukannya.

Kueri berikut mengurutkan baris yang ditampilkan berdasarkan jumlah klik, dari tertinggi ke terendah:

SELECT offer_id, clicks
FROM product_performance_view
WHERE date BETWEEN '2023-08-01' AND '2023-08-31'
ORDER BY clicks DESC

Anda dapat menentukan beberapa kolom dalam klausa ORDER BY menggunakan daftar yang dipisahkan koma.

Misalnya, hasil kueri berikut diurutkan dalam urutan menaik berdasarkan offer_id, lalu dalam urutan menurun berdasarkan jumlah tayangan, lalu dalam urutan menurun berdasarkan jumlah klik:

SELECT offer_id, impressions, clicks
FROM product_performance_view
WHERE date BETWEEN '2020-08-01' AND '2020-08-31'
ORDER BY
  offer_id,
  impressions DESC,
  clicks DESC

LIMIT

Klausa LIMIT memungkinkan Anda menentukan jumlah hasil yang akan ditampilkan.

Berikut adalah contoh yang hanya menampilkan 50 hasil, meskipun ada lebih banyak baris.

SELECT offer_id, impressions
FROM product_performance_view
WHERE date BETWEEN '2020-08-01' AND '2020-08-31'
ORDER BY impressions DESC
LIMIT 50

Gunakan kolom pageSize untuk menangani daftar hasil yang panjang.

Rentang tanggal

MCQL memungkinkan Anda menentukan rentang tanggal kustom atau relatif. Anda harus menggunakan klausa WHERE untuk menentukan rentang date untuk semua kueri performa.

Kustom

Anda dapat menentukan tanggal ISO 8601(YYYY-MM-DD) dalam format berikut:

• date BETWEEN '2021-01-01' AND '2021-01-31'
• date >= '2021-01-01' AND date <= '2021-01-31'

Anda dapat menentukan string tanggal dengan tanda kutip tunggal (') atau tanda kutip ganda (").

Relatif

Anda dapat menentukan rentang tanggal relatif, seperti LAST_30_DAYS atau THIS_MONTH, dengan menggunakan DURING, bukan BETWEEN dan AND:

WHERE date DURING LAST_30_DAYS

Lihat tata bahasa untuk mengetahui daftar lengkap rentang tanggal relatif yang tersedia.