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.