Merchant API phiên bản v1beta sẽ ngừng hoạt động và đóng cửa vào 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ề sản phẩm của bạn và thị trường mà sản phẩm đang cạnh tranh.

Ngữ pháp

Sau đây là thông tin tham khảo về ngữ pháp MCQL (ở dạng 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:

?cho biết một phần tử không bắt buộc.
* có nghĩa là không hoặc nhiều hơn; + có nghĩa là một hoặc nhiều hơn.
(xxxxxx) cho biết một nhóm.
[a-z0-9] biểu thị các dải ký tự.
| có nghĩa là "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
(KHÔNG) CÓ TRONG	Phân biệt chữ hoa chữ thường
(KHÔNG) THÍCH	Phân biệt chữ hoa chữ thường
CONTAINS (...)	Phân biệt chữ hoa chữ thường
REGEXP_MATCH	Không bắt buộc

Mệnh đề

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

SELECT

Mệnh đề SELECT lấy 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 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. Bạn bắt buộc phải có mệnh đề FROM cho tất cả các truy vấn.

Ở ĐÂU?

Sử dụng mệnh đề WHERE để lọc dữ liệu cho yêu cầu của bạn. Bạn phải dùng mệnh đề WHERE cho các truy vấn hiệu suất. Bạn có thể lọc theo tất cả các trường phân đoạn và theo các trường chỉ số bổ sung nếu 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ụ thể (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".

Sau đây là ví dụ trả về số lượt nhấp cho mỗi mặt hàng, trong đó có hơn 100 lượt nhấp, đối với phương thức 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ử có phân biệt chữ hoa chữ thường. Để xem danh sách đầy đủ các toán tử, hãy xem 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ụ thể.

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 đây 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ề.

Sau đâ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 một 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 một dải ô 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 theo tiêu chuẩn 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 một 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 ngữ pháp để biết danh sách đầy đủ các phạm vi ngày tương đối có sẵn.