Язык запросов Merchant Center

Merchant Center Query Language (MCQL) – это язык запросов, похожий на SQL. MCQL можно использовать с Merchant Reports API, чтобы получать данные об эффективности ваших товаров и рынка, на котором вы конкурируете.

Грамматика.

Ниже приведена грамматика 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] – диапазоны символов.
• | означает "или".

Важно! Оператор REGEXP_MATCH использует синтаксис RE2.

Регистр символов

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

Операторы	Учет регистра
= или !=	С учетом регистра
(NOT) IN	С учетом регистра
(НЕ) НРАВИТСЯ	С учетом регистра
CONTAINS (...)	С учетом регистра
REGEXP_MATCH	Оба (необязательно)

Важно! По умолчанию REGEXP_MATCH и NOT REGEXP_MATCH учитывают регистр, но вы можете добавить (?i), как описано в синтаксисе RE2, чтобы регистр не учитывался.

Пункты

Ниже перечислены пункты, которые можно запрашивать с помощью MCQL.

ВЫБРАТЬ

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

Важно! Предложение 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 является обязательным для всех запросов.

WHERE

Используйте условие WHERE, чтобы отфильтровать данные для запроса. Предложение WHERE обязательно для запросов эффективности. Вы можете фильтровать по всем полям segments и по дополнительным полям metrics, если вы укажете их в предложении SELECT.

Вот пример, в котором используется 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 (необязательно)

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

Укажите порядок сортировки с помощью field_name, а затем ASC или DESC. Сортировку можно выполнять только по полям, указанным в пункте SELECT запроса. Если вы не укажете значение ORDER BY, по умолчанию будет использоваться ASC.

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

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 позволяет указать собственный или относительный диапазон дат. Для всех запросов эффективности необходимо использовать условие WHERE, чтобы указать диапазон date.

Свой

Даты в формате 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

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