Descripción general de la sintaxis de ShopifyQL
Puedes usar la sintaxis de consultas de ShopifyQL para recuperar y dar forma a los datos en los informes de tu tienda. Una consulta es una pregunta que haces a tus datos. FROM selecciona el conjunto de datos, SHOW selecciona los datos a devolver y las otras palabras clave agregan filtros, agrupaciones, rangos de fechas, comparaciones y visualizaciones.
Puedes usar la sintaxis de ShopifyQL para cualquiera de estos fines:
- Crear o modificar informes con el editor de consultas.
- Crear o modificar segmentos de clientes con el editor de segmentos.
- Desarrollar apps con ShopifyQL mediante GraphQL Admin API.
En esta página
Glosario de términos
| Término | Definición |
|---|---|
| Dimensión | Un atributo que segmenta los datos para ordenarlos y presentarlos con mayor claridad. Algunos ejemplos habituales de dimensiones son el tiempo, los productos y los lugares. Las dimensiones se usan como parámetros en ShopifyQL. |
| Palabra clave | Sintaxis de ShopifyQL que actúa como un comando para dirigir la consulta. |
| Métrica | Una medición cuantitativa de los datos. Ejemplos comunes de métricas incluyen ventas totales, número de pedidos y beneficio bruto. |
| Parámetro | Sintaxis de ShopifyQL que identifica los elementos o la información de la base de datos que se incluirán en tu consulta. |
| Operador | Una palabra o carácter reservado que se usa como parte de una consulta. Por ejemplo: STARTS WITH, >= o last_week. |
Reglas de sintaxis de ShopifyQL
Debes cumplir los siguientes requisitos al redactar una consulta de informe válida con ShopifyQL:
- Puedes escribir una consulta completa en una sola línea o en varias líneas.
- Debes incluir como mínimo el
FROMySHOWpalabras clave con sus parámetros correspondientes. Todas las demás palabras clave y parámetros son opcionales. - Todas las palabras clave de una consulta deben aparecer en el siguiente orden:
FROMSHOWWHEREGROUP BYTIMESERIESWITHTOTALS,GROUP_TOTALS,PERCENT_CHANGE,CUMULATIVE_VALUES,CURRENCY,TIMEZONEHAVINGSINCEyUNTIL, oDURINGCOMPARE TOy opcionalmenteUNTILORDER BYLIMITVISUALIZEyTYPE,MAX,ANNOTATE
Este es un ejemplo de ShopifyQL escrito como una consulta con la sintaxis correcta. Los parámetros se incluyen mediante marcadores de posición genéricos, y los parámetros opcionales están entre corchetes:
FROM table_name1, table_name2, ...
SHOW column1 { AS alias }, column2 { AS alias }, ...
WHERE condition
GROUP BY dimension
TIMESERIES time_dimension WITH TOTALS, GROUP_TOTALS, PERCENT_CHANGE, CUMULATIVE_VALUES, CURRENCY 'currency_code', TIMEZONE 'iana_timezone'
HAVING condition
SINCE date_offset
UNTIL date_offset
DURING named_date_range
COMPARE TO [ date_offset { UNTIL date_offset }, ... | TARGETS ]
ORDER BY column { ASC | DESC }
LIMIT number { OFFSET number }
VISUALIZE [ alias1, alias2, ... ]
TYPE { visualization_type }
MAX number
ANNOTATE annotation_category { FILTER annotation_filter }La WITH modifica la palabra clave a la que sigue, por lo que se escribe al final de la GROUP BY o TIMESERIES declaración a la que se aplica, como TIMESERIES day WITH TOTALS.
Palabras clave de ShopifyQL
Las consultas de ShopifyQL pueden ir desde básicas, para obtener información útil de alto nivel, hasta completas, para obtener información detallada. Cada palabra clave tiene una función específica que estructura la consulta.
FROM y SHOW
Crear la consulta de ShopifyQL más sencilla solo requiere 2 palabras clave: FROM y SHOW, en ese orden. FROM, seguido de uno o más parámetros de nombre de tabla, indica qué tablas quieres consultar. SHOW, seguida de cualquier cantidad de parámetros de nombre de columna, especifica las columnas que quieres seleccionar.
SHOW se puede usar para especificar el orden en que se devuelven las métricas y dimensiones en el informe.
Por ejemplo, puedes devolver la suma de los ingresos totales escribiendo esta consulta:
FROM sales
SHOW total_salesConsulta la documentación para desarrolladores de Shopify para ver una lista de los conjuntos de datos disponibles.
WHERE
La WHERE permite aplicar un filtro dimensional a toda la consulta de ShopifyQL. El filtro se puede modificar tanto con operadores de comparación (como mayor que >) como con operadores lógicos (como AND o NOT), y con coincidencias parciales de cadenas y listas (como STARTS WITH y CONTAINS).
Usa WHERE cuando quieras centrarte en un segmento específico, como pedidos de un solo país, ventas de un producto en particular o transacciones por encima de un valor determinado.
WHERE las condiciones deben cumplir los siguientes requisitos:
- Los valores deben ir entre comillas simples ('), no comillas dobles (").
- Las condiciones no pueden contener operaciones aritméticas.
- Las condiciones solo pueden hacer referencia a una dimensión, no a una métrica.
Por ejemplo, para devolver las ventas totales filtradas según el país de facturación, la consulta es la siguiente:
FROM sales
SHOW total_sales, product_title, product_type, product_vendor
WHERE billing_country='Canada'
GROUP BY product_title, product_type, product_vendorComo en el ejemplo anterior, puedes filtrar el conjunto de resultados con WHERE parámetro incluso cuando ese parámetro no está incluido en el SHOW palabra clave. En este caso, las ventas totales se filtran para pedidos de Canadá únicamente, aunque billing_country no se incluye en el conjunto de resultados.
Operadores de comparación
La WHERE es la palabra clave que utiliza operadores de comparación para filtrar datos. En el ejemplo anterior, se usó = para especificar que la consulta se filtra según un valor específico. Sin embargo, existen otros operadores a tu disposición:
| Operador de comparación | Descripción |
|---|---|
| = | igual a |
| != | distinto de |
| < | menor que |
| > | mayor que |
| <= | menor o igual que |
| >= | mayor o igual que |
Operadores lógicos
Para filtrar aún más los datos, puedes agregar operadores lógicos a tu consulta. Los operadores lógicos de ShopifyQL son:
| Operador lógico | Descripción |
|---|---|
AND | Filtra para incluir todas las filas donde las condiciones separadas por AND se cumplen. |
OR | Filtra para incluir todas las filas en las que se cumpla cualquiera de las condiciones separadas por OR se cumplen. |
NOT | Filtra para incluir solo las filas donde no se cumplen las condiciones, por ejemplo, filas que no contienen el valor especificado. |
Puedes usar varios filtros con WHERE palabra clave agregando operadores lógicos.
A partir del ejemplo de consulta del conjunto de datos, para obtener una agrupación mensual de las ventas netas de todos los pedidos con melocotones secos en los que la dirección de facturación estaba en Canadá y se aplicó un descuento, la consulta es:
FROM sales
SHOW total_sales, product_title, product_type, product_vendor
WHERE billing_country = 'Canada' AND product_title = 'Dried Peaches' AND is_discounted_sale = true
GROUP BY product_title, product_type, product_vendorAND se evalúa antes de OR. Para controlar el orden de la evaluación, agrupa las condiciones con paréntesis, como en WHERE billing_country = 'Canada' AND (product_type = 'Fruit' OR product_type = 'Nuts').
Operadores de rango y pertenencia
Puedes relacionar una dimensión con una lista de valores, o comprobar si un valor cae dentro de un rango:
| Operador | Descripción |
|---|---|
IN | Encuentra cualquier valor de una lista, como WHERE billing_country IN ('Canada', 'United States'). |
NOT IN | Excluye todos los valores de una lista. |
BETWEEN | Coincide con los valores dentro de un rango, como WHERE number_of_products_bought_together BETWEEN 2 AND 4. Se incluyen tanto el valor bajo como el alto. |
NOT BETWEEN | Excluye los valores dentro de un rango. Se excluyen tanto el valor bajo como el alto. |
Comprobaciones nulas y booleanas
Puedes filtrar por valores faltantes o por estados booleanos sin tener que comparar una dimensión con un valor. Agrega NOT después de IS para invertir cualquiera de estas comprobaciones:
| Operador | Descripción |
|---|---|
IS NULL | Falta el valor. Funciona con cualquier dimensión que acepte valores faltantes. |
IS TRUE | El valor es verdadero. Funciona con dimensiones booleanas. |
IS FALSE | El valor es falso. Funciona con dimensiones booleanas. |
Una comprobación booleana invertida también coincide con las filas en las que falta el valor. Por ejemplo, una comprobación verdadera invertida coincide tanto con las filas donde el valor es falso como con aquellas donde el valor falta. La excepción es la comprobación nula invertida, ya que solo selecciona las filas en las que existe un valor:
FROM sales
SHOW total_sales
WHERE product_type IS NOT NULL AND is_discounted_sale IS NOT TRUE
GROUP BY product_typeExcluir valores con !=, NOT IN, o NOT CONTAINS no elimina las filas donde falta la dimensión. Para omitir esas filas también, agrega una comprobación no nula para la misma dimensión:
FROM sales
SHOW total_sales
WHERE product_type != 'Fruit' AND product_type IS NOT NULL
GROUP BY product_typeFunciones de eventos de cliente
Para filtrar los datos en mayor detalle, puedes agregar funciones condicionales de eventos de cliente a la consulta. Los nombres de las funciones van seguidos de MATCHES o NOT MATCHES y paréntesis que contienen la lista de parámetros opcionales.
Puedes agregar las siguientes funciones de eventos de cliente de ShopifyQL a las consultas:
| Operador de eventos de cliente | Descripción |
|---|---|
{customer_event} MATCHES ({condition1}, {condition2}, ...) | Filtro para incluir todas las filas donde se cumplen las condiciones de eventos de cliente definidas entre paréntesis. |
{customer_event} NOT MATCHES ({condition1}, {condition2}, ...) | Filtro para incluir solo las filas donde no se cumplen las condiciones de eventos de cliente. |
Por ejemplo, la siguiente consulta muestra solo a los clientes que han hecho 5 o más pedidos:
FROM customers
SHOW customer_name, total_number_of_orders
WHERE orders_placed MATCHES (count >= 5)
GROUP BY customer_nameLas condiciones dentro de los paréntesis deben reflejar los parámetros disponibles que pertenecen al evento de cliente asociado. Puedes usar los siguientes campos predeterminados de eventos de cliente y los parámetros asociados en una WHERE instrucción:
| Eventos | Parámetros |
|---|---|
products_purchased |
|
orders_placed |
|
shopify_email.opened |
|
shopify_email.clicked |
|
shopify_email.bounced |
|
shopify_email.marked_as_spam |
|
shopify_email.unsubscribed |
|
storefront_event.product_viewed |
|
storefront_event.collection_viewed |
|
store_credit_accounts |
|
within_distance |
|
Para los parámetros date en las funciones de eventos de cliente, puedes usar fechas relativas, como date = today, date = -30d y date = -6m.
Cuando el FROM conjunto de datos sea distinto a customers, debes anteponer customer. al campo que se puede relacionar para acceder al conjunto de datos del cliente en tu consulta. Por ejemplo, customer.products_purchased.
Por ejemplo, esta consulta muestra las ventas totales solo de los clientes que compraron 3 o más productos de cuidado de la piel en un solo pedido en los últimos 30 días:
FROM sales
SHOW total_sales
WHERE customer.products_purchased MATCHES (tag CONTAINS 'skincare', quantity >= 3)
GROUP BY month
SINCE -30dHay una función adicional de eventos de cliente anniversary disponible que no requiere el operador MATCHES . La función anniversary está disponible para las dimensiones del cliente que tienen resultados de fecha u hora, como customer_added_date o first_order_date, y para los metacampos relacionados con la hora o la fecha, como metafields.facts.birth_date o metafields.custom.preferred_delivery_date.
Por ejemplo, esta instrucción muestra solo los resultados en los que la fecha en que se agregó al cliente tiene como aniversario el día de hoy: WHERE anniversary(customer_added_date) = today. Otro ejemplo: esta instrucción muestra solo los resultados en los que el cumpleaños del cliente (guardado como metacampo) ocurre en algún momento de esta semana: WHERE anniversary(metafields.facts.birth_date) BETWEEN today AND +7d.
GROUP BY
Para segmentar una métrica por una dimensión, como agrupar ventas por región, usa GROUP BY palabra clave. La GROUP BY se puede combinar con cualquier parámetro de dimensión.
GROUP BY es lo que transforma un total único en un desglose. Sin esto, SHOW total_sales devuelve un número. Con GROUP BY product_title, esa misma métrica se desglosa por cada producto, para que puedas identificar qué impulsa realmente el rendimiento.
Por ejemplo, una consulta que agrupa los ingresos totales por país de facturación y región se escribe así:
FROM sales
SHOW total_sales
GROUP BY billing_country, billing_regionEste es otro ejemplo de consulta que usa la time dimension para mostrar las ventas totales por mes:
FROM sales
SHOW total_sales
GROUP BY monthEsta consulta no devuelve ningún mes en el que no tengas ventas. Si deseas una consulta que devuelva un período completo e ininterrumpido, usa TIMESERIES como palabra clave.
FROM sales
SHOW total_sales
TIMESERIES month
SINCE last_year UNTIL todayDimensiones de tiempo
Estas son las dimensiones de tiempo que puedes usar para agrupar los datos:
| Operador | Descripción |
|---|---|
second | Agrupar por segundo de la hora. |
minute | Agrupación por minuto de la hora. |
hour | Agrupación por hora del día calendario. |
day | Agrupación por día calendario. |
week | Agrupación por semana del calendario. |
month | Agrupación por mes calendario. |
quarter | Agrupar por trimestre del calendario. |
year | Agrupación por año calendario. |
hour_of_day | Agrupación por 24 horas basada en cero (0, 1, ..., 23). |
day_of_week | Agrupación de base cero por día de la semana, del 0 para el lunes al 6 para el domingo. |
week_of_year | Agrupación por semana del año, del 1 a la 52, o del 1 a la 53 en los años que tienen una 53.ª semana. |
month_of_year | Agrupación por mes del año (1, 2, ..., 12). |
TOP N
Puedes mostrar un número personalizado de elementos en la visualización del informe con TOP N parámetro, donde N es la cantidad de artículos que se muestran. N debe ser un número entero positivo.
Como parte de la consulta, puedes incluir TOP y, a continuación, la cantidad de artículos junto con una dimensión categórica. Si hay múltiples dimensiones, se separan por comas. Las dimensiones categóricas son aquellas que no están asociadas al tiempo, como los productos, los canales o las regiones. Los artículos que no se incluyen en N se agrupan como "Otros" en la visualización y en la tabla de datos. Ciertos tipos de visualización, como histogram o list, no admiten la agrupación por TOP N parámetros.
En este ejemplo, muestras los 5 productos principales de cada día de los últimos 30 días, y los demás artículos se agrupan como "Otros":
FROM sales
SHOW gross_sales
GROUP BY day, TOP 5 product_title WITH GROUP_TOTALS, TOTALS, CURRENCY 'USD'
TIMESERIES day
SINCE startOfDay(-30d) UNTIL today
ORDER BY day ASC, gross_sales DESC, product_title ASC
VISUALIZE gross_salesPuedes incluir más de un parámetro TOP N en una sola GROUP BY declaración.
Se pueden agregar palabras clave adicionales a la TOP N parámetro para personalizar cómo se muestran los artículos restantes, así como el sistema de clasificación usado:
ONLY TOP N: muestra solo N elementos y oculta los restantes del conjunto de datos en la visualización y en la tabla de datos, en lugar de agruparlos como "Otros".TOP N {dimension} OVERALL: Muestra la cantidad de N artículos principales dentro del rango de fechas especificado (la clasificación general), agrupados por la dimensión especificada.OVERALLno tiene efecto en la primera dimensión de unaGROUP BYdeclaración. También puedes incluir elONLYpalabra clave para ocultar los elementos restantes. El orden de clasificación del conjunto de datos sigue estando determinado por laORDER BYpalabra clave.
En este ejemplo, muestras solo los 5 productos principales de cada uno de los últimos 30 días, y los demás elementos se ocultan por completo en la visualización y en la tabla de datos:
FROM sales
SHOW gross_sales
GROUP BY day, ONLY TOP 5 product_title WITH GROUP_TOTALS, TOTALS, CURRENCY 'USD'
TIMESERIES day
SINCE startOfDay(-30d) UNTIL today
ORDER BY day ASC, gross_sales DESC, product_title ASC
VISUALIZE gross_salesEn este ejemplo, muestras los 5 productos principales de los últimos 30 días en general, agrupados por día, y ocultas los demás elementos:
FROM sales
SHOW gross_sales
GROUP BY day, ONLY TOP 5 product_title OVERALL WITH GROUP_TOTALS, TOTALS, CURRENCY 'USD'
TIMESERIES day
SINCE startOfDay(-30d) UNTIL today
ORDER BY day ASC, gross_sales DESC, product_title ASC
VISUALIZE gross_salesSimilar a LIMIT, la TOP N actualiza la cantidad de artículos incluidos en la tabla de datos y en la visualización. Para personalizar la cantidad de artículos en la visualización del informe sin afectar la tabla de datos, usa el VISUALIZE {metric} MAX N parámetro.
En este ejemplo, muestras los 5 productos principales de cada día de los últimos 30 días, y el resto de artículos siguen apareciendo en la tabla:
FROM sales
SHOW gross_sales
GROUP BY day, product_title WITH GROUP_TOTALS, TOTALS, CURRENCY 'USD'
TIMESERIES day
SINCE startOfDay(-30d) UNTIL today
ORDER BY day ASC, gross_sales DESC, product_title ASC
VISUALIZE gross_sales MAX 5CLUSTER
Puedes usar CLUSTER es un modificador de la declaración GROUP BY que sirve para agrupar las direcciones cercanas en clústeres geográficos. Los resultados agrupados se pueden mostrar en una visualización de mapa de burbujas, en la que cada clúster se dibuja como una burbuja cuyo tamaño se define según la métrica.
CLUSTER funciona con las dimensiones shipping_address y billing_address, que están disponibles en conjuntos de datos como sales y payments. Estas dimensiones de dirección solo se pueden agrupar con CLUSTER. Si agrupas por shipping_address sin este modificador, la consulta devuelve el error 'shipping_address' can only be grouped with CLUSTER.
Las dimensiones de dirección no están disponibles en el panel de filtros. Para filtrar por ubicación en una consulta, usa los campos de coordenadas de una dirección en WHERE, como shipping_address.latitude y shipping_address.longitude. Un mapa de burbujas usa estos campos para agregar el área de mapa visible a la consulta.
En este ejemplo, muestras las ventas totales de los últimos 30 días, agrupadas en clústeres de direcciones de envío cercanas, y mostradas en un mapa de burbujas:
FROM sales
SHOW total_sales
GROUP BY CLUSTER shipping_address WITH TOTALS
SINCE -30d UNTIL today
VISUALIZE total_sales TYPE bubble_mapCada clúster incluye un campo de recuento de direcciones generado, como shipping_address__cluster.size, que aparece en la tabla de datos como Recuento de direcciones de envío. El recuento es el número de ubicaciones de mapa distintas en el clúster, por lo que varias direcciones en la misma ubicación se cuentan como 1 dirección. Puedes hacer referencia al campo de recuento de direcciones en ORDER BY y HAVING. Por ejemplo, para incluir primero en la lista los clústeres con más ubicaciones, agrega ORDER BY shipping_address__cluster.size DESC a la consulta.
Puedes combinar CLUSTER con TOP N para devolver solo los clústeres más grandes, como GROUP BY ONLY TOP 10 CLUSTER shipping_address. Si usas TOP N sin ONLY, los clústeres restantes se combinan en una fila Otros. La fila Otros aparece solo en la tabla de datos, porque los clústeres que combina pueden estar en diferentes áreas del mapa.
Un mapa de burbujas también puede mostrar otras dimensiones junto con la dirección agrupada. Una dimensión que va antes de CLUSTER en la declaración GROUP BY dibuja cada valor con su propio color, por ejemplo, GROUP BY product_title, CLUSTER shipping_address. Una dimensión que va después devuelve una fila para cada valor en cada clúster, por ejemplo, GROUP BY CLUSTER shipping_address, day. Cuando un mapa de burbujas se agrupa por otra dimensión, una burbuja cuyo centro se dibuja dentro de una burbuja más grande en el nivel de zoom actual se fusiona con esta. La burbuja más grande conserva su propio valor en lugar de un total y, en la información sobre herramientas, aparecen las filas que incluye. Para dibujar en su lugar 1 burbuja para el total de cada clúster, agrega WITH GROUP_TOTALS, por ejemplo, GROUP BY CLUSTER shipping_address, product_title WITH GROUP_TOTALS.
TIMESERIES
Puedes usar TIMESERIES palabra clave para agrupar los resultados por una dimensión de tiempo, ver métricas a lo largo del tiempo y devolver los períodos que no tienen datos como valores vacíos.
En este ejemplo, estás completando los datos faltantes de ventas totales de los últimos 15 días:
FROM sales
SHOW total_sales
GROUP BY product_title, billing_country
TIMESERIES day
SINCE -15dRangos de fechas predeterminados para TIMESERIES
Si tu consulta incluye TIMESERIES sin SINCE o DURING, se aplicará una fecha de inicio predeterminada, en función de la dimensión de tiempo por la que se agrupa. El rango se extiende hasta el final del día en curso, a menos que establezcas un valor para UNTIL .
| Dimensión de tiempo | Fecha de inicio predeterminada |
|---|---|
second | startOfMinute(-1min) |
minute | startOfHour(-1h) |
hour | startOfHour(-24h) |
day | startOfDay(-30d) |
week | startOfWeek(-4w) |
month | startOfMonth(-3m) |
quarter | startOfQuarter(-4q) |
year | startOfYear(-3y) |
hour_of_day | startOfDay(-3d) |
day_of_week | startOfWeek(-4w) |
week_of_year | startOfYear(-1y) |
month_of_year | startOfYear(-1y) |
TIMESERIES y el orden de las columnas
Según esté presente o no TIMESERIES se especifica y está presente en cualquiera de los GROUP BY o SHOW valores, el orden de las columnas puede cambiar.
TIMESERIES | SHOW | GROUP BY | Resultado |
|---|---|---|---|
| Dado | No está presente | No está presente | La TIMESERIES es la primera dimensión. |
| Dado | No está presente | Presente | La posición de las dimensiones de tiempo se define por su posición en GROUP BY. |
| Dado | Presente | Presente | La posición de las dimensiones de tiempo se define por su posición en SHOW. |
| No especificado | No está presente | Presente | La posición de las dimensiones de tiempo se define por su posición en GROUP BY. No se rellenan datos retroactivamente. |
| No especificado | Presente | Presente | La posición de las dimensiones de tiempo se define por su posición en SHOW. No se rellenan datos retroactivamente. |
| No especificado | Presente | No está presente | Genera un error de sintaxis porque SHOW solo puede hacer referencia a dimensiones presentes en GROUP BY. |
HAVING
Similar a WHERE, puedes usar la HAVING para filtrar los resultados de una consulta después de agruparlos. El filtro puede tener una única condición, pero esta se puede modificar tanto con operadores de comparación (como mayor que >) como con operadores lógicos (como AND o NOT). A diferencia de la WHERE palabra clave, HAVING puede hacer referencia a alias, funciones de agregación y columnas de agrupación.
HAVING exige que la consulta incluya GROUP BY o TIMESERIES cláusula porque HAVING filtra los resultados de una consulta después de agruparlos por GROUP BY o TIMESERIES.
En este ejemplo, filtras por productos con ingresos totales entre 1.000 y 5.000:
FROM sales
SHOW total_sales
GROUP BY product_title
HAVING total_sales > 1000 AND total_sales < 5000Filtrar con HAVING tiene algunas limitaciones con respecto a las palabras clave aceptadas: los totales, totales de grupos, comparaciones, cambios porcentuales y totales acumulados no son válidos en una condición HAVING , y hacer referencia a uno de ellos devuelve un error como 'comparison_total_sales__previous_year' is not allowed in the HAVING clause. Las métricas atribuidas son válidas, como total_sales__first_click cuando se aplica un modelo de atribución.
WITH
La WITH (palabra clave) modifica el comportamiento de ciertas palabras clave de ShopifyQL. Puedes usar las siguientes modificaciones:
TOTALS: Ofrece un resumen general de las métricas antes de desglosarlas por cualquier dimensión.GROUP_TOTALS: proporciona un total para todos los subgrupos cuando hay una agregación con GROUP BY.PERCENT_CHANGE: Agrega un valor de cambio porcentual a la fila de resumen para cada métrica de comparación enCOMPARE TO.CURRENCY: Muestra los datos en la moneda seleccionada.TIMEZONE: Calcula los resultados basados en el tiempo en la zona horaria IANA seleccionada.- Cualquier modelo de atribución, como
LAST_CLICK_ATTRIBUTION,FIRST_CLICK_ATTRIBUTION, oANY_CLICK_ATTRIBUTION: Aplica modelos de atribución de marketing a las métricas de ventas cuando se desglosan por una dimensión de marketing. Cada métrica atribuida reemplaza a la métrica en la que se basa. CUMULATIVE_VALUES: muestra la métrica como un total acumulado en lugar de como valores individuales para cada período.
TOTALS
La TOTALS proporciona un resumen de alto nivel de las métricas antes de desglosarlas por cualquier otra dimensión. Cuando usas WITH TOTALS, la tabla de datos muestra los totales en una fila de resumen al inicio de los resultados, etiquetada con el rango de fechas que cubre la consulta.
Las métricas aditivas, como net_sales, se suman en todo el conjunto de resultados. Las métricas de proporción y porcentaje, como average_order_value, se vuelven a calcular en todo el conjunto de resultados en lugar de sumarse a partir de las filas agrupadas.
Por ejemplo, esta consulta muestra las métricas de ventas diarias con una fila de resumen:
FROM sales
SHOW gross_sales, net_sales
TIMESERIES day WITH TOTALSEsta consulta podría devolver un informe similar a este:
| Día | Ventas brutas | Ventas netas |
|---|---|---|
| 1-3 de enero de 2024 | 6 | 15 |
| 2024-01-01 | 1 | 4 |
| 2024-01-02 | 2 | 5 |
| 2024-01-03 | 3 | 6 |
GROUP_TOTALS
La GROUP_TOTALS es un modificador que calcula un subtotal para cada grupo cuando una consulta se agrupa por al menos 2 dimensiones. ShopifyQL calcula un subtotal para cada conjunto de dimensiones agrupadas, excepto para el conjunto completo. Agrupar por 2 dimensiones produce 1 nivel de subtotales, y agrupar por 3 dimensiones produce 2 niveles.
Para mostrar los subtotales, tu consulta también debe ordenar por las dimensiones bajo las que están agrupados. Todas las dimensiones agrupadas, excepto la última, deben incluirse en ORDER BY, o ser la dimensión en TIMESERIES. Cuando tu consulta cumple ese requisito, la tabla de datos agrupa los resultados y agrega una fila Total para cada grupo. Cuando no lo hace, la tabla de datos permanece plana y los subtotales no se muestran en absoluto.
Cada subtotal tiene un nombre generado, que combina la métrica y las dimensiones que suma:
{metric_name}__{first_dimension}_totals, comototal_sales__billing_country_totals{metric_name}_{first_dimension}{second_dimension}_totals, que se produce cuando una consulta se agrupa por 3 dimensiones
Puedes hacer referencia a estos nombres en ORDER BY y VISUALIZE, ya sea que los subtotales se muestren o no.
Por sí solo, GROUP_TOTALS deja la fila de resumen vacía, ya que no se calcula ningún total general. Cuando también quieras una fila de resumen general, empareja GROUP_TOTALS con TOTALS.
Por ejemplo, esta consulta muestra las ventas totales de cada país de facturación cada día, con un subtotal para cada día. La consulta ordena por day, que es la dimensión agrupada para la que se calculan los subtotales, por lo que se muestran:
FROM sales
SHOW total_sales
GROUP BY day, billing_country WITH TOTALS, GROUP_TOTALS
SINCE -30d
ORDER BY day ASCEsta consulta podría devolver un informe similar a este:
| Día | País de facturación | Ventas totales |
|---|---|---|
| 1-30 de junio de 2024 | - | 150 |
| 1 de junio de 2024 | Total | 90 |
| 1 de junio de 2024 | Canadá | 50 |
| 1 de junio de 2024 | Estados Unidos | 40 |
| 2 de junio de 2024 | Total | 60 |
| 2 de junio de 2024 | Canadá | 60 |
La primera fila es la fila de resumen que TOTALS agrega. Cada fila Total es un subtotal del día cuyas filas agrupa.
Como la consulta ordena por day, la tabla de datos muestra una fila Total para cada día.
PERCENT_CHANGE
La PERCENT_CHANGE es un modificador que agrega un valor de cambio porcentual para cada métrica de comparación cuando usas COMPARE TO. Se calcula un cambio porcentual para cada fila que tiene un valor de comparación, pero la tabla de datos lo muestra solo en la fila de resumen, apilado con los valores de los 2 períodos que compara. Incluye TOTALS cuando quieras que se muestre el cambio porcentual, ya que TOTALS es lo que agrega la fila de resumen.
Cuando tu período del informe incluye la fecha actual, cada período se mide solo hasta el mismo punto en su propia unidad de tiempo, por lo que un período actual parcial se compara con un período equivalente hasta la fecha. Por ejemplo, el día 17 de un mes, cada mes de comparación se mide hasta su propio día 17.
Cada cambio porcentual tiene un nombre generado, que combina la métrica y el período de comparación:
- Una comparación relativa, como
COMPARE TO previous_year, agregapercent_change_net_sales__previous_year. - Una comparación de funciones de fecha, como
COMPARE TO startOfQuarter(-3q), agregapercent_change_total_sales__startOfQuarter_sub_3q, donde cada signo menos se convierte ensub.
Sin una comparación de fechas, este modificador no agrega ninguna columna de cambio porcentual.
La fórmula para calcular el cambio porcentual es: (base_column - comparison_column) * 100 / abs(comparison_column). Un valor positivo significa que el período base es mayor que el período de comparación, y un valor negativo significa que el período base es menor que el período de comparación.
Por ejemplo, esta consulta usa SINCE y COMPARE TO para comparar las ventas netas por día en el mes calendario anterior con el mismo mes en el año anterior, con un cambio porcentual en la fila de resumen:
FROM sales
SHOW net_sales
TIMESERIES day WITH TOTALS, PERCENT_CHANGE
SINCE startOfMonth(-1m) UNTIL endOfMonth(-1m)
COMPARE TO previous_yearEl informe muestra una columna de día y una columna de ventas netas. Cada celda apila el valor del período del informe con el valor del período de comparación, y la fila de resumen incluye el cambio porcentual.
CURRENCY
La CURRENCY modificador muestra los datos del informe en la moneda seleccionada. Las unidades de moneda deben ir entre comillas simples y usar el código de moneda de 3 letras correspondiente.
Por ejemplo, esta consulta usa CURRENCY para mostrar los datos de ventas netas en dólares canadienses (CAD).
FROM sales
SHOW net_sales
TIMESERIES day WITH CURRENCY 'CAD'TIMEZONE
La TIMEZONE es un modificador que calcula los resultados basados en el tiempo en tu informe en la zona horaria seleccionada, lo que incluye los límites que resuelven las funciones de fecha. Las zonas horarias deben ir entre comillas simples y usar un nombre válido de zona horaria de la Autoridad de Números Asignados en Internet (IANA, por sus siglas en inglés), como EST, UTC, o Europe/Paris.
Por ejemplo, esta consulta usa TIMEZONE para resolver cada límite de día en la America/New_York zona horaria, de modo que las ventas cerca del inicio o el final de un día se incluyan en el día esperado.
FROM sales
SHOW net_sales
TIMESERIES day WITH TIMEZONE 'America/New_York'
SINCE startOfMonth(-1m) UNTIL endOfMonth(-1m)Modelos de atribución
Puedes agregar cualquier modelo de atribución disponible como modificador para mostrar tus métricas de ventas con la atribución de marketing estándar. Esta opción está disponible solo cuando se usan tanto una métrica de ventas como una dimensión de marketing, y afecta únicamente a las métricas de ventas. Cuando se cumplen estas condiciones y no se selecciona ningún modelo de atribución, los informes usan de forma predeterminada LAST_CLICK_ATTRIBUTION.
Cuando aplicas un modelo de atribución, cada métrica de ventas elegible se reemplaza por una versión atribuida de sí misma. La atribución es el único WITH modificador que cambia las columnas en tu tabla de datos. El nuevo nombre de la columna combina el nombre de la métrica y el sufijo del modelo, y el encabezado de la columna nombra el modelo, como Ventas totales (último clic). Si la métrica se renombra con AS, el alias se usa en el nombre de la columna en lugar del nombre de la métrica.
Como se reemplaza la métrica, el nombre original de la métrica ya no es válido en el resto de la consulta. Por ejemplo, hacer referencia a la métrica original en ORDER BY, VISUALIZE, o HAVING devuelve un error como 'total_sales' is not allowed when applying attribution. Use: 'total_sales__last_click'. En su lugar, usa el nombre atribuido en esas palabras clave.
| Modelo de atribución | Sufijo de columna | Columna de ejemplo para total_sales |
|---|---|---|
FIRST_CLICK_ATTRIBUTION | __first_click | total_sales__first_click |
LAST_CLICK_ATTRIBUTION | __last_click | total_sales__last_click |
LAST_NON_DIRECT_CLICK_ATTRIBUTION | __last_non_direct_click | total_sales__last_non_direct_click |
ANY_CLICK_ATTRIBUTION | __any_click | total_sales__any_click |
LINEAR_ATTRIBUTION | __linear | total_sales__linear |
Puedes incluir más de un modelo de atribución en la misma WITH cláusula para comparar modelos uno al lado del otro. ANY_CLICK_ATTRIBUTION otorga crédito completo a cada punto de contacto, por lo que sus totales atribuidos pueden sumar más que el valor general de la métrica.
Por ejemplo, esta consulta usa LAST_CLICK_ATTRIBUTION para mostrar las ventas totales por canal de referencia atribuidas al último clic, lo que muestra una columna de Ventas totales (último clic):
FROM sales
SHOW total_sales
GROUP BY ONLY TOP 5 referring_channel WITH TOTALS, LAST_CLICK_ATTRIBUTION
SINCE startOfDay(-30d) UNTIL today
ORDER BY total_sales__last_click DESC
VISUALIZE total_sales__last_clickMás información sobre los modelos de atribución en los informes.
CUMULATIVE_VALUES
Cuando muestras una métrica a lo largo del tiempo, puedes elegir mostrarla como un total acumulado en lugar de como valores individuales para cada período. A esto se le llama vista acumulativa, y facilita hacer seguimiento del progreso general en un rango de fechas, como la forma en que aumentan las ventas para alcanzar un objetivo mensual.
Para representar esta vista acumulativa en ShopifyQL, agrega CUMULATIVE_VALUES a tu cláusula WITH . Además, tu consulta de ShopifyQL debe incluir una dimensión de tiempo en la TIMESERIES o GROUP BY instrucciones.
Por ejemplo:
FROM sales
SHOW total_sales
GROUP BY product_title, billing_country
TIMESERIES day WITH TOTALS, CUMULATIVE_VALUESCada total acumulado tiene un nombre generado, {metric_name}__cumulative, como net_sales__cumulative, al que puedes hacer referencia en ORDER BY y VISUALIZE. Las métricas donde no tiene sentido sumar valores a lo largo del tiempo, como average_order_value o conversion_rate, no generan un total acumulado.
Más información sobre cómo incluir valores acumulativos en las visualizaciones.
SINCE y UNTIL
Para filtrar la consulta por una fecha o un período, usa SINCE y UNTIL como palabras clave y sus parámetros asociados. Estas palabras clave son únicas porque solo filtran períodos. Ambos límites son inclusivos.
Por ejemplo, esta consulta obtiene las ventas netas de los últimos 12 meses, en Canadá, hasta ayer:
FROM sales
SHOW net_sales
WHERE billing_country = 'Canada'
GROUP BY month
SINCE -12m UNTIL yesterdaySi usas SINCE y no defines un UNTIL como valor, el rango de tiempo abarca hasta el final del día actual, lo que produce el mismo resultado que UNTIL today. Para que el rango termine en el momento en que se ejecuta la consulta, usa UNTIL now. Si usas UNTIL sin SINCE, la consulta debe incluir TIMESERIES, que proporciona una fecha de inicio predeterminada. De lo contrario, la consulta devuelve el error UNTIL requires SINCE without TIMESERIES present.
Operadores de desplazamiento
Puedes filtrar por fechas específicas o por desplazamientos de fecha y hora. Los operadores de desplazamiento de ShopifyQL son:
| Operador de desplazamiento | Descripción |
|---|---|
-{#}s | Número de segundos antes de la fecha y hora en que se ejecuta la consulta. |
-{#}min | Número de minutos atrás desde la fecha y hora en que se ejecuta la consulta. |
-{#}h | Número de horas transcurridas desde la fecha y hora en que se ejecuta la consulta. |
-{#}d | Número de días atrás desde la fecha y hora en que se ejecuta la consulta. |
-{#}w | Número de semanas atrás desde la fecha y hora en que se ejecuta la consulta. |
-{#}m | Número de meses antes de la fecha y hora en que se ejecuta la consulta. |
-{#}q | Número de trimestres antes de la fecha y hora en que se ejecuta la consulta. |
-{#}y | Número de años antes de la fecha y hora en que se ejecuta la consulta. |
yyyy-MM-dd | Una fecha específica. |
yyyy-MM-ddThh:mm:ss | Una fecha y hora específicas. |
El signo menos marca un momento en el pasado. Un desplazamiento se calcula hasta un momento dado medido a partir de la ejecución de la consulta, en lugar de un límite del calendario. Por ejemplo, si ejecutas SINCE -1m el 15 de marzo, el rango comienza el 15 de febrero y no el 1 de febrero. Un desplazamiento escrito sin un signo menos se resuelve como un tiempo en el futuro, por lo que -1m y 1m no son equivalentes.
Para un rango que comience o termine en un límite del calendario, usa una función de fecha, como SINCE startOfMonth(-1m) UNTIL endOfMonth(-1m) para el mes calendario anterior, o SINCE startOfMonth(0m) para el primer día del mes actual.
La hora del día a la que se resuelve un desplazamiento depende de su unidad. Los desplazamientos de segundos, minutos y horas mantienen la hora del día en que se ejecuta la consulta. Los desplazamientos de días, semanas, meses, trimestres y años se resuelven a la medianoche, por lo que UNTIL -0m termina el rango al inicio del día actual en lugar de en la hora actual. Para terminar el rango en el momento en que se ejecuta la consulta, usa UNTIL now. Para abarcar la totalidad del día actual, omite UNTIL.
Funciones de fecha
Puedes usar las siguientes funciones junto con cualquier operador de rango de fechas (excepto fechas específicas) en SINCE y UNTIL sentencias. La "startOf..." funciones truncan al inicio de la unidad de tiempo asociada (minuto, hora, día, semana, mes, trimestre y año) cuando se usan con SINCE, y la "endOf...las funciones "fin de" truncan al final de la unidad de tiempo asociada cuando se usan con UNTIL.
Las unidades de la función de fecha y del operador deben coincidir para devolver un resultado válido. Por ejemplo, startOfMonth(-1m) es correcto, pero startOfMonth(-1d) no es válido.
| Función de fecha | Descripción |
|---|---|
now | La fecha y la hora en que se ejecuta la consulta. |
startOfMinute(-{#}min) | Trunca el operador de rango de fechas al inicio del minuto objetivo. |
endOfMinute(-{#}min) | Trunca el operador de rango de fechas hasta el final del minuto objetivo. |
startOfHour(-{#}h) | Trunca el operador de rango de fechas al inicio de la hora de destino. |
endOfHour(-{#}h) | Trunca el operador de rango de fechas al final de la hora de destino. |
startOfDay(-{#}d) | Trunca el operador de rango de fechas al inicio del día objetivo. |
endOfDay(-{#}d) | Trunca el operador de rango de fechas al final del día de destino. |
startOfWeek(-{#}w) | Trunca el rango de fechas al inicio de la semana de destino. |
endOfWeek(-{#}w) | Trunca el operador de rango de fechas al final de la semana de destino. |
startOfMonth(-{#}m) | Trunca el rango de fechas al inicio del mes de destino. |
endOfMonth(-{#}m) | Trunca el operador de rango de fechas al final del mes objetivo. |
startOfQuarter(-{#}q) | Trunca el rango de fechas al inicio del trimestre de destino. |
endOfQuarter(-{#}q) | Trunca el rango de fechas al final del trimestre de destino. |
startOfYear(-{#}y) | Trunca el operador de rango de fechas al inicio del año de destino. |
endOfYear(-{#}y) | Trunca el operador de rango de fechas al final del año objetivo. |
Por ejemplo, si hoy es el 8 de noviembre de 2022, puedes usar la siguiente consulta para obtener las ventas brutas desde el 1 de enero de 2020 hasta el 31 de octubre de 2022:
FROM sales
SHOW gross_sales
SINCE startOfYear(-2y) UNTIL endOfMonth(-1m)DURING
La DURING la palabra clave simplifica el filtrado por fechas para rangos de fechas y reemplaza el uso de SINCE y UNTIL. Debido a que DURING define el período de informes completo, no lo combines con SINCE o UNTIL en la misma consulta.
Puedes usar DURING como palabra clave para filtrar los resultados de la consulta de un período conocido, como un año calendario o un mes específico, o para rangos de fechas que tienen fechas diferentes cada año, como el Black Friday y Cyber Monday (BFCM). DURING solo acepta operadores de rangos de fechas con nombre, como yesterday o last_year, y no acepta now.
Por ejemplo, esta consulta filtra por fecha para el BFCM de 2021:
FROM sales
SHOW total_sales
GROUP BY day
DURING bfcm2021Si necesitas una fecha específica, un desplazamiento relativo o una función de fecha como límite, usa SINCE y UNTIL.
Operadores de rango de fechas con nombre
DURING acepta cualquiera de los siguientes operadores de rango de fechas con nombre:
| Operador de rango de fechas con nombre | Descripción |
|---|---|
today | La fecha en que se ejecuta la consulta. |
yesterday | El día calendario anterior. |
this_week | La semana del calendario actual. |
this_month | El mes actual del calendario. |
this_quarter | El trimestre calendario actual. |
this_year | El año natural actual. |
last_week | La semana natural anterior. |
last_month | El mes natural anterior. |
last_quarter | El trimestre natural anterior. |
last_year | El año calendario anterior. |
this_weekend | El fin de semana actual. |
last_weekend | El fin de semana anterior. |
bfcmYYYY | El rango de Black Friday Cyber Monday para el año especificado. Por ejemplo, bfcm2022 devuelve resultados del 25 al 28 de noviembre de 2022. |
COMPARE TO
La COMPARE TO , como palabra clave, compara el período de informes que estableces con SINCE y UNTIL, o con DURING, con otro período o con los objetivos configurados.
Puedes usar COMPARE TO palabra clave con los siguientes tipos de parámetros:
- Fechas absolutas, como
2023-01-01: incluye las métricas del período especificado y las métricas de comparación para ese mismo período en la fecha absoluta. - Fechas con nombre, como
last_week: incluye las métricas del periodo especificado y las métricas de comparación para ese mismo periodo en la fecha indicada.- El operador que utiliza
COMPARE TOno tiene que tener la misma duración temporal que la usada porDURING. Si no se especificaUNTILsi se proporciona un valor, entonces calcula el intervalo de tiempo para que sea igual al valor especificado enDURING. Por ejemplo,DURING this_week COMPARE TO last_monthcompara los datos de esta semana con un período de una semana que comienza al inicio del mes pasado.
- El operador que utiliza
- Offset dates, como
-3q: incluye las métricas del período especificado y las métricas de comparación para el mismo período en la fecha relativa. - Comparaciones de varias fechas, como
-1y, -2y: compara los datos de un rango de fechas específico con varios otros rangos. Es útil para hacer seguimiento de cambios a lo largo de varios periodos. - Los objetivos configurados, usando
COMPARE TO TARGETS: compara tus datos con los objetivos que estableciste para una métrica, en lugar de con otro rango de fechas. Esta opción está disponible para las métricas que admiten objetivos. - Si usas una dimensión de fecha en una consulta con
COMPARE TO, entonces usaTIMESERIESpara ello, en lugar deGROUP BY.
El siguiente ejemplo compara las ventas netas durante el mes calendario anterior con el mismo mes del año anterior:
FROM sales
SHOW net_sales, product_title
GROUP BY product_title
TIMESERIES day
SINCE startOfMonth(-1m) UNTIL endOfMonth(-1m)
COMPARE TO previous_yearCuando usas COMPARE TO, cada métrica comparada obtiene un valor de comparación. Los valores de comparación no se muestran en sus propias columnas en la tabla de datos. Cada celda de la tabla de datos apila el valor del período de informes con el valor del período de comparación, y cada etiqueta de fila apila los 2 períodos de la misma manera. Cada comparación tiene un nombre generado, que combina la métrica y el período de comparación, por lo que una métrica puede tener más de una comparación. Puedes hacer referencia a una comparación por su nombre en ORDER BY o VISUALIZE:
- Una comparación relativa agrega
comparison_net_sales__previous_year. - Una comparación de fecha específica agrega
comparison_net_sales__20230101. - Una comparación de fecha con nombre agrega
comparison_net_sales__last_week. - Una comparación de función de fecha agrega
comparison_net_sales__startOfQuarter_sub_3q, donde cada signo menos se convierte ensub.
Operadores de rango de fechas relativos
Los operadores relativos devuelven el mismo periodo de tiempo que el rango de fechas base, desplazado hacia atrás según el periodo especificado. Además de los named date range operators, COMPARE TO acepta los siguientes operadores relativos:
| Operador de intervalo de fechas relativo | Descripción |
|---|---|
previous_period | Un período antes del rango de fechas base. |
previous_year | Un año antes del rango de fechas base. |
previous_quarter | Un trimestre antes del intervalo de fechas base. |
previous_month | Un mes antes del rango de fechas base. |
previous_week | Una semana antes del rango de fechas base. |
previous_day | Un día antes del intervalo de fechas base. |
previous_hour | Una hora antes del rango de fechas base. |
previous_minute | Un minuto antes del rango de fechas base. |
previous_second | Un segundo antes del rango de fechas base. |
previous_year_match_day_of_week | 52 semanas antes del rango de fechas base, lo que mantiene la comparación alineada a los mismos días de la semana. |
Comparación con los objetivos
COMPARE TO TARGETS requiere TIMESERIES y un período de informes, que estableces con SINCE, UNTIL, o DURING. No puedes combinar TARGETS con ningún otro período de comparación. A diferencia de una comparación de fechas, los objetivos no agregan ningún valor a los resultados de la consulta, por lo que la tabla de datos permanece sin cambios, y PERCENT_CHANGE no tiene efecto. En su lugar, el objetivo se muestra en la visualización, como una línea de ritmo en la vista acumulativa de una visualización de líneas o de barras.
Para mostrar tu progreso hacia un objetivo como un medidor, usa VISUALIZE {metric} TYPE target_gauge. Un medidor de objetivos no requiere COMPARE TO TARGETS, pero el rango de fechas de tu consulta debe coincidir con el período de un objetivo que hayas establecido. Si ningún objetivo coincide con el rango de fechas, la visualización informa que no se encontró ningún objetivo para tu selección.
Más información sobre cómo establecer objetivos para las métricas.
ORDER BY
Puedes especificar cómo quieres ordenar los datos que devuelve la consulta con ORDER BY palabra clave y sus parámetros: ASC, para orden ascendente, y DESC, para orden descendente.
Puedes especificar cualquier métrica o dimensión que incluyas en la consulta en ORDER BY palabra clave, incluidos varios campos.
Por ejemplo, esta consulta devuelve las ventas netas de todos los productos y variantes del último año. Primero, los resultados se ordenan alfabéticamente por nombre del producto y luego en orden alfabético inverso por tipo de producto:
FROM sales
SHOW net_sales
GROUP BY product_title, product_type
SINCE -1y UNTIL today
ORDER BY product_title, product_type DESCEl orden en que escribas las métricas o las dimensiones importa. Si especificas varios valores para ORDER BY, entonces la ordenación se aplica a cada métrica o dimensión en el orden indicado.
TIMESERIES y el orden de los resultados
Según si la consulta incluye TIMESERIES y ORDER BY, el orden de las filas devueltas puede cambiar.
TIMESERIES | ORDER BY | Resultado |
|---|---|---|
| Presente | No está presente | Los resultados se ordenan por TIMESERIES dimensión. |
| Presente | Presente | Los resultados se ordenan por TIMESERIES dimensión temporal, entonces ORDER BY dimensión. |
| No está presente | Presente | Los resultados se ordenan por ORDER BY dimensión. |
| No está presente | No está presente | Los resultados se ordenan por la primera SHOW columna. |
LIMIT
La LIMIT permite especificar un número máximo de filas que devuelve la consulta. Es útil cuando quieres ver una vista previa de cómo se muestran los datos, acelerar las consultas en conjuntos de datos grandes o crear listas de los 10 principales. Puedes combinar LIMIT con ORDER BY para crear listas de mejores y peores.
Si no especificas un LIMIT valor, la consulta usa 1.000 filas de forma predeterminada.
También puedes usar un { OFFSET # } parámetro para omitir cierta cantidad de filas antes de empezar a devolver datos de filas. La frase resultante tendría un formato similar a: LIMIT 15 { OFFSET 5 }.
Este ejemplo usa LIMIT y ORDER BY para crear una lista de los 10 productos más vendidos de los últimos 3 meses:
FROM sales
SHOW gross_sales as total_gross_sales
GROUP BY product_title
SINCE -3m UNTIL today
ORDER BY total_gross_sales DESC
LIMIT 10VISUALIZE y TYPE
La VISUALIZE te permite escribir una consulta de ShopifyQL que muestra datos en una visualización gráfica.
La TYPE la palabra clave es opcional y debe ir acompañada de un único tipo de visualización. Si TYPE no se incluye en la consulta, ShopifyQL selecciona automáticamente la visualización más adecuada. Si la consulta no se puede visualizar tal como está escrita, ShopifyQL devuelve datos tabulares. Puedes consultar la TYPE palabra clave para cada visualización en Seleccionar la visualización adecuada para el informe de Shopify.
VISUALIZE también acepta un parámetro opcional LIMIT palabra clave, donde el parámetro es el número limitado de puntos de datos que se van a mostrar en la visualización y en la tabla de datos. También puedes usar el MAX , como palabra clave, para limitar el número de puntos de datos en la visualización sin afectar a los datos en la tabla de datos. MAX es la palabra clave preferida en las nuevas consultas.
Por ejemplo, puedes visualizar la tendencia de tus ventas del último año por mes con una línea de tendencia. Esta consulta devuelve un gráfico de serie temporal que muestra las ventas brutas por mes durante el último año. Las ventas brutas se representan con una sola línea; el eje x está etiquetado como mes y el eje y como ventas brutas:
FROM sales
SHOW gross_sales
TIMESERIES month
SINCE -1y UNTIL today
VISUALIZE gross_sales TYPE lineMúltiples métricas en las visualizaciones
Puedes incluir varias métricas en las visualizaciones de líneas del informe. Cada métrica incluida en la visualización debe separarse por una coma, junto con la palabra clave TYPE line . Las métricas que se enumeran en SHOW pero no en VISUALIZE , se muestran solo en la tabla de datos.
Por ejemplo, la siguiente consulta incluye las ventas totales, los pedidos y las sesiones como 3 líneas separadas en la visualización. Las ventas brutas se muestran en la tabla de datos, pero no en la visualización:
FROM sales
SHOW total_sales, orders, sessions, gross_sales
TIMESERIES month
SINCE -1y UNTIL today
VISUALIZE total_sales, orders, sessions TYPE linePara usar la visualización de tipo barras y líneas, puedes separar las 2 métricas con una coma y especificar las diferentes TYPE diferente para cada métrica:
FROM sales
SHOW total_sales, orders, conversion_rate, gross_sales
TIMESERIES month
SINCE -1y UNTIL today
VISUALIZE total_sales TYPE bar, conversion_rate TYPE lineObtén más información sobre cómo incluir varias métricas en las visualizaciones de los informes.
ANNOTATE
La ANNOTATE (palabra clave) muestra anotaciones en la visualización para que puedas comparar un cambio en una métrica con los eventos que podrían explicarlo.
Escribe ANNOTATE al final de tu declaración de VISUALIZE , después de cualquier parámetro TYPE y MAX . Puedes hacer anotaciones de las siguientes formas:
ANNOTATE ALL: Muestra todas las categorías de anotaciones de todas las fuentes, lo que incluye las generadas por Shopify, las creadas por apps y las creadas por ti y tus empleados.ANNOTATE {category}: Muestra cada anotación en una categoría, comoANNOTATE product_events.ANNOTATE {category}.{type}: Muestra un solo tipo de anotación, comoANNOTATE product_events.published.
Para combinar categorías y tipos, sepáralos con comas. Consulta la documentación para desarrolladores de Shopify para obtener una lista completa de categorías y tipos de anotaciones.
Por ejemplo, esta consulta muestra las ventas totales diarias de los últimos 90 días, con marcadores para cada producto que se publicó o dejó de publicarse, y para cada tema que se publicó:
FROM sales
SHOW total_sales
TIMESERIES day
SINCE -90d
VISUALIZE total_sales TYPE line ANNOTATE product_events, online_store_events.theme_publishedPara mostrar anotaciones solo de creadores o fuentes específicos, agrega FILTER después de las categorías y los tipos de anotaciones, seguido de una o más condiciones. Si no incluyes FILTER, se muestran las anotaciones de todas las fuentes. Puedes filtrar las anotaciones por los siguientes campos:
source: La fuente de la anotación. Usa'shopify'para las anotaciones generadas por Shopify,'app'para las anotaciones creadas por apps o'staff'para las anotaciones creadas por ti y tus empleados.app_id: La identificación de la app que creó la anotación.staff_id: La identificación del empleado que creó la anotación.
Usa = para filtrar por un valor o IN para filtrar por una lista de valores, como source IN ('app', 'staff'). Ingresa las identificaciones de las apps y de los empleados como números sin comillas, como staff_id = 123. Para combinar condiciones, sepáralas con OR. Los filtros de anotaciones no admiten AND. Los nombres de los campos y los valores de origen distinguen entre mayúsculas y minúsculas. Cuando ingresas app_id o staff_id en el editor de consultas de ShopifyQL, se sugieren las apps y los empleados que han creado anotaciones.
Por ejemplo, esta consulta muestra las ventas totales diarias de los últimos 90 días, con marcadores para cada anotación creada por ti y tus empleados:
FROM sales
SHOW total_sales
TIMESERIES day
SINCE -90d
VISUALIZE total_sales TYPE line ANNOTATE ALL FILTER source = 'staff'Las anotaciones necesitan una dimensión de tiempo, por lo que tu consulta debe devolver una con TIMESERIES o GROUP BY, y usar un tipo de visualización con un eje de tiempo. Las anotaciones no están disponibles en las consultas de varias tiendas que usan FROM ORGANIZATION.
AS
La palabra clave AS es una palabra clave opcional que te permite cambiar el nombre (o asignar un alias) a una columna o a una expresión.
AS acepta solo un parámetro. Si el alias tiene un espacio en el nombre, debes encerrar el alias entre comillas dobles (").
FROM sales
SHOW total_sales AS "My Total Sales"Otros operadores y funciones de ShopifyQL
ShopifyQL incluye los siguientes operadores adicionales:
- Mathematical operators, como
+o/ - Implicit joins
- Partial string and array matching, como
STARTS WITHyCONTAINS - Comments
- Mostrar datos de organizaciones con varias tiendas
- Metacampos
- Metaobjetos
Operadores matemáticos
ShopifyQL permite realizar operaciones aritméticas con las métricas de tus datos. Están disponibles los siguientes operadores matemáticos:
| Operador matemático | Descripción |
|---|---|
| + | Suma de dos números. |
| - | Resta de dos números. |
| * | Multiplicación de dos números. |
| / | División de dos números. |
Las expresiones matemáticas tienen las siguientes limitaciones:
- Ambos valores de una expresión deben ser numéricos. Las dimensiones como los nombres de los productos, las identificaciones y los valores verdaderos o falsos no pueden usarse en aritmética, incluso si una identificación se muestra como un número.
- Las fechas y las horas solo admiten restas. Puedes restar una fecha de otra o una hora de otra, pero no puedes sumarlas, multiplicarlas ni dividirlas.
- Las expresiones se calculan en la
SHOWpalabra clave. UnaWHEREcondición no puede incluir operaciones aritméticas. - No se pueden usar operaciones matemáticas en un campo utilizado para unir tablas. Obtén más información sobre las uniones implícitas.
Por ejemplo, esta consulta calcula el valor del pedido para cada región durante el último año. Cuando uses operadores matemáticos con métricas, puedes usar el AS palabra clave para asignar un nombre nuevo a la métrica nueva.
FROM sales
SHOW (net_sales + sales_reversals) AS order_value, orders
GROUP BY billing_region
SINCE -1y UNTIL todayUniones implícitas
Una unión te permite ver métricas de distintos dominios juntas, lado a lado. Las uniones se realizan de forma implícita e inteligente en ShopifyQL.
ShopifyQL tiene las siguientes capacidades de unión (join):
- ShopifyQL permite uniones por campos de dimensión cuando hay un único
FROMtabla en la consulta. - Unión izquierda automática en campos de dimensión.
- ShopifyQL permite uniones de múltiples hechos (cuando hay múltiples
FROMtablas en las consultas). - Unión completa automática en uniones multifacto, que admiten cualquier número de tablas o esquemas y se agrupan por dimensiones.
- En las uniones de múltiples hechos, las métricas pueden usar math.
ShopifyQL tiene las siguientes restricciones de unión:
- El campo de unión debe tener el mismo nombre en todos los esquemas combinados.
- El campo de unión debe estar en
GROUP BY. - El campo de unión no puede usar math.
FROMes necesario para que funcionen las uniones de múltiples hechos.- En una unión con varias tablas de hechos, cada
GROUP BYdebe estar en todos los esquemas y se considera un campo sobre el que se realiza la unión.
Por ejemplo, esta consulta usa una unión multifacto:
FROM sales, sessions
SHOW day, total_sales, sessions
GROUP BY day
SINCE 2023-10-03
ORDER BY dayCoincidencia parcial de cadenas y arrays
Puedes usar los siguientes operadores para la coincidencia parcial de cadenas y arrays:
| Operador | Descripción |
|---|---|
STARTS WITH | Devuelve todas las filas en las que una columna empieza con un prefijo. |
ENDS WITH | Devuelve todas las filas en las que una columna termine con un sufijo. |
CONTAINS | Devuelve todas las filas en las que una columna contiene una parte de una cadena o un elemento en una matriz. |
NOT CONTAINS | Devuelve todas las filas donde una columna no contiene una parte de una cadena o un elemento en un arreglo. |
Algunos ejemplos de coincidencia parcial de cadenas mediante operadores son las siguientes consultas:
FROM sales
SHOW product_title
WHERE product_title STARTS WITH 'Summer'
GROUP BY product_titleFROM sales
SHOW product_title
WHERE product_title ENDS WITH 'kit'
GROUP BY product_titleFROM sales
SHOW product_title
WHERE product_title CONTAINS 'Beef'
GROUP BY product_titleLa CONTAINS se puede usar para hacer coincidir elementos dentro de arrays, incluidos enteros, cadenas y decimales. Esta coincidencia no distingue mayúsculas de minúsculas. Algunos ejemplos de coincidencia en arrays con CONTAINS incluyen las siguientes consultas:
FROM sales
SHOW orders
WHERE products_bought_together_ids CONTAINS '101'FROM customers
SHOW total_number_of_orders
WHERE customer_cities CONTAINS 'seattle'FROM sales
SHOW orders
WHERE variants_bought_together_variant_prices CONTAINS '10.2'Comentarios
Puedes usar comentarios para explicar secciones de sentencias de ShopifyQL o para evitar la ejecución de una sentencia de ShopifyQL. Cualquier texto dentro de un comentario se ignorará en el momento de la ejecución.
Los comentarios de una sola línea comienzan con -- y terminan al final de la línea.
Los comentarios de varias líneas comienzan con /* y terminan con */.
FROM sales
SHOW average_order_value, gross_sales
-- the line below has been commented out and won't run
-- GROUP BY billing_region
WHERE billing_country = 'United States'
/*
this line and the two lines below it have been commented out and won't run
SINCE 2021-01-01
UNTIL 2021-12-31
*/Otros datos que puedes consultar con ShopifyQL
También puedes usar ShopifyQL para consultar los siguientes datos:
Mostrar datos para organizaciones con varias tiendas
Si tu tienda está en un plan Plus o Enterprise y tienes varias tiendas dentro de una organización, puedes modificar ligeramente tu consulta de ShopifyQL para mostrar datos de varias tiendas a la vez. La FROM debe ir seguida de ORGANIZATION, y el WHERE debe incluir la shop_id para las tiendas que quieres incluir en la consulta, declaradas como parámetro.
Por ejemplo, puedes obtener la suma de los ingresos totales de 4 tiendas de tu organización con esta consulta:
FROM ORGANIZATION sales
SHOW total_sales
WHERE shop_id IN (12301, 12302, 12303, 12304)Filtrar por shop_id requiere FROM ORGANIZATION. Para encontrar el shop_id valor para cada tienda de tu organización, ejecuta una consulta de organización por shop_id:
FROM ORGANIZATION sales
SHOW total_sales
GROUP BY shop_name, shop_idLas consultas de varias tiendas también requieren el permiso de informes y estadísticas de la organización.
Metacampos
Puedes usar los metacampos de categoría de productos y los metacampos personalizados compatibles como dimensiones o filtros en tus consultas de ShopifyQL.
Metacampos de categoría de productos en ShopifyQL
Los metacampos de categoría se asignan a categorías de productos específicas en la taxonomía de productos estándar de Shopify.
Los metacampos de categoría se formatean con notación de punto en las consultas de ShopifyQL. El formato para un metacampo es product.metafields.shopify.{key}, donde el valor {key} es el nombre específico del metacampo, como material o size. Las claves de la taxonomía estándar formadas por varias palabras separadas por guiones usan identificadores de escape, por lo que el formato del metacampo es product.metafields.shopify."color-pattern" o product.metafields.shopify."age-group". Para filtrar un metacampo de categoría por un valor, se necesita el operador CONTAINS o NOT CONTAINS.
Por ejemplo, si vendes macetas para jardín y usas la categorización estándar Hogar y jardín > Césped y jardín > Jardinería > Macetas y jardineras para tus productos, podrías usar el metacampo Forma de la categoría para almacenar la forma de cada maceta (como cilíndrica, rectangular, redonda o cuadrada). Luego, podrías usar product.metafields.shopify.shape como dimensión o filtro en los informes.
A continuación, puedes mostrar las ventas totales por producto, filtradas por el metacampo estándar Forma para incluir solo los productos "Rectangulares", mediante la siguiente consulta:
FROM sales
SHOW total_sales
GROUP BY product.title
WHERE product.metafields.shopify.shape CONTAINS 'Rectangular'Cuando agrupas por un metacampo de categoría, todas las entradas de un producto para ese metacampo se tratan como un único valor. Por ejemplo, si una maceta tiene seleccionados los valores Interiores y Exteriores en el metacampo Espacio adecuado de la categoría, sus ventas se agruparán en Interiores, Exteriores en lugar de contarse por separado para cada espacio. Las macetas que no tengan ninguna entrada en Espacio adecuado se agrupan como (no establecido).
Puedes mostrar las ventas totales por Espacio adecuado mediante la siguiente consulta:
FROM sales
SHOW total_sales
GROUP BY product.metafields.shopify."suitable-space"Metacampos personalizados en ShopifyQL
ShopifyQL admite metacampos personalizados para los siguientes tipos de recursos:
- Productos
- Variantes
- Clientes
- Pedidos
Para cada uno de los tipos de recursos aplicables, ShopifyQL admite los siguientes tipos de metacampos personalizados:
- Texto:
single_line_text_field,multi_line_text_field - Referencia:
product_reference - Números:
number_integer,number_decimal,id,rating - Enlace:
url - Fechas:
date,date_time - Otros:
boolean,color - Listas:
list.single_line_text_field,list.multi_line_text_field,list.number_integer,list.number_decimal
Cuando crees el metacampo, debes activar la opción Filtrar o agrupar datos en Informes y estadísticas antes de poder usarlo como dimensión o filtro en los informes de Shopify.
Los metacampos personalizados se deben formatear con notación de punto en las consultas de ShopifyQL. El formato para un metacampo es {entity}.metafields.{namespace}.{key}. Por ejemplo, si creaste un metacampo personalizado de "Material" para tus productos con el fin de almacenar el tipo de material del que está hecho cada uno (como poliéster, algodón, lino y nailon), podrías usar product.metafields.custom.material como dimensión o filtro en los informes.
Por ejemplo, puedes mostrar las ventas totales por producto, filtradas por el metacampo personalizado Material para incluir solo los productos con el material "algodón orgánico", mediante la siguiente consulta:
FROM sales
SHOW total_sales
WHERE product.metafields.custom.material = 'organic cotton'
GROUP BY product.titleTambién puedes acceder a los valores de los metacampos directamente en las consultas de ShopifyQL. Por ejemplo, puedes analizar los datos de los clientes en función de los valores de un metacampo personalizado Nivel de fidelización que sean superiores al nivel 2:
FROM customers
SHOW total_amount_spent
WHERE metafields.custom.loyalty_tier > 2
GROUP BY metafields.custom.loyalty_tierEn el ejemplo anterior, la entidad de recurso customers se declara en la FROM instrucción, por lo que no es necesario incluirla de nuevo en la GROUP BY o WHERE instrucciones.
Eventos de apps
Las apps instaladas en tu tienda pueden enviar eventos a Shopify, como un correo electrónico enviado por una app de marketing o una recompensa canjeada en una app de lealtad. Puedes crear informes sobre esos eventos si consultas FROM app_eventsy los agrupas por app o por período de tiempo.
Los datos de eventos de las apps que puedes consultar dependen de las que estén instaladas en tu tienda y de si el desarrollador de cada app envía eventos a Shopify.
Las apps pueden enviar eventos estándar, que utilizan un nombre de evento con el formato shopify.{category}.{event}, como shopify.marketing.email_sent. Cada evento tiene sus propias métricas y dimensiones. Por ejemplo, el evento shopify.marketing.email_sent tiene la métrica emails_sent y dimensiones como campaign_id y message_type.
Revisa la siguiente tabla para obtener más información sobre los campos que están disponibles para cada evento de las apps.
| Campo | Tipo | Descripción |
|---|---|---|
app_name | Dimensión | El nombre de la app que envió el evento. Agrupa por este campo para comparar la misma métrica en distintas apps. |
event_handle | Dimensión | El nombre del evento, como shopify.marketing.email_sent. |
event_count | Métrica | El número de eventos que enviaron las apps. |
latest_event_timestamp | Métrica | La fecha y hora del evento más reciente. |
Por ejemplo, para comparar el número de correos electrónicos que envió cada una de tus apps de marketing durante los últimos 30 días, la consulta es la siguiente:
FROM app_events
SHOW emails_sent
GROUP BY app_name
TIMESERIES day
SINCE -30dNo puedes consultar el app_events conjunto de datos junto con otro en la misma consulta. Por ejemplo, FROM sales, app_events no es compatible.
Eventos personalizados de apps en ShopifyQL
Además de los eventos estándar, algunas apps definen sus propios eventos personalizados, con métricas y dimensiones específicas de la app. Por ejemplo, una app de reserva de citas con el identificador bookings podría definir un evento appointment_booked. El evento podría tener una métrica appointments para la cantidad de citas que los clientes reservan, y una dimensión service_type para el tipo de servicio al que corresponde cada cita.
En las consultas de ShopifyQL, da formato a los campos de eventos personalizados de apps usando la notación de puntos: event.{app}.{event}.{field}. La parte {app} es el identificador o la clave API de la app, según lo que el desarrollador haya elegido. Por ejemplo, la métrica appointments de la app de reservas es event.bookings.appointment_booked.appointments.
Si parte de un nombre de campo incluye un guion, debes encerrar esa parte entre comillas dobles ("). Por ejemplo, si el identificador de la app de reservas es bookings-app, el campo será event."bookings-app".appointment_booked.appointments.
Cada campo de un evento personalizado de la app está disponible solo para el evento que lo define. En la dimensión event_handle, los eventos personalizados usan el nombre {app}.{event}, como bookings.appointment_booked.
En los resultados de la consulta y las exportaciones a formato CSV, los campos de los eventos personalizados de apps usan las etiquetas que la app les asigna.
Las dimensiones de los eventos personalizados de apps solo están disponibles para los últimos 30 días de datos. Si tu consulta agrupa o filtra por una de ellas, usa un rango de fechas que comience dentro de los últimos 30 días, como SINCE -7d.
Por ejemplo, para comparar el número de citas que los clientes reservaron para cada tipo de servicio durante los últimos 7 días, tu consulta es:
FROM app_events
SHOW event.bookings.appointment_booked.appointments
GROUP BY event.bookings.appointment_booked.service_type
TIMESERIES day
SINCE -7dMetaobjetos
Puedes usar los campos de tus metaobjetos como dimensiones o filtros en tus consultas de ShopifyQL cuando un metacampo en un tipo de recurso compatible hace referencia al metaobjeto. ShopifyQL admite campos de metaobjetos para los siguientes tipos de recursos:
- Productos
- Variantes
- Clientes
- Pedidos
El metacampo de referencia debe ser una referencia a un único metaobjeto o una lista de referencias a metaobjetos. Los campos de un metaobjeto al que se hace referencia a través de un metacampo de Referencia mixta no se pueden usar en una consulta, y no se admiten todos los tipos de campo de metaobjetos.
El formato de los campos de los metaobjetos utiliza la notación de puntos, la cual amplía el metacampo de referencia con el campo del metaobjeto. El formato es: {entity}.metafields.{namespace}.{key}.{field}, donde {namespace}.{key} es el metacampo de referencia y {field} es el campo del metaobjeto que quieres usar.
Por ejemplo, supongamos que tus productos hacen referencia a un metaobjeto Diseñador a través de un metacampo personalizado designer, y el metaobjeto tiene un campo country. Puedes mostrar las ventas totales agrupadas por el país del diseñador usando la siguiente consulta:
FROM sales
SHOW total_sales
GROUP BY product.metafields.custom.designer.country