Merchant Center Query Language

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

Tata Bahasa

Berikut 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] menandakan rentang karakter.
• | adalah singkatan dari "atau".

Kepekaan huruf besar/kecil

Sebagian besar operator MCQL peka huruf besar/kecil:

Klausul

Berikut adalah klausa yang dapat Anda kueri dengan MCQL:

PILIH

Klausa SELECT mengambil daftar kolom yang dipisahkan koma untuk diambil.

Anda dapat memilih kolom apa pun dari tampilan yang Anda gunakan. Berikut 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 yang akan diambil datanya 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. Klausul WHERE diperlukan untuk kueri performa. Anda dapat memfilter menurut semua kolom segmen, dan menurut kolom metrik tambahan jika Anda menentukannya dalam klausa SELECT.

Berikut adalah contoh yang menggunakan WHERE untuk menampilkan tayangan iklan 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 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'

Klausul WHERE tidak mendukung OR. Operator peka huruf besar/kecil. Untuk mengetahui daftar lengkap operator, lihat grammar.

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 yang tertinggi hingga 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 yang tersedia.

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 sintaksis untuk mengetahui daftar lengkap rentang tanggal relatif yang tersedia.