Contrato semántico de gold: ¿puedes elegir qué columnas llegan al modelo Direct Lake?

Una tabla gold que parece limpia en Spark puede fallar igualmente como activo de plataforma. Los enlaces opcionales a una tabla de dimensión descartan las filas sin coincidencia. Los campos de texto libre esconden claves de negocio detrás de regex de conocimiento tribal. Las etiquetas y las carpetas se tratan como un retoque. Las partes interesadas abren un informe y falta parte de los datos sin ningún error.

Gold resulta útil cuando las claves sin coincidencia, las etiquetas y las relaciones se entregan junto con la tabla como un único contrato semántico. "Cada fila de origen visible, coincida o no" es una prueba de aceptación, no un eslogan.

Figura 1. Gold como contrato semántico. El Delta curado es necesario. Los miembros desconocidos, los puentes, las relaciones y los nombres pensados para personas lo convierten en un activo de plataforma.

Contexto y restricción

Un fallo habitual: los recuentos de filas del lakehouse cuadran y aun así hay páginas de informe que aparecen vacías para porciones enteras de los datos. El hecho existe. El contrato sobre los miembros sin coincidencia y el comportamiento de las relaciones, no.

Un enlace opcional a una tabla de dimensión debe hacer visibles los desconocidos, no filtrarlos en silencio. Las claves de negocio extraídas de texto libre son decisiones de modelado con pruebas. Las etiquetas por referencia cultural y las carpetas de consulta son infraestructura de usabilidad. Trátalas como parte de la misma publicación que la escritura en gold.

La figura 2 es la página de Learn sobre las relaciones del modelo. Las claves y el comportamiento de las relaciones son el contrato en el que puede confiar el modelo Direct Lake, no un retoque para después.

Figura 2. Gold solo se convierte en activo de plataforma cuando las claves y las relaciones se comportan como un contrato semántico en el que el modelo puede confiar. Fuente: Microsoft Learn: understand relationships.

La figura 3 explica por qué un SQL endpoint sano no equivale a aceptación. Los recuentos de filas pueden parecer correctos mientras los informes esconden claves sin coincidencia.

Figura 3. Los recuentos de filas en el SQL endpoint pueden parecer sanos mientras los informes esconden claves sin coincidencia. Prueba el contrato, no solo que Spark termine bien. Fuente: Microsoft Learn: lakehouse SQL analytics endpoint.

Diseño

1. Los miembros desconocidos ganan a los descartes silenciosos

Los left joins que filtran lo que no coincide hacen que los dashboards parezcan fiables y estén incompletos. Conserva cada fila de origen. Añade miembros desconocidos o sin coincidencia en las tablas de dimensión y puente para que los totales cuadren con el recuento de origen en el que cree la gente. Documenta qué significa "desconocido" para que nadie lo elimine en un PR posterior. La figura 4 es la bifurcación entre el descarte silencioso y los desconocidos de primera clase.

Figura 4. Los miembros desconocidos ganan a los descartes silenciosos. "Solo coincidencias" es un filtro explícito del informe, no la granularidad por defecto de gold.

2. Las claves de negocio parseadas son una decisión de modelado

Si los identificadores de negocio viven en campos de texto libre, las reglas de parseo van en gold con fixtures, no en el DAX de quien hace el informe ni en una celda suelta de un notebook. Versiona las reglas. Cuando cambie el formato del texto en el origen, querrás un único sitio que arreglar y volver a probar, no cinco visuales que adivinaron cada uno a su manera.

3. La granularidad, las claves puente y las relaciones TMDL se entregan juntas

Publica la declaración de granularidad (¿una fila por clave por qué?), las claves puente hacia las tablas de dimensión y las relaciones de TMDL o del modelo en el mismo conjunto de cambios. Una tabla gold sin las relaciones actualizadas es una mina para el siguiente refresco semántico. Las dimensiones con varios roles necesitan tipos de clave que coincidan; si no, tendrás visuales vacíos que parecen bugs de DAX. La figura 5 es esa entrega en un único conjunto de cambios.

Figura 5. La granularidad, los puentes y las etiquetas se entregan juntos. Si alguna respuesta es "más adelante", el PR es una tabla soltada sin más, no un activo de plataforma.

4. Las etiquetas y las carpetas de consulta son parte de la entrega

Los nombres de campo que tienen sentido para los ingenieros fracasan en la lista de campos de los analistas. Las etiquetas por referencia cultural, las descripciones y la agrupación en carpetas reducen las consultas a soporte del tipo "¿dónde está la clave?". No es decoración. Es la forma en que se consume el contrato semántico.

5. Aceptación de las partes interesadas: cada fila visible, coincida o no

Escribe la prueba: el número de filas de origen en gold es igual al número alcanzable en el modelo por la ruta por defecto, incluidas las que no coinciden. Comprueba por muestreo los huérfanos conocidos. Si a los product owners les importa que aparezcan todas las filas, automatiza esa comprobación antes de discutir los colores del dashboard.

6. Comparte la lógica de enriquecimiento

Si la tabla de hechos A y la tabla de hechos B resuelven claves contra la misma tabla de dimensión, comparte el módulo de coincidencia. Una lógica de coincidencia divergente produce dos verdades que reclaman a la vez el estatus de gold.

Miembros desconocidos en la práctica

Espera resistencia la primera vez que aparezcan miembros desconocidos en un segmentador. Esa resistencia es útil. Obliga a hablar de calidad de datos frente a exclusión silenciosa. Enseña a filtrar "solo coincidencias" como una decisión explícita del informe, no como la granularidad por defecto de gold. Gold dice la verdad sobre la cobertura. Los informes pueden acotar. No pueden fingir que el lake nunca vio los huérfanos.

Cómo reviso un PR de gold

Antes del merge hago cuatro preguntas. ¿Sobrevive cada fila de origen al enlace opcional con la dimensión? ¿Están cubiertas por fixtures las reglas de parseo de las claves de negocio? ¿Coinciden las relaciones TMDL y los tipos de clave con la granularidad de gold en el mismo conjunto de cambios? ¿Hay etiquetas y carpetas para los campos que los analistas buscarán primero? Si alguna respuesta es "más adelante", el PR es una tabla soltada sin más, no un activo de plataforma. "Más adelante" rara vez llega antes del primer ticket por un visual vacío.

Errores comunes

La comodidad del inner join. Las filas sin coincidencia desaparecen. La dirección cree que la cobertura es completa.

Regex como afición. Cada notebook se inventa un parseo de claves ligeramente distinto.

Gold fusionado, relaciones del modelo obsoletas. El refresco termina bien. Los visuales, vacíos.

Nombres técnicos solo en inglés en la lista de campos. La adopción muere en silencio.

Aceptar capturas de informes como prueba. Las capturas esconden los miembros que faltan.

Reglas de coincidencia distintas en cada hecho. Los recuentos de filas no cuadran entre páginas.

Úsalo tal cual o adáptalo

Úsalo tal cual

• Gold conserva las filas sin coincidencia; los miembros desconocidos son de primera clase.
• Las reglas de parseo de las claves de negocio viven en gold con pruebas de fixtures.
• La granularidad, las claves puente y las relaciones semánticas se publican juntas.
• Las etiquetas, las descripciones y las carpetas de consulta son obligatorias para publicar.
• La aceptación exige que cada fila de origen sea visible, coincida o no con la dimensión.
• La lógica de coincidencia se comparte entre las tablas de hechos.

Adáptalo antes de usarlo

Los miembros desconocidos inflan algunos visuales hasta que se enseña a usar los filtros. Enseñarlo sale más barato que un recuento a la baja silencioso. Las reglas de parseo explícitas implican gestión del cambio cuando cambia el texto de origen; las ocultas implican una deriva silenciosa. Entregar etiquetas y TMDL junto con gold ralentiza un poco el PR de datos y ahorra una semana de idas y vueltas semánticas. Los módulos de enriquecimiento compartidos exigen disciplina de paquetes entre notebooks. Merece la pena cuando dos hechos tienen que coincidir.

Referencias principales: Microsoft Learn sobre semantic models in Fabric, understand relationships y los flujos de TMDL que tu equipo ya usa para el modelo como código.

Cuando revises un pull request que solo añade una tabla gold, pide su complemento semántico: el comportamiento de los miembros desconocidos, el diff de relaciones y la cobertura de etiquetas. Si todo eso queda para después, la tabla todavía no es un activo de plataforma. Es una copia del origen esperando a un incidente futuro.

Si las filas sin coincidencia desaparecen, las claves son conocimiento tribal y las etiquetas quedan para más adelante, has entregado una tabla. Entrega el contrato: desconocidos, puentes, relaciones y nombres pensados para personas, a la vez que gold.

Relacionado

• MLV + SCD2: ¿es SCD2 en bronze el patrón correcto antes de las MLV de silver? (el historial de atributos y las relaciones as-of como una sola especificación)
• Remodelar hechos: ¿dimensiones compartidas o hechos separados para modelos más limpios? (claves puente antes de los informes de muchos a muchos)