Ingesta de datos en el almacenamiento mediante BCP API (versión preliminar)

Esto se aplica a:✅ Almacén en Microsoft Fabric

La API de BCP proporciona una vía directa de ingestión desde el cliente para cargar datos en Warehouse sin necesidad de usar archivos provisionales en almacenamiento externo.

Importante

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

La herramienta BCP (utilidad bcp), la clase de .NET SqlBulkCopy y la clase de Java SQLServerBulkCopy son métodos consolidados de ingesta utilizados en las cargas de trabajo de SQL Server, Azure SQL y grupos de SQL dedicados de Azure Synapse. Estas interfaces utilizan la API BCP y el protocolo de carga masiva de TDS, que normalmente es más eficiente que las instrucciones fila por fila INSERT para la ingestión de grandes volúmenes.

Importante

Para obtener el mayor rendimiento de ingesta en escenarios de producción en los que puede almacenar provisionalmente los archivos primero, use COPY INTO.

Use la API de BCP cuando los datos ya estén en el nivel de cliente o aplicación y necesite la ingesta directa en tablas de almacenamiento a través de una conexión SQL.

Cuándo usar la API de BCP

Use BCP API para escenarios de ingesta directa, como:

  • Servicios de aplicación que mantienen los datos en memoria y escriben en lotes.
  • Scripts operativos y runbooks que cargan archivos a través de la automatización de la línea de comandos.
  • Herramientas de integración de datos que utilizan la semántica de copia masiva de SQL.
  • Herramientas cliente existentes o integraciones que ya utilizan la semántica de la API BCP y que no pueden refactorizarse para seguir un patrón de COPY INTO staging.
  • Cargas de trabajo con procesamiento por microlotes en las que los clientes envían pequeños lotes frecuentes directamente a través de la conexión SQL del almacén de datos.

Prerequisites

  • Use la autenticación de Microsoft Entra ID. La autenticación de SQL (nombre de usuario y contraseña) no se admite en Warehouse.

Opción 1: Uso de bcp.exe para la ingesta basada en scripts

Use la utilidad bcp cuando necesite la ingesta de línea de comandos repetible desde scripts, trabajos programados o runbooks. Esta opción es una buena opción para las importaciones basadas en archivos en las que desea un control explícito sobre delimitadores, codificación, tamaño de lote y salida de error.

Esta opción también se recomienda cuando los archivos de origen se crearon bcp ... out a partir de SQL Server, Azure SQL o puntos de conexión SQL similares y desea conservar las convenciones de archivos de copia masiva compatibles.

Flujo típico:

  1. Prepare una tabla de destino en el almacén.
  2. Prepare un archivo de origen (por ejemplo CSV) con el orden de columna que coincida con el destino o use un archivo de formato.
  3. Ejecute bcp ... in con el extremo SQL de su almacén y su base de datos.
  4. Ajuste las opciones, como el tamaño del lote y los delimitadores en función del tamaño y el formato del archivo.

Ejemplo:

bcp dbo.Sales in sales.csv -S <workspace-endpoint> -d <database> -G -U <user@domain.com> -c -t ,

Opciones útiles de la documentación de bcp:

  • -S establece el punto de conexión SQL o la cadena de conexión del almacén.
  • -d establece la base de datos de destino.
  • -G usa la autenticación de Microsoft Entra. Esta es la única opción de autenticación admitida para este escenario de versión preliminar.
  • -U especifica el nombre de usuario principal de Microsoft Entra para los patrones de inicio de sesión interactivo.
  • -c usa el formato de datos de caracteres.
  • -t establece el terminador de campo (, en este ejemplo).
  • -b puede establecer el tamaño del lote para cargas grandes.

Para obtener una sintaxis completa y opciones específicas de la plataforma, consulte Bulk Copy with bcp Utility (Copia masiva con la utilidad bcp).

Opción 2: Usar SqlBulkCopy de C#

Use Microsoft. Data.SqlClient.SqlBulkCopy para .NET servicios y aplicaciones que ya contienen datos en memoria (por ejemplo, DataTable o DbDataReader). SqlBulkCopy transmite filas de forma eficaz a una tabla de destino a través de una conexión SQL. Es una opción mejor que emitir muchas declaraciones individuales INSERT .

Flujo típico:

  1. Abra una conexión SQL con la cadena de conexión del almacén mediante la autenticación de Microsoft Entra.
  2. Cree una SqlBulkCopy instancia y establezca DestinationTableName.
  3. (Opcional) Añada asignaciones de columnas si los nombres de las columnas de origen y destino o su orden son distintos.
  4. Establezca propiedades relacionadas con el rendimiento, como BatchSize y BulkCopyTimeout.
  5. Llame a WriteToServer o a WriteToServerAsync para cargar el lote.

Ejemplo:

using Microsoft.Data.SqlClient;

using var connection = new SqlConnection(connectionString);
await connection.OpenAsync();

using var bulk = new SqlBulkCopy(connection);
bulk.DestinationTableName = "dbo.Sales";
await bulk.WriteToServerAsync(dataTable);

Entre las opciones de ajuste habituales se incluyen BatchSize, BulkCopyTimeout y las asignaciones explícitas de columnas cuando los esquemas de origen y de destino difieren.

Opción 3: Usar Java SQLServerBulkCopy

Use SQLServerBulkCopy en servicios de Java que incorporan datos de orígenes JDBC o flujos de datos en memoria. Proporciona un comportamiento de carga masiva similar a bcp.exe, pero directamente en el código de la aplicación.

Flujo típico:

  1. Abra una conexión JDBC con la cadena de conexión del almacén usando la autenticación de Microsoft Entra.
  2. Cree una SQLServerBulkCopy instancia y establezca setDestinationTableName.
  3. (Opcional) Configure SQLServerBulkCopyOptions y las asignaciones de columnas.
  4. Proporcione los datos de origen como ResultSet, RowSeto ISQLServerBulkRecord.
  5. Llame writeToServer a para ingerir datos.

Ejemplo:

try (SQLServerBulkCopy bulkCopy = new SQLServerBulkCopy(connectionString)) {
    bulkCopy.setDestinationTableName("dbo.Sales");
    bulkCopy.writeToServer(resultSet);
}

La API de copia masiva de JDBC admite la escritura desde los orígenes ResultSet, RowSet y ISQLServerBulkRecord.

Comentarios sobre la compatibilidad con la opción de copia masiva

En esta sección se explica cómo se comportan las opciones comunes de copia masiva en Fabric Data Warehouse. Los nombres de las opciones se corresponden con la configuración de .NET SqlBulkCopyOptions, Java SQLServerBulkCopyOptions y las sugerencias relacionadas de carga masiva de bcp.

Opciones no aplicables

Las API de cliente comunes aceptan las siguientes opciones, pero la copia masiva en Fabric Data Warehouse las omite y usa el comportamiento predeterminado del servicio:

  • CheckConstraints
  • TableLock
  • KeepNulls
  • FireTriggers

Consideraciones sobre el rendimiento

El rendimiento de la copia masiva depende en gran medida del tamaño de los lotes y de la calidad de la conexión de red del cliente para la carga.

Tamaño de lote

El tamaño del lote tiene un impacto importante en el rendimiento. Cada lote tiene una sobrecarga de procesamiento fija, por lo que el envío de lotes muy pequeños (por ejemplo, decenas o cientos de filas) puede reducir significativamente el rendimiento al cargar grandes conjuntos de datos.

Para cargas más grandes, use lotes más grandes. Un objetivo práctico se sitúa aproximadamente entre 150 MB y 1 GB por lote.

Un buen punto de partida para muchas cargas de trabajo es de 250 MB a 500 MB por lote y, a continuación, ajuste en función de los límites de rendimiento y memoria del cliente.

Calidad de la conexión de subida del cliente

La copia masiva transmite datos del cliente al extremo del almacén de datos. Si el ancho de banda de subida es limitado o la latencia de red es alta, el rendimiento de ingesta puede disminuir incluso cuando los recursos del almacén de datos están disponibles.

Para obtener el mejor rendimiento, ejecute la aplicación cliente en la misma región de Azure que el almacenamiento y use una ruta de acceso de red de baja latencia y ancho de banda alto.

API de BCP en comparación con COPY INTO

  • Use la API de BCP cuando se generan o mantienen datos en el nivel de cliente o aplicación y se requiere la ingesta directa.
  • Use COPY INTO cuando pueda almacenar provisionalmente archivos en el almacenamiento y desee la ruta de acceso del lado servidor principal para la ingesta de mayor rendimiento.

Contenido relacionado

  • Last updated on