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 Anda dan pasar tempat produk tersebut bersaing di.

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.
• | berarti "atau".

Kepekaan huruf besar/kecil

Sebagian besar operator MCQL peka huruf besar/kecil:

Klausa

Berikut klausa yang dapat Anda kueri dengan MCQL:

SELECT

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 tempat data akan diambil dalam permintaan. Anda hanya dapat menentukan satu kolom dalam klausa FROM. Klausa FROM diperlukan untuk semua kueri.

WHERE

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

Berikut contoh yang menggunakan WHERE untuk menampilkan tayangan hanya dari periode 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 jumlah klik lebih dari 100, 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 mengetahui daftar lengkap operator, lihat tata bahasa.

ORDER BY (opsional)

Klausa ORDER BY memungkinkan Anda mengambil hasil dalam urutan tertentu.

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

Kueri berikut mengurutkan baris yang ditampilkan berdasarkan jumlah klik, dari 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 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 tata bahasa untuk mengetahui daftar lengkap rentang tanggal relatif yang tersedia.