Merchant API phiên bản v1beta đã ngừng hoạt động và ngừng cung cấp từ ngày 28 tháng 2 năm 2026. Để biết các bước chuyển đổi sang phiên bản ổn định mới nhất, hãy xem phần Di chuyển từ v1beta sang v1.

Merchant Center Query Language

Ngôn ngữ truy vấn Merchant Center (MCQL) là một ngôn ngữ truy vấn, tương tự như SQL. Bạn có thể sử dụng MCQL với Merchant Reports API để truy xuất dữ liệu hiệu suất về các sản phẩm và thị trường mà sản phẩm đang cạnh tranh.

Ngữ pháp

Dưới đây là tài liệu tham khảo về ngữ pháp MCQL (theo ký hiệu biểu thức chính quy):

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

Bạn có thể sử dụng các ký hiệu sau:

?biểu thị một phần tử không bắt buộc.
* có nghĩa là 0 hoặc nhiều; + có nghĩa là 1 hoặc nhiều.
(xxxxxx) biểu thị một nhóm.
[a-z0-9] biểu thị phạm vi ký tự.
| biểu thị "hoặc".

Phân biệt chữ hoa chữ thường

Hầu hết các toán tử MCQL đều phân biệt chữ hoa chữ thường:

Toán tử	Phân biệt chữ hoa chữ thường
= hoặc !=	Phân biệt chữ hoa chữ thường
(NOT) IN	Phân biệt chữ hoa chữ thường
(NOT) LIKE	Phân biệt chữ hoa chữ thường
CONTAINS (...)	Phân biệt chữ hoa chữ thường
REGEXP_MATCH	Tuỳ chọn cả hai

Mệnh đề

Dưới đây là các mệnh đề mà bạn có thể truy vấn bằng MCQL:

SELECT

Mệnh đề SELECT lấy một danh sách các trường được phân tách bằng dấu phẩy để truy xuất.

Bạn có thể chọn bất kỳ trường nào trong chế độ xem mà bạn đang sử dụng. Dưới đây là một số ví dụ về các trường mà bạn có thể chọn:

Chỉ số
- impressions
- clicks
Phân khúc
- date
- marketing_method

Bạn có thể truy vấn nhiều loại trường trong một yêu cầu. Ví dụ:

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

FROM

Mệnh đề FROM chỉ định bảng để tìm nạp dữ liệu trong yêu cầu. Bạn chỉ có thể chỉ định một trường trong mệnh đề FROM. Mệnh đề FROM là bắt buộc đối với tất cả các truy vấn.

WHERE

Sử dụng mệnh đề WHERE để lọc dữ liệu cho yêu cầu của bạn. Mệnh đề WHERE là bắt buộc đối với hiệu suất truy vấn. Bạn có thể lọc theo tất cả các trường phân khúc, và theo các trường chỉ số bổ sung nếu bạn chỉ định các trường đó trong mệnh đề SELECT.

Dưới đây là ví dụ sử dụng WHERE để chỉ trả về số lượt hiển thị trong một khoảng thời gian được chỉ định (tháng 8):

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

Bạn có thể lọc theo nhiều điều kiện trong một truy vấn bằng toán tử AND. Sử dụng AND giữa các điều kiện hoàn chỉnh, ví dụ: WHERE marketing_method != "ADS" AND marketing_method != "ORGANIC". Bạn không thể sử dụng AND giữa các giá trị trong một điều kiện, ví dụ: WHERE marketing_method != "ADS" AND "ORGANIC".

Dưới đây là ví dụ trả về số lượt nhấp cho mỗi ưu đãi, trong đó có hơn 100 lượt nhấp, cho phương pháp tiếp thị ADS, trong tháng 8:

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'

Mệnh đề WHERE không hỗ trợ OR. Các toán tử phân biệt chữ hoa chữ thường. Để xem danh sách đầy đủ các toán tử, hãy xem phần ngữ pháp.

ORDER BY (không bắt buộc)

Mệnh đề ORDER BY cho phép bạn truy xuất kết quả theo một thứ tự được chỉ định.

Chỉ định thứ tự theo field_name, sau đó là ASC hoặc DESC. Bạn chỉ có thể sắp xếp theo các trường được chỉ định trong mệnh đề SELECT của truy vấn. ORDER BY mặc định là ASC nếu bạn không chỉ định.

Truy vấn sau sắp xếp các hàng được trả về theo số lượt nhấp, từ cao nhất đến thấp nhất:

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

Bạn có thể chỉ định nhiều trường trong mệnh đề ORDER BY bằng cách sử dụng danh sách được phân tách bằng dấu phẩy.

Ví dụ: kết quả của truy vấn sau được sắp xếp theo thứ tự tăng dần theo offer_id, sau đó theo thứ tự giảm dần theo số lượt hiển thị, sau đó theo thứ tự giảm dần theo số lượt nhấp:

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

Mệnh đề LIMIT cho phép bạn chỉ định số lượng kết quả cần trả về.

Dưới đây là ví dụ chỉ trả về 50 kết quả, ngay cả khi có nhiều hàng hơn.

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

Sử dụng trường pageSize để xử lý danh sách kết quả dài.

Phạm vi ngày

MCQL cho phép bạn chỉ định phạm vi ngày tuỳ chỉnh hoặc tương đối. Bạn phải sử dụng mệnh đề WHERE để chỉ định phạm vi date cho tất cả các truy vấn hiệu suất.

Tuỳ chỉnh

Bạn có thể chỉ định ngày ISO 8601(YYYY-MM-DD) ở các định dạng sau:

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

Bạn có thể xác định chuỗi ngày bằng dấu nháy đơn (') hoặc dấu nháy kép (").

Họ hàng

Bạn có thể chỉ định phạm vi ngày tương đối, chẳng hạn như LAST_30_DAYS hoặc THIS_MONTH, bằng cách sử dụng DURING thay vì BETWEEN và AND:

WHERE date DURING LAST_30_DAYS

Xem phần ngữ pháp để biết danh sách đầy đủ các phạm vi ngày tương đối có sẵn.