Cómo escribir elementos maestros para que Cub AI los entienda mejor

Guía para quienes construyen aplicaciones Qlik Sense en una organización que usa Lupa CuboPlus.

El asistente lee lo que su equipo ya escribe en Qlik. Escribir bien los elementos maestros no sirve solo para Cub AI: sirve para el colega que abra la aplicación dentro de un año. La diferencia es que ahora hay un segundo lector, y este obedece lo que está escrito.

Verificado contra el código del producto el 11/09/2026. Lo que este documento dice que se lee, se lee; lo que dice que no, no. Versión de la guía: v1, del 12/09/2026. Es una guía técnica para el equipo de BI, y no un documento legal; los documentos jurídicamente vinculantes son los Términos de uso y el Aviso de privacidad. Sobre el portugués en esta guía. Los ejemplos vienen de aplicaciones escritas en portugués, y se mantienen exactamente como aparecen en Qlik, con el significado al lado. El asistente lee descripciones en cualquier idioma. La única excepción es el marcador NÃO USAR (sección 2), que siempre se escribe en portugués.

Lo que Cub AI lee hoy

La descripción de la hoja empezó a leerse el 11/09/2026. Hasta entonces, solo el título llegaba al asistente.

1. Título: el nombre con el que la persona pregunta

El asistente elige entre las medidas por el título antes de mirar la expresión. Un buen título es lo que una persona de negocio diría en voz alta.

Los títulos están en portugués, como las aplicaciones de donde vienen, y también la convención de abreviaturas: viene de la guía de desarrollo de Cubotimize, y el diagnóstico evalúa los títulos según ella (sección 7).

Reglas prácticas:

• use la convención de abreviaturas de la guía de desarrollo, y solo esa: Vlr. (valor), Qtd. (quantidade, cantidad), Vol. (volumen), Ind. (indicador), % o Perc. (percentual, porcentaje), Cód. (código), Desc. (descrição, descripción) y Ref. (referência, referencia). Existen para que el título quepa en el tablero;
• Ref. va al final del nombre, porque califica lo que viene antes: Ano Ref., Competência Ref. (período de devengo de referencia). El diagnóstico evalúa la posición: Ref. Ano pierde puntos, y la lista descargada dice que la abreviatura solo vale al final;
• lo que está fuera de la convención se escribe completo: Inadimplência (mora), y no Inad.;
• sin preposición en el título, también para que quepa en el tablero: Custo Médio Atendimento (costo promedio por atención, sin el "de" del portugués);
• en singular, en campo, dimensión y medida: Qtd. Beneficiário Ativo, y no Qtd. Beneficiários Ativos. El plural es raro, y queda para el elemento que solo tiene sentido así;
• con tildes, con Mayúscula Inicial En Cada Palabra;
• ponga la unidad en el nombre cuando no sea obvia: Prazo Médio (dias) (plazo promedio, en días), Receita (R$ mil) (ingresos, en miles de reales);
• si existen dos versiones de lo mismo, diga en el título cuál es cuál: Custo Ajustado (costo ajustado) y Custo Bruto (conferência) (costo bruto, para conciliación). Sin eso el asistente elige por la descripción, y si no hay descripción elige por el nombre más parecido a la pregunta, que es una suposición con cara de respuesta.

⚠️ La descripción es donde el título abreviado se explica. Un título corto es bueno para el tablero y peor para quien pregunta por "valor de inadimplência" (valor de la mora): escriba en la descripción, completo, lo que el título abrevia. La descripción es lo que el asistente lee antes de elegir, y es lo que une Vlr. Inadimplência con la pregunta de quien nunca vio la convención.

2. Descripción: donde está lo que el nombre no dice

Es el campo de mayor retorno. Es el único lugar donde puede quedar escrita la trampa de una medida, y el asistente tiene la instrucción de dar más peso a la descripción que a su propia lectura del nombre o de la expresión.

Escriba lo que un colega necesitaría saber antes de usarla:

Custo já líquido de glosa e recuperação. Fecha com o contábil a partir de mai/2025.
Grão: competência (Mês Ano Ref.), não data de pagamento.

En español: "Costo ya neto de glosas y recuperaciones. Cuadra con la contabilidad a partir de may/2025. Grano: período de devengo (Mês Ano Ref.), no fecha de pago."

Lo que vale la pena registrar, en una línea cada uno:

• el grano: por período de devengo, por fecha de pago, por evento;
• el corte: ya excluye cancelados, ya excluye intercambio (intercâmbio);
• desde cuándo es confiable: "vale a partir de may/2025";
• con qué cuadra: "cuadra con el informe contable", "no cuadra con el SIB a propósito" (el registro de beneficiarios del regulador);
• cuál es la oficial, cuando existe más de una.

⚠️ Aviso con ⚠️: el asistente se lo transmite al usuario

Cuando la descripción tenga el carácter ⚠️, o diga que algo no se debe sumar, no se debe confundir, o solo vale en cierto grano, Cub AI transmite ese aviso junto con el número. No se lo guarda.

⚠️ Não somar entre convênios: há rateio duplicado no intercâmbio.

En español: "No sumar entre convenios: hay prorrateo duplicado en el intercambio."

Quien pregunte recibirá el número y la salvedad. Y si la pregunta pide exactamente lo que la descripción desaconseja, el asistente entrega el número pedido y explica por qué engaña.

⛔ NÃO USAR: el asistente se niega

Una medida o dimensión que ya no debe usarse puede vetarse. Escriba NÃO USAR al comienzo de la descripción:

NÃO USAR
⚠️ NÃO USAR: substituída por Faturamento Líquido em jan/2026
NÃO USAR, medida antiga da carga velha
**NÃO USAR**

NÃO USAR significa "no usar" en portugués, y se escribe literalmente así, en portugués, sea cual sea el idioma de su aplicación: es el marcador que Lupa busca. Un "NO USAR" en español no veta nada; se lee como una salvedad común. En los ejemplos de arriba, el texto después del marcador dice "sustituida por Faturamento Líquido en ene/2026" y "medida antigua de la carga vieja".

El gateway de Lupa rechaza cualquier cálculo que use ese elemento, y rechaza también copiar su expresión a una fórmula nueva. El asistente le dice a la persona que ese elemento fue marcado como no utilizable por el equipo de BI, y ofrece la alternativa si la descripción indica una.

⚠️ Esto no es una instrucción al modelo, es un rechazo en el código. El modelo no puede decidir usarlo de todos modos.

Los campos que solo usa el elemento vetado salen con él. Si Receita Antiga (ingreso antiguo) es Sum(ValorAntigo) y ningún otro elemento maestro usa ValorAntigo, el gateway rechaza también cualquier fórmula nueva con ese campo, con o sin corchetes. Sin eso, bastaría con reescribir la expresión por fuera.

Un campo que usa otro elemento maestro no vetado sigue disponible, porque bloquearlo rompería ese elemento: vetar Sum({<Ano={2025}>} ValorAntigo) no saca Ano de uso si la Receita Ajustada también usa Ano. Para garantizar que un campo nunca se use, en ninguna fórmula, el camino es la lista de campos bloqueados en el panel de Lupa (sección 6).

La frontera, que es la parte en la que se falla

Não usar seguido de otra palabra es un consejo sobre un uso, no un veto al elemento:

Es a propósito. Si cualquier "não usar" en medio de una frase vetara el elemento, nadie escribiría más salvedades, y la descripción perdería justamente lo mejor que tiene.

Para vetar, empiece la descripción con NÃO USAR. Para alertar, escriba la frase completa.

Las tildes, las mayúsculas y el ⚠️ delante no importan. nao usar: funciona igual que ⚠️ NÃO USAR:.

3. Etiquetas

Las etiquetas de los elementos maestros llegan al asistente junto con el título. Sirven para agrupar lo que el nombre no agrupa:

oficial      no item que fecha com o contábil
homologacao  no que ainda está em validação
2026         no que só vale no exercício novo

En español: oficial en el elemento que cuadra con la contabilidad, homologacao (validación) en el que todavía está en validación, y 2026 en el que solo vale en el nuevo ejercicio.

Ninguna etiqueta tiene un significado especial para el producto: entran como contexto. Una etiqueta oficial ayuda al asistente a elegir entre dos medidas parecidas, pero la descripción decide, porque es ella la que explica el porqué.

Etiquetas de campo, en el script

Las etiquetas que usted aplica en el script de carga también se leen:

TAG FIELD [Mês Ano Ref.] WITH '$date', 'competencia';

El asistente usa $numeric, $date y $timestamp para saber qué se puede sumar y qué se puede comparar como período. Sus propias etiquetas, como competencia (período de devengo), entran como contexto.

4. Hojas

El título de la hoja abierta se lee y cuenta: le dice al asistente de qué trata la pantalla. Prefiera Faturamento por Convênio (facturación por convenio) a Análise 3 (análisis 3).

Los gráficos de la hoja abierta también se leen, pero solo sus definiciones: título, tipo, dimensiones y medidas usadas. Los valores no. El asistente sabe que existe un gráfico "Custo por convênio" (costo por convenio) dibujado con la medida Custo; para saber cuánto da, consulta la Engine en el momento, con el filtro que usted está viendo.

La descripción de la hoja también se lee, y es el lugar para decir el recorte que asume la pantalla:

Faturamento dos convênios empresariais, por competência (Mês Ano Ref.).
Não inclui intercâmbio.

En español: "Facturación de los convenios empresariales, por período de devengo (Mês Ano Ref.). No incluye intercambio."

Llega al asistente como aviso, igual que la descripción de un elemento maestro: el asistente la tiene en cuenta y la transmite, y nunca la trata como una orden.

5. Lo que NO se debe escribir

⚠️ La descripción no es un canal para darle órdenes al asistente. El producto trata el texto que viene de Qlik como contenido, y un texto que pida revelar la configuración, cambiar reglas o ignorar instrucciones no se envía al asistente: Lupa cambia la descripción por un aviso de omisión antes de que salga la pregunta, y la aplicación baja a Bronce en el diagnóstico hasta que se corrija el texto. No es un pedido al modelo, es una omisión en el código.

Lo que funciona es describir el dato. Lo que no funciona:

Los ejemplos están en portugués, como las aplicaciones que el producto lee. En cualquier idioma la regla es la misma: describa el dato, nunca el comportamiento del asistente.

⚠️ A dónde va el texto de la descripción. Se envía al proveedor del modelo de lenguaje, hoy Google Gemini, en cada pregunta sobre esa aplicación, y el procesamiento puede ocurrir fuera de Brasil. Por eso los datos de personas no entran en una descripción, ni siquiera como ejemplo. Los detalles están en el Aviso de privacidad.

Para que el asistente le hable de otra manera a su organización, el camino es el campo de preferencias en el panel de Lupa, y quien lo edita es Cubotimize junto con usted.

6. Campos que no deben detallarse

Los campos que identifican a una persona (número de afiliado, CPF, nombre del beneficiario, número de protocolo) pueden bloquearse en el panel de Lupa, por aplicación o para el cliente entero. Una vez bloqueado, el gateway rechaza cualquier cálculo que agrupe o muestre ese campo, incluso dentro de una expresión.

No es un límite de cantidad de valores: Município (municipio) tiene miles de valores y sigue disponible, porque no identifica a nadie. Quien sabe lo que identifica a una persona es usted, y por eso la lista es suya.

Usted define la lista; pídale a Cubotimize que la registre antes de liberar la aplicación al equipo. Es la diferencia entre "al asistente se le indicó no hacerlo" y "el sistema lo rechaza". La lista vigente puede consultarse en cualquier momento, a pedido.

7. El diagnóstico: Bronce, Plata, Oro y Diamante

Quien tiene el permiso en el panel de Lupa puede diagnosticar la aplicación abierta, desde la extensión. El diagnóstico compara la aplicación con esta guía y le da una medalla, que todos los usuarios ven en el encabezado del asistente. Diagnosticar de nuevo, después de corregir, actualiza la medalla.

No consume preguntas del paquete. La nota se calcula por reglas, sin el modelo: la misma aplicación siempre recibe la misma medalla, y cada punto perdido señala los elementos que lo perdieron.

Quien diagnostica también descarga la lista completa de los puntos a corregir, en hoja de cálculo: criterio, sección de esta guía, el elemento por su nombre y qué hacer. Y el nivel aparece en el pie de cada respuesta del asistente: es la nota de la aplicación, no de la respuesta, y sirve para sopesar cuánto tuvo que adivinar el asistente al elegir las medidas.

Las ponderaciones y los cortes de abajo son los de las reglas iniciales, y Cubotimize puede ajustarlos. Cada diagnóstico registra la versión de las reglas que lo midió.

Un criterio que no se aplica a la aplicación (sin dimensiones maestras, sin campo de fecha) queda fuera del cálculo, en lugar de contar como cero.

Los dos últimos son bonos: suman por encima de los 100, en lugar de ser parte de ellos. Una aplicación bien escrita llega a 100 sin ellos, y quien no tiene ningún campo de persona para bloquear no pierde puntos por eso.

⚠️ La orden al asistente es lo único que también lleva la medalla a Bronce, por más puntos que tenga la aplicación. Escribir una orden es un acto de quien escribió, y no la ausencia de algo que la aplicación no tiene; y el texto ni siquiera llega al asistente (sección 5). Un campo de persona sin bloqueo solo deja de sumar el bono, porque quien bloquea es Cubotimize, en el panel de Lupa: bajar la aplicación por eso sería castigarla por una decisión que no es de su equipo.

En el criterio de títulos, las abreviaturas de la convención no cuentan (Vlr., Qtd., Vol., Ind., Perc., Cód., Desc. y Ref.); cualquier otra con punto cuenta, y basta una. Ref. es la única con regla de posición: fuera del final del nombre, cuenta. En la lista descargada, cada título viene con el motivo: Qtd. Conta Inad. Vigente (abreviatura fuera de la convención: Inad.). La lista está en las reglas, y Cubotimize puede ampliarla.

Los elementos auxiliares quedan fuera. Una medida o dimensión cuyo título empieza con Alt (medida alternativa), 🎲 Dim o 📐 Med (selectores de dimensión y de medida del tablero) no entra en ningún criterio: es una pieza de la pantalla, y no algo sobre lo que alguien pregunte. El resumen del diagnóstico dice cuántos quedaron fuera. Esa lista también está en las reglas.

En masa, desde el hub. Quien puede diagnosticar también mide de una vez todas las aplicaciones publicadas que abre, en el hub de Qlik: una por vez, porque cada una se abre para leer su metadato. Al final vienen el conteo de Oro, Plata y Bronce, la lista de la peor a la mejor con dónde pierde más cada una, y la hoja de cálculo: una fila por punto a corregir, con la aplicación, el criterio y qué hacer en cada fila.

Las aplicaciones de extracción y de transformación quedan fuera. En el estándar de desarrollo, el número al frente del nombre es la capa: 1. es extracción y 2. es transformación, aplicaciones que generan QVD para las demás y que nadie consulta. No se diagnostican y no aparecen en la lista del hub ni en el selector de aplicaciones. Quien abra una de ellas en Qlik sigue teniendo el asistente. Esa lista también está en las reglas.

Para sacar una aplicación de la consulta por un tiempo, cámbiele el nombre con 0. al frente: 0. es el escalón fuera de las reglas, para una aplicación de prueba o para lo que todavía no debe aparecer. Vuelve en cuanto vuelva el nombre.

La cuenta: las ponderaciones de los cinco criterios de la base suman 100, y la nota es la ponderación por la nota de cada criterio, sumadas. Una aplicación con 100% en todos hace 100 puntos. Un criterio que no se aplica sale de la cuenta, y los demás se reajustan, sin bajar la nota.

⚠️ Los dos criterios de riesgo avisan en la ventana del diagnóstico, que es donde el riesgo tiene que leerse: una descripción que le dé órdenes al asistente (sección 5), y un campo que identifica a una persona sin bloqueo en el panel o un CPF de ejemplo en una descripción (sección 6). Quien falla en ellos pierde el bono; una orden al asistente, además, baja la medalla a bronce, como se dijo arriba.

Lo que las reglas no ven es si lo que se escribió está bien. Miden si lo que esta guía pide está ahí; la verdad de la descripción sigue siendo de su equipo.

Resumen en una página

1. Título en singular, sin preposición, con las abreviaturas de la convención y el resto completo.
2. Descripción con grano, corte, desde cuándo vale y con qué cuadra.
3. ⚠️ en la descripción cuando haya una trampa: el asistente la transmite.
4. NÃO USAR al comienzo de la descripción para vetar de una vez: el gateway lo rechaza.
5. Não usar para X en medio de la frase es un consejo, y el elemento sigue disponible.
6. Etiquetas para agrupar; la descripción es la que decide.
7. Título y descripción de hoja que digan de qué trata la pantalla y qué recorte asume.
8. Nada de órdenes al asistente en la descripción, y nada de datos de personas como ejemplo.

CuboPlus es una marca de Cubotimize. Dudas: [email protected]