Resolución de problemas de integración de Git para desarrollo de almacén

Se aplica a: ✅ Almacén en Microsoft Fabric

Este artículo incluye temas de resolución de problemas para desarrollar y desplegar Fabric Data Warehouse con la integración integrada de Git de Fabric.

Importante

Esta característica se encuentra en versión preliminar.

Referencias a los propios objetos del almacén usando un nombre en tres partes

Un objeto puede referenciar a otro objeto en el mismo almacén usando un nombre de tres partes, [warehouse_name].[schema_name].[object_name].

La denominación en tres partes está pensada para referirse a un almacén diferente . Cuando la parte de la base de datos nombra el almacén actual, la compilación trata la referencia como externa y el objeto acaba definiéndose dos veces en el modelo.

Elimina la parte de la base de datos de las referencias a los propios objetos del almacén:

-- Fails: the warehouse is named MyWarehouse and references itself by name
CREATE VIEW [Sales].[CustomerSummary] AS
SELECT c.[CustomerId], c.[OrderDate]
FROM [MyWarehouse].[Sales].[Customers] AS c;

-- Works
CREATE VIEW [Sales].[CustomerSummary] AS
SELECT c.[CustomerId], c.[OrderDate]
FROM [Sales].[Customers] AS c;

Solo las referencias a los propios objetos del almacén deben cambiar. Se soportan referencias genuinas cruzadas a bases de datos a otros almacenes, como [Other_Warehouse].[Sales].[Orders], y deben permanecer as-is.

Importante

Usa nombres en tres partes (database.schema.object) solo para referencias de endpoints de análisis cross-warehouse o cross-SQL, no para referenciar objetos dentro del mismo almacén. Autorreferenciar objetos en el mismo almacén usando nombres en tres partes no es una práctica estándar de modelado y puede crear referencias externas involuntarias.

Siempre que sea posible, modela los objetos usando nombres en dos partes (schema.object) en lugar de en tres partes, incluso para autorreferencias dentro del mismo almacén. Esta convención mejora la consistencia entre herramientas cliente y evita la ambigüedad introducida por las referencias de tres partes.

.sqlproj desactualizado en el repositorio Git

El repositorio Git puede contener un .sqlproj archivo que hace referencia a una versión anterior Microsoft.Build.Sql del SDK. El SDK antiguo no reconoce la sintaxis de Fabric Data Warehouse más reciente como IDENTITY columnas y CLUSTER BY.

Este problema afecta a los repositorios cuyos contenidos se comprometieron antes de que el almacén pasara al formato de definición actual. Las situaciones más comunes que resultan en un archivo .sqlproj desactualizado son:

  • Conectar un nuevo espacio de trabajo a un repositorio existente. El almacén se crea con lo que se realiza allí.
  • Expandirme a un nuevo espacio de trabajo.
  • Restaurando un almacén eliminado de Git.
  • Sincronización desde Git inmediatamente después de que el almacén se moviera al formato de definición actual, antes de que se haya ejecutado cualquier sincronización en la otra dirección.

Los almacenes que no se mueven al formato de definición actual no se ven afectados, porque el archivo de proyecto antiguo no se usa para construir.

Cómo confirmar la versión del SDK .sqlproj

Abre el archivo del .sqlproj almacén en el repositorio y comprueba la versión del SDK en el XML:

<Sdk Name="Microsoft.Build.Sql" Version="2.2.0" />

Una versión que va por detrás de la actual Microsoft. La versión del paquete Build.SQL indica un archivo de proyecto desactualizado. Por ejemplo, si tu versión empieza por 0.1.. Para más información, consulta Microsoft. Build.SQL y Plantillas Releases.

Actualizar la versión A del SDK .sqlproj: sincronizar primero el almacén con Git

Si el almacén ya existe en el espacio de trabajo y está en buen estado, haz commit desde el espacio de trabajo a Git antes de sincronizar en la otra dirección. Esta acción regenera el archivo del proyecto con la versión actual del SDK, tras lo cual la sincronización desde Git funciona normalmente.

Esta opción es preferida cuando está disponible, porque actualiza toda la definición en lugar de solo el atributo SDK.

El almacén debe estar ya en el formato de definición actual para que esta opción funcione. Si no lo es, actualízalo primero en el panel de Fabric Git y luego haz commit en Git. Hacer commit desde un almacén que aún está en el formato de definición antigua escribe el formato antiguo de nuevo en el repositorio y no actualiza la versión del SDK, así que la siguiente sincronización falla de la misma manera. Si no puedes actualizar, usa la opción de arreglar B en su lugar.

Actualizar la versión B del SDK .sqlproj: actualizar el archivo .sqlproj directamente en Git

Usa esta opción cuando el almacén aún no existe en el espacio de trabajo objetivo, como cuando conectas un nuevo espacio de trabajo a un repositorio existente, expandes tu ramificación o restauras un almacén eliminado. En esos casos, no hay almacén desde donde sincronizar, así que la opción de arreglo A no está disponible.

Edita el .sqlproj archivo en el repositorio para usar la última versión de Microsoft. Compila la versión del paquete Build.SQL y confirma el cambio. Por ejemplo:

<!-- Before -->
<Sdk Name="Microsoft.Build.Sql" Version="0.1.19-preview" />

<!-- After -->
<Sdk Name="Microsoft.Build.Sql" Version="2.2.0" />

Ejecutar una exportación o un diff por sí solo no actualiza el archivo del proyecto. El archivo solo se reescribe cuando se completa un commit del espacio de trabajo a Git, o cuando lo editas manualmente.

Columnas no calificadas en objetos que hacen referencia a dos o más tablas en otro almacén

Siempre proporciona y utiliza alias de tabla al referenciar columnas en consultas T-SQL.

  • Cuando una consulta T-SQL hace referencia a dos o más tablas en otro almacén, la compilación no puede validar una columna escrita sin alias de tabla a una tabla específica. Las tablas no necesitan compartir el nombre de una columna para que exista esta ambigüedad. Esta ambigüedad existe en la versión de validación.
  • Esta ambigüedad afecta a las consultas T-SQL dentro de objetos que hacen referencia a dos o más tablas en otro almacén dentro del mismo cuerpo de sentencia.
  • Esta ambigüedad no afecta a las consultas T-SQL dentro de objetos que solo hacen referencia a una tabla en otro almacén, porque con una sola fuente no hay nada entre lo que pueda ser ambiguo.
  • Esta ambigüedad no afecta a las consultas T-SQL que permanecen completamente dentro de un solo almacén.

En el siguiente ejemplo, solo fieldinfo tiene finame, por lo que el SQL es válido y se ejecuta correctamente contra el almacén, pero existe ambigüedad en la compilación de validación.

-- Fails: two tables from another warehouse, and 'finame' isn't alias-qualified
CREATE PROCEDURE [dbo].[LoadFieldInfo] AS
SELECT finame
FROM   [OtherWarehouse].[halo].[fieldinfo] AS f
INNER JOIN   [OtherWarehouse].[halo].[lookup]    AS l ON f.[id] = l.[id];

Añadir un alias de tabla a cada referencia de columna en el objeto afectado:

-- Works: every column carries its table alias
CREATE PROCEDURE [dbo].[LoadFieldInfo] AS
SELECT f.[finame]
FROM   [OtherWarehouse].[halo].[fieldinfo] AS f
INNER JOIN   [OtherWarehouse].[halo].[lookup]    AS l ON f.[id] = l.[id];

Capitalización inconsistente de los nombres de esquemas

Tu almacén puede usar una colación insensible a mayúsculas y minúsculas, así que sales y Sales son el mismo esquema, pero tus scripts pueden deletrearlo de ambas formas en diferentes lugares. Las bases de datos insensibles a mayúsculas y minúsculas siempre han aceptado eso, por lo que la inconsistencia suele ser de larga data e inofensiva.

Cuando tus scripts hacen referencia a dos o más objetos diferentes en el mismo esquema de otro almacén, y escriben ese esquema de forma distinta en cada referencia, la compilación genera una CREATE SCHEMA instrucción para cada escritura. Este problema afecta solo a almacenes que hacen referencia a otro almacén y utilizan una clasificación insensible a mayúsculas y minúsculas.

  • Por defecto, los almacenes en Fabric usan Latin1_General_100_BIN2_UTF8, una clasificación con distinción de mayúsculas y minúsculas. Los almacenes con distinción de mayúsculas minúsculas no se ven afectados. En esos almacenes, sales y Sales hay dos esquemas diferentes, lo quieras o no.
  • Una base de datos insensible a mayúsculas minúsculas no puede contener tanto sales como Sales. El duplicado proviene solo de las diferentes ortografías en tu texto SQL.

Revisa la recopilación del almacén y lo ModelCollation especificado en el .sqlproj archivo. Busca ( CI indistinto a mayúsculas) o CS (sensible a mayúsculas).

<ModelCollation>1033, CI</ModelCollation>   <!-- case-insensitive: affected -->
<ModelCollation>1033, CS</ModelCollation>   <!-- case-sensitive: not affected -->

Corregir

Para identificar una capitalización inconsistente de nombres de esquema en las definiciones de objetos de tu almacén, compara la capitalización del esquema nombrado en el error entre todos tus scripts. Busca dos referencias cross-warehouse al mismo esquema que solo difieran en caso de que exista.

Usa una mayúscula consistente en todas partes, coincidiendo con el nombre real del esquema en el almacén referenciado. Por ejemplo, usa solo Sales o solo sales.

-- Fails: two objects in the same schema, referenced with different capitalization
CREATE VIEW [dbo].[v_one] AS SELECT * FROM [OtherWarehouse].[sales].[Orders];
GO
CREATE VIEW [dbo].[v_two] AS SELECT * FROM [OtherWarehouse].[Sales].[Customers];

-- Works: same capitalization in both references
CREATE VIEW [dbo].[v_one] AS SELECT * FROM [OtherWarehouse].[Sales].[Orders];
GO
CREATE VIEW [dbo].[v_two] AS SELECT * FROM [OtherWarehouse].[Sales].[Customers];

Te encuentras con este problema cuando tienes dos objetos diferentes con dos mayúsculas de esquemas distintas. Dos referencias al mismo objeto con mayúsculas diferentes se pliegan correctamente y no fallan.

Intercalación de columnas

Si la cláusula de COLLATE una columna especifica explícitamente la misma colación que la colación predeterminada del almacén, la extracción de esquema de Fabric (basada en DacFx) considera la colación explícita como equivalente a no especificar ninguna en absoluto. En este caso:

  • La cláusula explícita COLLATE no aparece en la definición de elemento extraída del repositorio Git.
  • La columna no aparece como diferencia en los cambios de Git, actualizaciones o comparaciones de pipelines de despliegue, porque no hay diferencia efectiva respecto a la clasificación predeterminada del almacén.

Solo las columnas cuya colación difiere de la colación predeterminada del almacén conservan una cláusula explícita COLLATE en el control de versiones, y solo los cambios en la colación de esas columnas aparecen como diferencias.

Por ejemplo, consideremos un almacén cuya colación es Latin1_General_100_CI_AS_KS_WS_SC_UTF8:

CREATE TABLE dbo.MixedCollationExample
(
    CustomerId      INT             NOT NULL,
    FirstName       VARCHAR(100)    NOT NULL,                                               -- inherits warehouse collation
    LastNameBin     VARCHAR(100)    COLLATE Latin1_General_100_BIN2_UTF8 NOT NULL,          -- column override, differs from warehouse collation
    Email           VARCHAR(256)    COLLATE Latin1_General_100_CI_AS_KS_WS_SC_UTF8 NULL     -- explicit collation, matches warehouse collation
);
  • FirstName no tiene una clasificación explícita y hereda la clasificación predeterminada del almacén.
  • LastNameBin tiene una clasificación explícita que difiere de la clasificación predeterminada del almacén, por lo que se conserva en la definición extraída y siempre aparece en las comparaciones si cambia.
  • Email tiene una clasificación explícita que coincide con la clasificación predeterminada del almacén. Aunque la COLLATE cláusula está presente en T-SQL, no aparece en la definición extraída por Git ni en Git ni en comparaciones de pipelines de despliegue, porque es equivalente a la predeterminada.

Errores ambiguos en columnas con objetos candidatos duplicados

Comprometer o actualizar desde Git puede fallar con un error ambiguo en la columna cuya lista de candidatos contiene un :: separador, por ejemplo:

SQL71501: View: [dbo].[SchoolSummary] contains an unresolved reference to an object.
Either the object does not exist or the reference is ambiguous because it could refer
to any of the following objects: [dbo].[SchoolSummary].[NCESID] or
[dbo].[SchoolSummary].[ss]::[NCESID].

El :: separador distingue este error de la ambigüedad genuina descrita en columnas No calificadas en objetos que hacen referencia a dos o más tablas en otro almacén. Añadir un alias de tabla no lo resuelve, ya que el alias aparece en la lista de candidatos y el error sigue ocurriendo.

  1. Primero, descarta estas dos causas más comunes:

    • Un objeto realmente faltante o con un nombre equivocado. Si el mismo commit o actualización también informa de una referencia no resuelta a un objeto específico que falta, como SQL71501: View: [dbo].[v_report] has an unresolved reference to object [dbo].[MissingTable], corrige esa referencia primero. Los :: candidatos suelen pasar junto con ella.
    • Una columna realmente ambigua. Si se selecciona una columna no calificada sobre una unión de dos fuentes que exponen una columna con ese nombre, califique la columna con su alias de tabla, por a.[NCESID]ejemplo . SQL Server también rechazaría esta consulta, así que no es específica de la integración con Git.

  2. Si todos los objetos referenciados existen y ninguna columna es realmente ambigua, los :: candidatos son un problema conocido en la validación que se ejecuta durante los commits y actualizaciones de Git, seguida por el equipo de producto. Prueba estas soluciones alternativas, en orden:

    1. Sustituye SELECT * los CTEs internos y las tablas derivadas por una lista explícita de columnas.
    2. Divide la vista para que cada fuente ambigua esté definida en su propia vista y referencia esa vista en lugar de repetir la consulta subyacente.
    3. Evita unir OPENROWSET(BULK ...) a otra fuente dinámicamente formada en la misma afirmación.

Si ninguno de estos resuelve el error, recopila la definición del objeto nombrado en el error y abre una solicitud de soporte. Para limitaciones específicas de las canalizaciones de despliegue, véase Limitaciones.

Contenido relacionado

  • Last updated on