A linguagem de consulta do Merchant Center (MCQL) é semelhante ao SQL. Você pode usar o MCQL com a API Merchant Reports para extrair dados de performance dos seus produtos e do mercado em que eles competem.
Gramática
Confira a referência da 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;+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 do 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
Estas são as cláusulas que podem ser consultadas com a MCQL:
SELECT
A cláusula SELECT usa uma lista de campos separados por vírgulas para extrair.
Você pode selecionar qualquer campo da visualização que estiver usando. Confira alguns exemplos de campos que podem ser selecionados:
É 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 é necessária para consultas de performance.
É possível filtrar por todos os campos de segmentos e por outros campos de métricas, se especificados na cláusula SELECT.
Confira um exemplo que usa WHERE para retornar impressões de apenas 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 com um field_name, depois ASC ou DESC. Só é possível ordenar por campos especificados na cláusula SELECT da consulta. ORDER BY vai ser o padrão para
ASC 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
Com o MCQL, você pode especificar um período relativo ou personalizado. É 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 a gramática para conferir a lista completa de períodos relativos disponíveis.