Merchant Center Query Language

Язык запросов Merchant Center (MCQL) — это язык запросов, похожий на SQL. Вы можете использовать MCQL с API отчетов Merchant Reports для получения данных о производительности ваших товаров и рынке, на котором они конкурируют.

Грамматика

Вот справочник по грамматике MCQL (в формате регулярных выражений):

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

Вы можете использовать следующие символы:

• ? указывает на необязательный элемент.
• * означает ноль или более; + означает один или более.
• (xxxxxx) обозначает группировку.
• [a-z0-9] обозначает диапазоны символов.
• | означает «или».

Чувствительность к регистру

Большинство операторов MCQL чувствительны к регистру:

Пункты

Вот пункты, по которым можно выполнять запросы с помощью MCQL:

ВЫБИРАТЬ

В предложении SELECT принимается список полей, разделенных запятыми, для извлечения данных.

Вы можете выбрать любое поле в используемом представлении. Вот несколько примеров полей, которые вы можете выбрать:

• Метрики

  • impressions
  • clicks

• Сегменты

  • date
  • marketing_method

В одном запросе можно запрашивать данные из нескольких типов полей. Вот пример:

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

ОТ

В предложении FROM указывается таблица, из которой следует извлекать данные в запросе. В предложении FROM можно указать только одно поле. Предложение FROM обязательно для всех запросов.

ГДЕ

Use the WHERE clause to filter the data for your request. The WHERE clause is required for performance queries . You can filter by all segments fields, and by additional metrics fields if you specify them in the SELECT clause.

Вот пример, в котором используется WHERE для возврата показов только за указанный период времени (август):

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

В одном запросе можно фильтровать по нескольким условиям с помощью оператора AND . Используйте AND между полными условиями, например: WHERE marketing_method != "ADS" AND marketing_method != "ORGANIC" . Нельзя использовать AND между значениями в одном условии, например: WHERE marketing_method != "ADS" AND "ORGANIC" .

Вот пример, который возвращает количество кликов по каждому предложению, где количество кликов превышает 100, для метода маркетинга ADS в течение августа:

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'

В предложении WHERE оператор OR не поддерживается. Операторы чувствительны к регистру. Полный список операторов см. в разделе «Грамматика» .

Сортировать по (необязательно)

Предложение ORDER BY позволяет получать результаты в указанном порядке.

Specify the order by a field_name , then ASC or DESC . You can only order by fields specified in the SELECT clause of your query. ORDER BY defaults to ASC if you don't specify.

Следующий запрос упорядочивает возвращаемые строки по количеству кликов, от наибольшего к наименьшему:

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

В предложении ORDER BY можно указать несколько полей, используя список, разделенный запятыми.

Например, результаты следующего запроса сортируются в порядке возрастания по offer_id , затем в порядке убывания по количеству показов, а затем в порядке убывания по количеству кликов:

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 позволяет указать количество возвращаемых результатов.

Вот пример, который возвращает только 50 результатов, даже если доступно больше строк.

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

Для обработки длинных списков результатов используйте поле pageSize .

Диапазоны дат

MCQL позволяет указать пользовательский или относительный диапазон дат. Для указания диапазона date во всех запросах, определяющих производительность , необходимо использовать предложение WHERE .

Обычай

Даты в формате ISO 8601 (ГГГГ-ММ-ДД) можно указывать в следующих форматах:

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

Строковые значения даты можно задавать как в одинарных кавычках ( ' ), так и в двойных кавычках ( " ).

Родственник

Вы можете указать относительный диапазон дат, например, LAST_30_DAYS или THIS_MONTH , используя DURING вместо BETWEEN и AND :

WHERE date DURING LAST_30_DAYS

Полный список доступных относительных диапазонов дат см. в разделе «Грамматика» .