A linguagem de consulta do Merchant Center (MCQL, na sigla em inglês) é uma linguagem de consulta semelhante ao SQL. É possível usar o MCQL com a API Merchant Reports para recuperar dados de performance sobre seus produtos e o mercado em que estão concorrendo.
Gramática
Esta é a referência de gramática do MCQL (em notação de expressão regular):
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
Você pode usar os seguintes símbolos:
?indica um elemento opcional.*significa zero ou mais, e+significa um ou mais.(xxxxxx)indica um agrupamento.[a-z0-9]indica intervalos de caracteres.|significa "ou".
Diferenciação entre maiúsculas e minúsculas
A maioria dos operadores de MCQL diferencia maiúsculas de minúsculas:
| Operadores | Diferenciação entre maiúsculas e minúsculas |
|---|---|
| = ou != | Diferenciação entre maiúsculas e minúsculas |
| (NÃO) EM | Diferenciação entre maiúsculas e minúsculas |
| (NÃO) GOSTE | Diferenciação entre maiúsculas e minúsculas |
| CONTÉM (...) | Diferenciação entre maiúsculas e minúsculas |
| REGEXP_MATCH | Ambos opcionais |
Cláusulas
Aqui estão as cláusulas que você pode consultar com a MCQL:
SELECT
A cláusula SELECT usa uma lista separada por vírgulas de campos a serem recuperados.
É possível selecionar qualquer campo na visualização que estiver usando. Veja alguns exemplos de campos que você pode selecionar:
Você pode consultar vários tipos de campo em uma única solicitação. Veja um exemplo:
SELECT
date,
marketingMethod,
impressions,
clicks
FROM ProductPerformanceView
WHERE date BETWEEN '2020-08-01' AND '2020-08-31'
FROM
A cláusula FROM especifica a tabela em que os dados serão buscados na solicitação. Só é possível
especificar um campo na cláusula FROM. A cláusula FROM é obrigatória para todas as consultas.
WHERE
Use a cláusula WHERE para filtrar os dados da solicitação. A cláusula WHERE é obrigatória para consultas de desempenho.
É possível filtrar por todos os campos de segmentos e por outros campos de metrics, se você os especificar na cláusula SELECT.
Confira um exemplo que usa WHERE para retornar impressões somente de um período especificado (o mês de agosto):
SELECT offerId, impressions
FROM ProductPerformanceView
WHERE date BETWEEN '2020-08-01' AND '2020-08-31'
É possível filtrar por várias condições em uma única consulta com o operador AND.
Use AND entre as condições completas, por exemplo: WHERE marketingMethod !=
"ADS" AND marketingMethod != "ORGANIC". Não é possível usar AND entre valores em uma
única condição, por exemplo: WHERE marketingMethod != "ADS" AND "ORGANIC".
Confira um exemplo que retorna o número de cliques por oferta em que há mais de 100 cliques para o método de marketing ADS durante o mês de agosto:
SELECT offerId, clicks
FROM ProductPerformanceView
WHERE clicks > 100
AND marketingMethod = 'ADS'
AND date BETWEEN '2020-08-01' AND '2020-08-31'
A cláusula WHERE não é compatível com OR. Os operadores diferenciam maiúsculas de minúsculas. Para ver uma lista completa de operadores, consulte a gramática.
ORDER BY (opcional)
A cláusula ORDER BY permite recuperar resultados em uma ordem especificada.
Especifique a ordem com fieldName e, em seguida, ASC ou DESC. Só é possível ordenar por campos especificados na cláusula SELECT da sua consulta. O padrão de ORDER BY será
ASC se você não especificar.
A consulta a seguir ordena as linhas retornadas por número de cliques, do maior para o menor:
SELECT offerId, clicks
FROM ProductPerformanceView
WHERE date BETWEEN '2020-08-01' AND '2020-08-31'
ORDER BY clicks DESC
É possível especificar vários campos na cláusula ORDER BY usando uma lista separada por vírgulas.
Por exemplo, os resultados da consulta a seguir são classificados em ordem crescente por offerId, depois em ordem decrescente por número de impressões e, em seguida, em ordem decrescente por número de cliques:
SELECT offerId, impressions, clicks
FROM ProductPerformanceView
WHERE date BETWEEN '2020-08-01' AND '2020-08-31'
ORDER BY
offerId,
impressions DESC,
clicks DESC
LIMIT
A cláusula LIMIT permite especificar o número de resultados que serão retornados.
Veja um exemplo que retorna somente 50 resultados, mesmo que mais linhas estejam disponíveis.
SELECT offerId, impressions
FROM ProductPerformanceView
WHERE date BETWEEN '2020-08-01' AND '2020-08-31'
ORDER BY impressions DESC
LIMIT 50
Use o campo pageSize para processar listas longas de resultados.
Períodos
A MCQL permite especificar um período personalizado ou relativo. Use a cláusula WHERE para especificar um intervalo date para todas as consultas de desempenho.
Personalizado
Você pode especificar datas ISO 8601(AAAA-MM-DD) nos seguintes formatos:
date BETWEEN '2021-01-01' AND '2021-01-31'date >= '2021-01-01' AND date <= '2021-01-31'
Você pode definir strings de data com aspas simples (') ou aspas duplas
(").
Relativo
É possível especificar um período relativo, como LAST_30_DAYS ou THIS_MONTH,
usando DURING em vez de BETWEEN e AND:
WHERE date DURING LAST_30_DAYS
Consulte a gramática para ver a lista completa de períodos relativos disponíveis.