A linguagem de consulta do Merchant Center (MCQL, na sigla em inglês) é semelhante à 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 em.
Gramática
Confira a referência da gramática da 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 da MCQL diferencia maiúsculas de minúsculas:
| Operadores | Diferenciação entre maiúsculas e minúsculas |
|---|---|
| = ou != | Diferenciar maiúsculas de minúsculas |
| (NOT) IN | Diferenciar maiúsculas de minúsculas |
| (NOT) LIKE | Diferenciar maiúsculas de minúsculas |
| CONTAINS (...) | Diferenciar maiúsculas de minúsculas |
| REGEXP_MATCH | Opcionalmente, 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.
É possível selecionar qualquer campo da visualização que você está usando. Confira alguns exemplos de campos que podem ser selecionados:
É possível consultar vários tipos de campo em uma única solicitação. Confira 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 extraídos 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 performance
consultas.
É 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 oferece suporte a 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 e, em seguida, ASC ou DESC. Só é possível ordenar por campos especificados na cláusula SELECT da consulta. ORDER BY usa ASC como padrão se você não especificar.
A consulta a seguir ordena as linhas retornadas pelo 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 pelo número de impressões e, em seguida, em ordem decrescente pelo 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
A MCQL permite especificar um período personalizado ou relativo. É necessário usar a
WHERE cláusula para especificar um date período 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 conferir a lista completa de períodos relativos disponíveis.