A linguagem de consulta do Merchant Center (MCQL) é uma linguagem de consulta semelhante ao SQL. Você pode usar a MCQL com a API Merchant Reports para recuperar dados de performance dos seus produtos e do mercado em que eles estão competindo.
Gramática
Confira a referência da gramática 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;+significa um ou mais.(xxxxxx)indica um agrupamento.[a-z0-9]significa 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 != | Diferenciar maiúsculas de minúsculas |
| (NÃO) EM | Diferenciar maiúsculas de minúsculas |
| (NÃO) GOSTEI | Diferenciar maiúsculas de minúsculas |
| CONTAINS (...) | Diferenciar maiúsculas de minúsculas |
| REGEXP_MATCH | Opcional: ambos |
Cláusulas
Confira as cláusulas que podem ser consultadas com a MCQL:
SELECT
A cláusula SELECT usa uma lista separada por vírgulas de campos a serem recuperados.
Você pode selecionar qualquer campo da visualização que está usando. Confira alguns exemplos de campos que você pode selecionar:
É possível consultar vários tipos de campo em uma única solicitação. Veja um exemplo:
SELECT
date,
marketing_method,
impressions,
clicks
FROM product_performance_view
WHERE date BETWEEN '2023-08-01' AND '2023-08-31'
FROM
A cláusula FROM especifica a tabela de onde 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 sua solicitação. A cláusula WHERE é obrigatória para consultas de performance.
É possível filtrar por todos os campos de segmentos e por outros campos de métricas, se você os especificar na cláusula SELECT.
Confira um exemplo que usa WHERE para retornar impressões apenas de um período especificado (o mês de agosto):
SELECT offer_id, impressions
FROM product_performance_view
WHERE date BETWEEN '2023-08-01' AND '2023-08-31'
É possível filtrar por várias condições em uma única consulta com o operador AND.
Use AND entre condições completas, por exemplo: WHERE marketing_method !=
"ADS" AND marketing_method != "ORGANIC". Não é possível usar AND entre valores em uma única condição, por exemplo: WHERE marketing_method != "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 offer_id, clicks
FROM product_performance_view
WHERE clicks > 100
AND marketing_method = 'ADS'
AND date BETWEEN '2023-08-01' AND '2023-08-31'
A cláusula WHERE não é compatível com OR. Os operadores diferenciam maiúsculas de minúsculas. Para uma lista completa de operadores, consulte gramática.
ORDER BY (opcional)
A cláusula ORDER BY permite recuperar resultados em uma ordem especificada.
Especifique a ordem por um field_name, depois ASC ou DESC. Só é possível ordenar por campos especificados na cláusula SELECT da consulta. ORDER BY será definido como
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 offer_id, clicks
FROM product_performance_view
WHERE date BETWEEN '2023-08-01' AND '2023-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 offer_id, depois em ordem decrescente por número de impressões e, por fim, em ordem decrescente por número de cliques:
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
A cláusula LIMIT permite especificar o número de resultados a serem retornados.
Confira um exemplo que retorna apenas 50 resultados, mesmo que mais linhas estejam disponíveis.
SELECT offer_id, impressions
FROM product_performance_view
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
Com a MCQL, é possível especificar um período personalizado ou relativo. É necessário usar a cláusula
WHERE para especificar um intervalo date para todas as consultas de performance.
Personalizado
É possível 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'
É possível definir strings de data com aspas simples (') ou 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 gramática para ver a lista completa de períodos relativos disponíveis.