La consulta de cubo#

La consulta de cubo es el cuerpo JSON que se envía a la API de consulta y que usa también el servidor MCP. Describe lo mismo que se elige en el visor del cubo: qué dimensiones van en filas y columnas, qué métricas se calculan y con qué segmentación. Esta página es su referencia, con las ampliaciones que solo existen en la API: comparar periodos, métricas calculadas, consultas compuestas y las demás.

Antes de empezar#

Lea antes el recorrido de la API de consulta. Todos los identificadores (de dimensiones, métricas, listas y tablas) salen del catálogo de la conexión: en los ejemplos son inventados.

La forma básica#

{
  "rows": [
    { "dimension": 310, "dateLevel": "YEAR", "sort": { "by": "CODE" } },
    { "dimension": 305, "sort": { "by": "RANKING", "metric": 0, "descending": true },
      "filter": { "mode": "FIRST_N", "count": 5 } }
  ],
  "columns": [],
  "metrics": [ { "metric": 1201 }, { "metric": 1201, "display": "PERCENT_OF_TOTAL" } ],
  "segmentation": { "root": { "type": "group", "logic": "AND", "children": [
    { "type": "condition", "dimension": 305, "operator": "IN",
      "values": [ { "type": "literal", "value": "N" }, { "type": "literal", "value": "C" } ] } ] } },
  "totals": false
}

Esta consulta pide el importe total y su porcentaje sobre el total, por año y, dentro de cada año, de las cinco zonas que más facturan, solo con las zonas Norte y Centro.

Campo	Qué es
`rows`, `columns`	Las dimensiones de los ejes, en orden (abajo). La salida es siempre larga; las columnas importan para los porcentajes por fila o columna y para los acumulados.
`metrics`	Las métricas, por su `id`, con su visualización.
`segmentation`	Los filtros que se aplican en la base de datos, antes de agregar.
`totals`	`true` añade las filas de total y subtotal.
`listing`	`true` pide un listado: una fila por registro, sin métricas (solo `rows`).
`from`	Un documento de partida (abajo).
`comparison`, `parts`, `order`	Las ampliaciones: comparar periodos, consultas compuestas y el orden de la salida.

Límites: como mucho 20 dimensiones y 50 métricas. Las reglas del cubo se comprueban al recibir la consulta: al menos una métrica (salvo en un listado), cada dimensión en un solo eje, los rankings sobre una métrica de la lista… Lo que no las cumple es 400 INVALID_QUERY con el problema.

Un campo de un eje#

Campo	Valores	Qué hace
`dimension`	Un `id` del catálogo	La dimensión
`dateLevel`	`YEAR`, `SEMESTER`, `QUARTER`, `MONTH`, `WEEK`	Agrupa una dimensión de fecha a ese nivel
`showTotals`	`true` (por defecto) o `false`	Si lleva subtotal con `totals: true`
`sort`	`{ "by": "LABEL" }` (por defecto), `CODE`, `NONE` o `RANKING` con `metric` (posición en `metrics`, desde 0) y `descending`	El orden de sus miembros
`filter`	`FIRST_N` o `LAST_N` con `count`; `SELECTION` con `keys`; `FROM_DATE`, `TO_DATE` o `BETWEEN_DATES`	Un filtro en memoria, después de calcular, como el del visor

Una métrica#

Campo	Qué hace
`metric`	El `id` de la métrica. En su lugar puede ir `formula` o `aggregate` (abajo).
`display`	La visualización: `VALUE` (por defecto), `PERCENT_OF_TOTAL`, `PERCENT_OF_ROW`, `PERCENT_OF_COLUMN`, `PERCENT_OF_GROUP` y `PERCENT_OF_GROUP_TOTAL` (con `groupDimension`), `CUMULATIVE_ROWS` y `CUMULATIVE_COLUMNS` (acumulados), `CUMULATIVE_PERCENT_ROWS` y `CUMULATIVE_PERCENT_COLUMNS` (% acumulado) y `MOVING_AVERAGE_ROWS` y `MOVING_AVERAGE_COLUMNS` (media móvil, con `period`).
`groupDimension`	La dimensión de grupo de los porcentajes y acumulados de grupo.
`totalType`	Cómo se calcula su total: `NONE`, `SUM`, `COUNT`, `AVG`, `WEIGHTED_AVG`, `MIN`, `MAX`, `CALCULATED` (recalcula la expresión sobre los totales), `INCREASE_ROWS` o `INCREASE_COLUMNS` (% de incremento entre el primer y el último valor).
`period`	Las líneas de una media móvil, de 1 a 1000.
`name`, `format`	El nombre de la columna y su máscara, como al renombrar en el visor.

Los porcentajes se dan de 0 a 100 y se calculan sobre las filas de la consulta, después de la segmentación y de los universos.

La segmentación#

segmentation.root es un árbol de grupos ("type": "group", con logic AND, OR, NOT_AND o NOT_OR, y NOT_EXISTS, abajo) y condiciones. Es el mismo modelo del editor de segmentaciones de la aplicación.

Condición sobre una dimensión:

{ "type": "condition", "dimension": 310, "operator": "BETWEEN",
  "ranges": [ { "from": { "type": "literal", "value": "2025-01-01" },
                "to":   { "type": "literal", "value": "2025-12-31" } } ] }

operator: EQUAL, NOT_EQUAL, GREATER, LESS, GREATER_OR_EQUAL, LESS_OR_EQUAL, LIKE, NOT_LIKE, IN, NOT_IN, BETWEEN, NOT_BETWEEN, IS_NULL e IS_NOT_NULL.
Valores: literal (un texto, un número con punto decimal o una fecha ISO), tuple (los códigos de una dimensión de clave compuesta, codeLength mayor que 1) o dynamicDate, una fecha relativa: { "type": "dynamicDate", "anchor": "START_OF_YEAR", "offset": -1, "offsetUnit": "YEARS" }. Los anclajes son START_OF_ y END_OF_ con YEAR, SEMESTER, QUARTER, MONTH, WEEK y DAY, y NOW; las unidades, YEARS, MONTHS, WEEKS, DAYS, HOURS, MINUTES y SECONDS.
Los códigos de una lookup salen de los miembros de la dimensión: no los invente.

Una lista incluye o excluye los registros de una lista del catálogo: { "type": "list", "factTable": 2, "list": 7, "include": true }.

Una condición sobre una métrica filtra las filas ya agregadas (cada combinación de los ejes), no los registros: es el HAVING del editor.

{ "type": "metricCondition", "metric": 1201, "operator": "GREATER",
  "values": [ { "type": "literal", "value": "1000" } ] }

Admite números, sin LIKE; va con Y al resto de la segmentación, y su métrica tiene que ser de la tabla de la primera métrica de la consulta. Un listado no las admite.

Una agrupación se usa como cualquier dimensión, con los códigos de sus divisiones como literales ("value": "1") y solo con EQUAL, NOT_EQUAL, IN y NOT_IN.

Consejo

Segmentación y filtro no son lo mismo. La segmentación filtra en la base de datos y cambia los totales; el filter de un campo (primeros N, selección, fechas) se aplica después de calcular, como en el visor.

Partir de un documento (`from`)#

{ "from": { "workbook": "5b0e…", "document": "c1f7…", "bookmark": "9a2d…" },
  "rows": [ { "dimension": 310, "dateLevel": "YEAR" } ],
  "segmentation": { "root": { "type": "group", "logic": "AND", "children": [ … ] } } }

La consulta de partida es la del documento (los identificadores salen de GET /workbooks), restringida a lo que ve el titular y recortada a sus datos. Lo que trae la petición la cambia así:

rows, columns y metrics, si no están vacías, sustituyen a las del documento.
segmentation se añade con Y a la de la sección del documento y a la del marcador.
El documento tiene que ser de la conexión de la ruta; uno que no existe o que el titular no puede abrir es 404 NOT_FOUND.
Lo que el documento usa y el titular no ve se quita y se cuenta en hidden. Validar devuelve además normalized: la consulta ya junta con la del documento.

Las ampliaciones de la consulta#

Estas ampliaciones calculan en ECenter lo que no está en el catálogo. Algunas existen también en el visor del cubo (el % acumulado, la media móvil, la semana y las métricas calculadas); otras, como comparar periodos o las consultas compuestas, solo en la API y en el servidor MCP.

Comparar periodos (`comparison`)#

El valor de cada métrica en un periodo actual y en uno de referencia, con la diferencia y el % de variación, por las dimensiones de la consulta: «este año frente al mismo periodo del año pasado, por zona».

{ "rows": [ { "dimension": 305 } ],
  "metrics": [ { "metric": 1201 } ],
  "comparison": {
    "dimension": 310,
    "current": { "from": { "type": "dynamicDate", "anchor": "START_OF_YEAR", "offset": 0, "offsetUnit": "YEARS" },
                 "to":   { "type": "dynamicDate", "anchor": "END_OF_DAY", "offset": 0, "offsetUnit": "DAYS" } },
    "reference": { "shift": "PREVIOUS_YEAR" },
    "show": [ "CURRENT", "REFERENCE", "DIFFERENCE", "PERCENT_CHANGE" ] },
  "order": { "metric": 0, "show": "PERCENT_CHANGE", "descending": true, "limit": 5 } }

Campo	Qué es
`dimension`	Una dimensión de fecha que el titular ve.
`current`	El periodo actual: `from` y `to`, los dos incluidos, con fechas ISO o fechas dinámicas.
`reference`	El de referencia: `from` y `to`, o `shift`: `PREVIOUS_YEAR` (doce meses antes) o `PREVIOUS_PERIOD` (la misma duración justo antes).
`show`	Las columnas de cada métrica, en ese orden: `CURRENT`, `REFERENCE`, `DIFFERENCE` (actual menos referencia) y `PERCENT_CHANGE`. Sin él, las cuatro.

Reglas:

Se calcula como dos consultas, una por periodo, y se juntan por los miembros. Una fila que solo está en un periodo lleva vacío el otro, y vacías la diferencia y el %. El % queda vacío si la referencia es 0.
Sin rankings ni primeros N en los ejes: se ordena y se limita con order. Las métricas, con su valor (display VALUE).
La dimensión de fecha de la comparación puede ir en un eje solo a nivel SEMESTER, QUARTER o MONTH («por mes, 2026 frente a 2025»).
No admite listing ni parts.
Las columnas se llaman «Importe total (periodo actual)», «(periodo de referencia)», «(diferencia)» y «(% de variación)», y llevan el campo comparison.
La explicación dice los dos periodos en fechas: «… del 01/01/2026 al 15/10/2026 frente al del 01/01/2025 al 15/10/2025».

Métricas calculadas (`formula`)#

Una métrica que no existe en el catálogo, calculada con otras: «importe medio por cliente», «% de incidencias abiertas».

"metrics": [
  { "metric": 1201 },
  { "formula": "{M:1201} / {M:1210}", "name": "Importe medio por cliente", "format": "#.##0,00" } ]

La fórmula usa {M:<id>} de métricas del catálogo, + - * /, paréntesis, números con punto decimal y LEVEL({M:<id>}, n). No puede citar otra métrica calculada.
Se evalúa celda a celda y, en los totales, sobre los totales. Una división por cero deja la celda vacía.
Las métricas que cita y la consulta no pide se calculan sin verse, pero cuentan como pedidas: si alguna está oculta, 403 COLUMNS_HIDDEN. Tienen que poder ir juntas (metricTables del catálogo).
Sin name, la columna se llama como la fórmula con los nombres de sus métricas; sin format, #.##0,00.

Agregación de una dimensión (`aggregate`)#

La suma, la media, el mínimo o el máximo de una dimensión numérica: «la edad media de los clientes».

{ "aggregate": { "dimension": 455, "function": "AVG" }, "name": "Edad media" }

function: SUM, AVG, MIN o MAX.
La dimensión tiene que ser numérica (NUMERIC), visible, y no ser lookup, agrupación ni un nivel de fecha.
Sin name, la columna se llama «Edad (media)», «(suma)», «(mínimo)» o «(máximo)». Solo en la API y el MCP.

La semana (`WEEK`)#

"dateLevel": "WEEK" agrupa por la semana ISO con su año: código 202641, etiqueta 2026-W41. A diferencia del semestre, el trimestre o el mes, no junta años distintos. «Las últimas 12 semanas» es la fecha a nivel WEEK en un eje y la condición fecha ≥ { "type": "dynamicDate", "anchor": "START_OF_WEEK", "offset": -11, "offsetUnit": "WEEKS" }.

% acumulado y media móvil#

{ "metric": 1201, "display": "CUMULATIVE_PERCENT_ROWS" }
{ "metric": 1201, "display": "MOVING_AVERAGE_ROWS", "period": 3 }

El % acumulado (el Pareto) es el acumulado en % del total de su grupo. Tiene sentido con la dimensión ordenada por la métrica de mayor a menor.
La media móvil promedia las period líneas anteriores de su grupo, incluida la de la celda. Sin period, 400.
Las dos admiten groupDimension y la variante _COLUMNS, hacia la derecha.

«Sin registros» (`NOT_EXISTS`)#

«Los clientes que no han comprado en 2026»: un grupo de la segmentación que exige que ningún registro de una tabla cumpla sus condiciones.

{ "type": "group", "logic": "NOT_EXISTS", "factTable": 2, "children": [
    { "type": "condition", "dimension": 310, "operator": "GREATER_OR_EQUAL",
      "values": [ { "type": "literal", "value": "2026-01-01" } ] } ] }

Las condiciones hijas se unen con Y; sin hijas, «ningún registro».
La tabla tiene que ser una tabla de detalle de la consulta (su camino desde las tablas de la consulta baja al lado «varios» de una relación). Si no, 400 INVALID_QUERY.
No es lo mismo que negar un grupo, que pide «algún registro que no cumpla».

Consulta compuesta (`parts`)#

Métricas de tablas de hechos que no se combinan, juntas por una dimensión común: «ventas frente a objetivo por comercial».

{ "parts": [
    { "rows": [ { "dimension": 412 } ], "metrics": [ { "metric": 1201 } ] },
    { "rows": [ { "dimension": 530 } ], "metrics": [ { "metric": 1301 } ] } ],
  "metrics": [ { "formula": "{M:1201} * 100 / {M:1301}", "name": "Cumplimiento (%)", "format": "0,00" } ],
  "totals": true,
  "order": { "metric": 2, "descending": false, "limit": 10 } }

De 2 a 4 partes. Cada una es una consulta con sus ejes, sus métricas y su segmentación (y, si quiere, su from), sin rankings ni primeros N, y con el mismo número de dimensiones en filas y en columnas que las demás. Una métrica va en una sola parte.
La dimensión i de cada parte se empareja con la i de la primera por el código de sus miembros: la misma dimensión o dos con la misma lookupTable del catálogo, con el mismo nivel de fecha.
Arriba solo van metrics (solo fórmulas sobre las métricas de las partes, sin LEVEL), totals y order.
Las filas son la unión: primero las de la primera parte; a una fila que solo está en una parte le faltan las métricas de las demás. Las columnas de cada parte llevan queryPart (desde 0).

El orden de la salida (`order`)#

Solo con comparison o parts: ordena las filas de datos de la salida entera y deja las primeras.

Campo	Qué es
`metric`	La posición de la métrica en la salida, desde 0. Con partes: las de la primera parte, las de la segunda… y al final las calculadas.
`show`	Con una comparación, la columna por la que se ordena (`CURRENT` si falta).
`descending`	De mayor a menor.
`limit`	Las filas que se dejan, de 1 a 10 000.

Las filas vacías van al final y las de total no cambian: van detrás de las de datos.

La salida#

Cada dimensión da una columna CODE por columna de su clave (que vale tal cual en una condición) y, si es lookup, otra LABEL con su descripción. Cada métrica da una columna METRIC con su valor sin formato y su máscara en format. Las ampliaciones añaden a sus columnas period, formula, aggregate, comparison o queryPart. Los tipos son NUMBER, TEXT, DATE, DATETIME, BOOLEAN e IDS; las fechas, en ISO 8601. Los formatos de descarga se explican en Resultados, límites y errores.

La consulta de cubo#

Antes de empezar#

La forma básica#

Un campo de un eje#

Una métrica#

La segmentación#

Partir de un documento (from)#

Las ampliaciones de la consulta#

Comparar periodos (comparison)#

Métricas calculadas (formula)#

Agregación de una dimensión (aggregate)#

La semana (WEEK)#