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 tentang produk Anda dan pasar pesaingnya.

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

Poin Penting: Operator REGEXP_MATCH menggunakan RE2 sintaksis.

Kepekaan huruf besar/kecil

Sebagian besar operator MCQL peka huruf besar/kecil:

Operator	Kepekaan Huruf Besar/Kecil
= atau !=	Peka huruf besar/kecil
(BUKAN) DI	Peka huruf besar/kecil
(BUKAN) SUKA	Peka huruf besar/kecil
BERISI (...)	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 dijelaskan dalam RE2 sintaksis untuk membuatnya tidak peka huruf besar/kecil.

Klausul

Berikut adalah klausul yang dapat Anda kueri dengan MCQL:

PILIH

Klausa SELECT menggunakan daftar kolom yang dipisahkan koma untuk diambil.

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

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

• Metrik

  • impressions
  • clicks

• Segmen

  • date
  • marketingMethod

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

SELECT
  date,
  marketingMethod,
  impressions,
  clicks
FROM ProductPerformanceView
WHERE date BETWEEN '2020-08-01' AND '2020-08-31'

FROM

Klausa FROM menentukan tabel tempat mengambil data dalam permintaan. Anda dapat hanya menentukan satu kolom dalam klausa FROM. Klausa FROM diperlukan untuk semua kueri.

WHERE

Gunakan klausa WHERE untuk memfilter data permintaan Anda. Klausul WHERE diperlukan untuk performa kueri. Anda dapat memfilter menurut semua segments, dan dengan tambahan kolom metrics jika Anda menentukannya dalam klausa SELECT.

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

SELECT offerId, impressions
FROM ProductPerformanceView
WHERE date BETWEEN '2020-08-01' AND '2020-08-31'

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

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

SELECT offerId, clicks
FROM ProductPerformanceView
WHERE clicks > 100
  AND marketingMethod = 'ADS'
  AND date BETWEEN '2020-08-01' AND '2020-08-31'

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

ORDER BY (opsional)

Dengan klausa ORDER BY, Anda dapat mengambil hasil dalam urutan tertentu.

Tentukan urutan menurut fieldName, lalu ASC atau DESC. Anda hanya dapat memesan paling kolom yang ditentukan dalam klausa SELECT kueri Anda. ORDER BY ditetapkan secara default ke ASC jika Anda tidak menentukan.

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

SELECT offerId, clicks
FROM ProductPerformanceView
WHERE date BETWEEN '2020-08-01' AND '2020-08-31'
ORDER BY clicks DESC

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

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

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

LIMIT

Klausa LIMIT memungkinkan Anda menentukan jumlah hasil yang akan ditampilkan.

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

SELECT offerId, impressions
FROM ProductPerformanceView
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 khusus atau relatif. Anda harus menggunakan Klausa WHERE guna menentukan rentang date untuk semua performa kueri.

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