COPIAR EN (Transact-SQL)

Se aplica a:Azure Synapse Analytics

• Iniciar una prueba gratuita de Fabric.
• Asistente de Migración para el Almacén de Datos Fabric.

En este artículo se explica cómo usar la instrucción /> COPY declaración ofrece la mayor flexibilidad para la ingesta de datos de alto rendimiento en Azure Synapse Analytics.

Úsalo COPY para las siguientes capacidades:

• Use usuarios con privilegios inferiores para cargar datos sin necesidad de permisos estrictos de CONTROL en el almacenamiento de datos.
• Ejecute una instrucción T-SQL única sin tener que crear objetos de base de datos adicionales.
• Analice y cargue correctamente los archivos CSV en los que los delimitadores (cadena, campo, fila) se escapen dentro de las columnas delimitadas de cadena.
• Especifique un modelo de permisos más fino sin exponer las claves de cuenta de almacenamiento mediante firmas de acceso compartido (SAS).
• Usa una cuenta de almacenamiento diferente para la ERRORFILE ubicación (REJECTED_ROW_LOCATION).
• Personalice los valores predeterminados de cada columna de destino y especifique los campos de datos de origen que se van a cargar en columnas de destino concretas.
• Especifica un terminador de fila personalizado, un terminador de campo y una cita de campo para archivos CSV.
• Use formatos de fecha SQL Server para archivos CSV.
• Especifique caracteres comodín y varios archivos en la ruta de acceso de la ubicación de almacenamiento.
• La detección automática de esquemas simplifica el proceso de definición y asignación de datos de origen en tablas de destino.
• El proceso de creación automática de tablas crea automáticamente las tablas y funciona junto con la detección automática de esquemas.
• Cargue directamente tipos de datos complejos de archivos Parquet, como Maps y Lists en columnas de cadena, sin usar otras herramientas para preprocesar los datos.

Para obtener ejemplos completos e inicios rápidos mediante la COPY instrucción , consulte:

• Inicio rápido: Carga masiva de datos mediante la instrucción COPY
• Inicio rápido: Ejemplos de uso de la instrucción COPY y sus métodos de autenticación admitidos
• Inicio rápido: Creación de la instrucción COPY mediante la interfaz de usuario de Synapse Studio enriquecida

Syntax

COPY INTO [ schema. ] table_name
[ (Column_list) ]
FROM '<external_location>' [ , ...n ]
WITH
 (
 [ FILE_TYPE = { 'CSV' | 'PARQUET' | 'ORC' } ]
 [ , FILE_FORMAT = EXTERNAL FILE FORMAT OBJECT ]
 [ , CREDENTIAL = (AZURE CREDENTIAL) ]
 [ , ERRORFILE = ' [ http(s)://storageaccount/container ] /errorfile_directory [ / ] ] '
 [ , ERRORFILE_CREDENTIAL = (AZURE CREDENTIAL) ]
 [ , MAXERRORS = max_errors ]
 [ , COMPRESSION = { 'Gzip' | 'DefaultCodec' | 'Snappy' } ]
 [ , FIELDQUOTE = 'string_delimiter' ]
 [ , FIELDTERMINATOR =  'field_terminator' ]
 [ , ROWTERMINATOR = 'row_terminator' ]
 [ , FIRSTROW = first_row ]
 [ , DATEFORMAT = 'date_format' ]
 [ , ENCODING = { 'UTF8' | 'UTF16' } ]
 [ , IDENTITY_INSERT = { 'ON' | 'OFF' } ]
 [ , AUTO_CREATE_TABLE = { 'ON' | 'OFF' } ]
)

Arguments

schema_name

Es opcional si el esquema predeterminado para el usuario que realiza la operación es el esquema de la tabla especificada. Si no especifica el esquema y el esquema predeterminado del usuario que realiza la COPY operación es diferente del esquema de la tabla especificada, se cancela la COPY operación y se devuelve un mensaje de error.

nombre_de_tabla

Es el nombre de la tabla en la que se van a copiar (COPY) los datos. La tabla de destino puede ser una tabla temporal o permanente, y ya debe existir en la base de datos. Para el modo de detección automática de esquemas, no proporcione una lista de columnas.

(column_list)

Lista opcional de una o varias columnas que se usa para asignar campos de datos de origen a las columnas de la tabla de destino y cargar datos.

No especifique una column_list cuando AUTO_CREATE_TABLE = 'ON'.

column_list debe ir entre paréntesis y delimitada con comas. La lista de columnas tiene el formato siguiente:

[(Column_name [Default_value predeterminado] [Field_number] [,... n])]

• Column_name: el nombre de la columna en la tabla de destino.
• Default_value: valor predeterminado que sustituye a cualquier valor NULL del archivo de entrada. El valor predeterminado se aplica a todos los formatos de archivo. COPY intenta cargar NULL desde el archivo de entrada cuando se omite una columna de la lista de columnas o cuando hay un campo de archivo de entrada vacío. El valor predeterminado va precedido de la palabra clave "default".
• Field_number: número de campo de archivo de entrada asignado a la columna de destino.
• La indización de campos comienza en 1.

Cuando no se especifica una lista de columnas, COPY asigna columnas basadas en el orden de origen y destino: el campo de entrada 1 va a la columna 1 de destino, el campo 2 va a la columna 2, etc.

Ubicaciones externas

Ubicación donde se almacenan provisionalmente los archivos que contienen los datos. Actualmente, se admiten Azure Data Lake Storage (ADLS) Gen2 y Azure Blob Storage:

• Ubicación externa para Blob Storage: https://<account\>.blob.core.windows.net/<container\>/<path\>
• Ubicación externa para ADLS Gen2: https://<account\>.dfs.core.windows.net/<container\>/<path\>

• Cuenta: el nombre de la cuenta de almacenamiento

• Contenedor: el nombre del contenedor de blobs

• Ruta: la carpeta o la ruta de acceso de archivo para los datos. La ubicación comienza en el contenedor. Si especifica una carpeta, COPY recupera todos los archivos de la carpeta y todas sus subcarpetas. COPYomite las carpetas ocultas y no devuelve archivos que comienzan con un subrayado () o un punto (_.), a menos que se especifique explícitamente en la ruta de acceso. Este comportamiento es el mismo incluso cuando se especifica una ruta de acceso con un carácter comodín.

Puede incluir caracteres comodín en la ruta de acceso donde:

• La coincidencia de nombres de la ruta de acceso de caracteres comodín distingue mayúsculas de minúsculas
• Puede escapar un carácter comodín mediante el carácter de barra diagonal inversa (\)
• La expansión de caracteres comodín se aplica de forma recursiva. Por ejemplo, todos los archivos CSV de Customer1 (incluidos los subdirectorios de Customer1) se cargan en el ejemplo siguiente: Account/Container/Customer1/*.csv

Puede especificar varias ubicaciones de archivos solo desde la misma cuenta de almacenamiento y contenedor a través de una lista separada por comas, como:

• https://<account>.blob.core.windows.net/<container\>/<path\>, https://<account\>.blob.core.windows.net/<container\>/<path\>

FILE_TYPE = { 'CSV' | 'PARQUET' | 'ORC' }

FILE_TYPE especifica el formato de los datos externos.

• CSV: especifica un archivo de valores separados por comas compatible con el estándar RFC 4180 .
• PARQUET: Especifica un formato Parquet.
• ORC: Especifica un formato ORC (Optimized Row Columnar).

FILE_FORMAT = external_file_format_name

FILE_FORMAT solo se aplica a archivos Parquet y ORC. Especifica el nombre del objeto de formato de archivo externo que almacena el tipo de archivo y el método de compresión para los datos externos. Para crear un formato de archivo externo, use CREATE EXTERNAL FILE FORMAT.

CREDENTIAL (IDENTITY = '', SECRET = '')

CREDENTIAL Especifica el mecanismo de autenticación para acceder a la cuenta de almacenamiento externa. Los métodos de autenticación son:

	CSV	Parquet	ORC
Azure Blob Storage	SAS/MSI/PRINCIPAL DE SERVICIO/KEY/Entra	SAS/KEY	SAS/KEY
Azure Data Lake Gen2	SAS/MSI/PRINCIPAL DE SERVICIO/KEY/Entra	SAS (blob 1 )/MSI (dfs 2 )/PRINCIPAL DE SERVICIO/KEY/Entra	SAS (blob 1 )/MSI (dfs 2 )/PRINCIPAL DE SERVICIO/KEY/Entra

¹ Es necesario el punto de conexión de blob (.blob.core.windows.net) en la ruta de acceso de ubicación externa para este método de autenticación.

² El punto de conexión de dfs (.dfs.core.windows.net) en la ruta de acceso de ubicación externa es necesario para este método de autenticación.

• Autenticación con firmas de acceso compartido (SAS)

  • IDENTITY: constante con un valor de Shared Access Signature
  • SECRET: la firma de acceso compartido proporciona acceso delegado a los recursos de la cuenta de almacenamiento.

• Permisos mínimos necesarios: READ y LIST

• Autenticación con entidades de servicio

  • IDENTITY: <ClientID>@<OAuth_2.0_Token_EndPoint>
  • SECRET: clave de entidad de servicio de aplicación Microsoft Entra

• Roles de RBAC mínimos necesarios: Colaborador de datos de Storage Blob, colaborador de datos de Storage Blob, propietario de datos de Storage Blob o lector de datos de Storage Blob

• Autenticación con la clave de la cuenta de almacenamiento

  • IDENTITY: constante con un valor de Storage Account Key
  • SECRET: clave de cuenta de almacenamiento

• Autenticación con identidad administrada (puntos de conexión de servicio de red virtual)

  • IDENTITY: constante con un valor de Managed Identity

• Roles de RBAC mínimos necesarios: colaborador de datos de blobs de almacenamiento o propietario de datos de blobs de Storage para el servidor lógico registrado de Microsoft Entra en Azure. Cuando se usa un grupo de SQL dedicado (anteriormente SQL DW) que no está asociado a un área de trabajo de Synapse, este rol de RBAC no es necesario, pero la identidad administrada requiere permisos de Access Control Lista (ACL) en los objetos de destino para habilitar el acceso de lectura a los archivos de origen.

• Autenticación con un usuario de Microsoft Entra

  • NO se requiere CREDENTIAL

• Roles de RBAC mínimos necesarios: colaborador de datos de blobs de almacenamiento o propietario de datos de blobs de Storage para el usuario de Microsoft Entra

ERRORFILE = Ubicación del directorio

ERRORFILE solo se aplica a CSV. Especifica el directorio dentro de la COPY instrucción donde se escriben las filas rechazadas y el archivo de error correspondiente. Puede especificar la ruta de acceso completa desde la cuenta de almacenamiento o la ruta de acceso relativa al contenedor. Si la ruta de acceso especificada no existe, el almacén crea uno. Se crea un directorio secundario con el nombre _rejectedrows. El _ carácter garantiza que el directorio se escape para otro procesamiento de datos, a menos que se indique explícitamente el nombre en el parámetro location.

Dentro de este directorio, el almacén crea una carpeta en función del tiempo de envío de carga en el formato YearMonthDay -HourMinuteSecond (por ejemplo, 20180330-173205). En esta carpeta, el proceso escribe dos tipos de archivos: el archivo de motivo (error) y el archivo de datos (fila). Cada archivo antepone los queryIDGUID de archivo , distributionIDy . Como los datos y los motivos están en archivos independientes, los archivos correspondientes tienen un prefijo coincidente.

Si ERRORFILE tiene definida la ruta de acceso completa de la cuenta de almacenamiento, COPY usa ERRORFILE_CREDENTIAL para conectarse a ese almacenamiento. De lo contrario, usa el valor especificado para CREDENTIAL. Cuando se usa la misma credencial para los datos de origen y ERRORFILE, también se aplican restricciones.ERRORFILE_CREDENTIAL

ERRORFILE_CREDENTIAL = (IDENTITY = '', SECRET = '')

ERRORFILE_CREDENTIAL solo se aplica a los archivos CSV. Los métodos de autenticación y el origen de datos admitidos son:

• Azure Blob Storage: SAS, entidad de servicio o Microsoft Entra

• Azure Data Lake Gen2: SAS, MSI, entidad de servicio o Microsoft Entra

• Autenticación con firmas de acceso compartido (SAS)

  • IDENTITY: constante con un valor de Shared Access Signature
  • SECRET: la firma de acceso compartido proporciona acceso delegado a los recursos de la cuenta de almacenamiento.

• Permisos mínimos necesarios: READ, LIST, WRITE, CREATE, DELETE

• Autenticación con entidades de servicio

  • IDENTITY: <ClientID>@<OAuth_2.0_Token_EndPoint>
  • SECRET: clave de entidad de servicio de aplicación Microsoft Entra

• Roles de RBAC mínimos necesarios: Colaborador de datos de Storage Blob o propietario de datos de Storage Blob

• Autenticación con identidad administrada (puntos de conexión de servicio de red virtual)

  • IDENTITY: constante con un valor de Managed Identity

• Roles de RBAC mínimos necesarios: colaborador de datos de blobs de almacenamiento o propietario de datos de blobs de Storage para el servidor de SQL Database registrado de Microsoft Entra

• Autenticación con un usuario de Microsoft Entra

  • CREDENTIAL no es necesario

• Roles de RBAC mínimos necesarios: colaborador de datos de blobs de almacenamiento o propietario de datos de blobs de Storage para el usuario de Microsoft Entra

No se admite el uso de una clave de cuenta de almacenamiento con ERRORFILE_CREDENTIAL .

MAXERRORS = max_errors

MAXERRORS especifica el número máximo de filas de rechazo permitidas en la carga antes de que se produzca un error en la operación COPY. Cada fila que no se puede importar con la operación COPY se omite y se cuenta como un error. Si no especifica un valor para el número máximo de errores, el valor predeterminado es 0.

MAXERRORS no se puede usar con AUTO_CREATE_TABLE.

Cuando FILE_TYPE es PARQUET, las excepciones causadas por errores de conversión de tipos de datos (por ejemplo, binario de Parquet a entero de SQL) siguen provocando COPY INTO un error, ignorando MAXERRORS.

COMPRESSION = { 'DefaultCodec' | 'Snappy' | 'GZIP' | 'NONE'}

COMPRESSION es opcional y especifica el método de compresión de datos para los datos externos.

• CSV admite GZIP.
• Parquet admite GZIP y Snappy.
• ORC admite DefaultCodec y Snappy.
• Zlib es la compresión predeterminada para ORC.

El comando COPY detecta automáticamente el tipo de compresión en función de la extensión de archivo cuando no se especifica este parámetro:

• .gz - GZIP
• .snappy - Rápido
• .deflate - DefaultCodec (solo Parquet y ORC)

El comando COPY requiere que los archivos gzip no contengan elementos no utilizados finales para funcionar normalmente. El formato gzip requiere estrictamente que los archivos se componen de miembros válidos sin ninguna información adicional antes, entre o después de ellos. Cualquier desviación de este formato, como la presencia de datos finales que no son gzip, da como resultado el error del comando COPY. Para asegurarse de que COPY se ejecuta correctamente, asegúrese de comprobar que no hay elementos no utilizados finales al final de los archivos gzip.

CITA DE CAMPO = 'field_quote'

FIELDQUOTE se aplica a CSV y especifica un solo carácter que se usa como carácter de comillas (delimitador de cadena) en el archivo CSV. Si no especifica este valor, el carácter de comilla (") se usa como carácter de comilla tal como se define en el estándar RFC 4180. También se admite la notación hexadecimal para FIELDQUOTE. Los caracteres ASCII y multibyte extendidos no se admiten con UTF-8 para FIELDQUOTE.

FIELDTERMINATOR = 'field_terminator'

FIELDTERMINATOR solo se aplica a CSV. Especifica el terminador de campo que se usa en el archivo CSV. Puede especificar el terminador de campo mediante la notación hexadecimal. El terminador de campo puede ser multicharacter. El terminador de campo predeterminado es un (,). Los caracteres ASCII y multibyte extendidos no se admiten con UTF-8 para FIELDTERMINATOR.

ROWTERMINATOR = "row_terminator"

ROWTERMINATOR solo se aplica a CSV. Especifica el terminador de fila que se usa en el archivo CSV. Puede especificar el terminador de fila mediante la notación hexadecimal. El terminador de fila puede ser multicharacter. De forma predeterminada, el terminador de fila es \r\n.

El comando COPY antepone el carácter \r al especificar \n (nueva línea), lo que genera \r\n. Para especificar solo el carácter \n, use la notación hexadecimal (0x0A). Al especificar terminadores de fila multicharacter en hexadecimal, no especifique 0x entre cada carácter.

Los caracteres ASCII y multibyte extendidos no se admiten con UTF-8 para ROWTERMINATOR.

FIRSTROW = First_row_int

FIRSTROW se aplica a CSV y especifica el número de fila que se lee primero en todos los archivos del comando COPY. Los valores comienzan desde 1, que es el valor predeterminado. Si establece el valor 2en , se omite la primera fila de cada archivo (fila de encabezado) cuando se cargan los datos. Las filas se omiten en función de la existencia de terminadores de fila.

DATEFORMAT = { 'mdy' | 'dmy' | 'ymd' | 'ydm' | 'myd' | 'dym' }

DATEFORMAT solo se aplica a CSV y especifica el formato de fecha de la asignación de fecha para los formatos de fecha de SQL Server. Para una introducción acerca de todos los tipos de datos y funciones de fecha y hora de Transact-SQL, vea Funciones de fecha y hora (Transact-SQL). DATEFORMAT dentro del comando COPY tiene prioridad sobre DATEFORMAT configurado en el nivel de sesión.

ENCODING = 'UTF8' | 'UTF16'

ENCODING solo se aplica a CSV. El valor predeterminado es UTF8. Especifica el estándar de codificación de datos para los archivos cargados por el comando COPY.

IDENTITY_INSERT = 'ON' | 'OFF'

IDENTITY_INSERT especifica si el valor de identidad o los valores del archivo de datos importados se usarán para la columna de identidad. Si IDENTITY_INSERT es OFF (valor predeterminado), se comprueban los valores de identidad de esta columna, pero no se importan. Tenga en cuenta el siguiente comportamiento con el comando COPY:

• Si IDENTITY_INSERT es OFF y la tabla tiene una columna de identidad
  • Debe especificar una lista de columnas que no asigne un campo de entrada a la columna de identidad.
• Si IDENTITY_INSERT es ON y la tabla tiene una columna de identidad
  • Si pasa una lista de columnas, debe asignar un campo de entrada a la columna de identidad.
• El valor predeterminado no se admite para la columna IDENTITY de la lista de columnas.
• Solo se puede establecer IDENTITY_INSERT para una tabla a la vez.

Azure Synapse Analytics asigna automáticamente valores únicos en función de los valores de inicialización e incremento especificados durante la creación de la tabla.

AUTO_CREATE_TABLE = { 'ON' | 'OFF' }

AUTO_CREATE_TABLE especifica si la tabla se puede crear automáticamente trabajando junto con la detección automática de esquemas. AUTO_CREATE_TABLE solo está disponible para archivos Parquet en Azure Synapse Analytics.

• ON: habilita la creación automática de tablas. El COPY INTO proceso crea automáticamente una nueva tabla detectando la estructura del archivo que se va a cargar. También puede usarlo con tablas preexistentes para aprovechar la detección automática de esquemas de archivos Parquet.
• OFF: la creación automática de tablas no está habilitada. Default.

Permissions

El usuario que ejecuta el comando COPY debe tener los permisos siguientes:

• ADMINISTRACIÓN DE OPERACIONES MASIVAS DE BASE DE DATOS
• INSERT

Se requieren los permisos INSERT y ADMINISTER BULK OPERATIONS. En Azure Synapse Analytics, se necesitan los permisos INSERT y ADMINISTER DATABASE BULK OPERATIONS.

Además, si el usuario que ejecuta el comando COPY también pretende generar una nueva tabla y cargar datos en ella, necesitará los permisos CREATE TABLE y ALTER ON SCHEMA.

Por ejemplo, para permitir que mike@contoso.com use COPY para crear una nueva tabla en el esquema HR e insertar los datos de un archivo Parquet, use el siguiente ejemplo de Transact-SQL:

GRANT ADMINISTER DATABASE BULK OPERATIONS to [mike@contoso.com];
GRANT INSERT to [mike@contoso.com];

GRANT CREATE TABLE to [mike@contoso.com];
GRANT ALTER on SCHEMA::HR to [mike@contoso.com];

Remarks

La COPY instrucción solo acepta caracteres válidos UTF-8 y UTF-16 para los datos de fila y parámetros de comando. La COPY instrucción podría interpretar incorrectamente los archivos o parámetros de origen (como ROWTERMINATOR o FIELDTERMINATOR) que usan caracteres no válidos y provocar resultados inesperados, como daños en los datos u otros errores. Asegúrate de que tus archivos fuente y parámetros cumplan con UTF-8 o UTF-16 antes de invocar la COPY sentencia.

La MAXDOP sugerencia de consulta no se admite con COPY INTO.

Para garantizar una ejecución confiable, no cambie los archivos y carpetas de origen durante la COPY INTO operación.

• Modificar, eliminar o reemplazar los archivos o carpetas a los que se hace referencia mientras se ejecuta el comando puede provocar un error en la operación o provocar una ingesta de datos incoherente.
• Antes de ejecutar COPY INTO, compruebe que todos los datos de origen son estables y no se modificarán durante el proceso.

Si los datos de origen tienen mayor precisión que la definición de columna de destino, el valor se trunca, no se redondea, para los tipos numéricos, de fecha y hora.

Examples

A. Realizar la carga desde una cuenta de almacenamiento público

En el ejemplo siguiente se muestra la forma más sencilla del COPY comando , que carga datos de una cuenta de almacenamiento pública. En este ejemplo, los valores predeterminados de la COPY instrucción coinciden con el formato del archivo CSV del elemento de línea.

COPY INTO dbo.[lineitem]
FROM 'https://unsecureaccount.blob.core.windows.net/customerdatasets/folder1/lineitem.csv'
WITH (FIELDTERMINATOR = '|')

Los valores predeterminados del comando COPY son:

• DATEFORMAT = Session DATEFORMAT

• MAXERRORS = 0

• COMPRESSION por defecto es sin comprimir

• FIELDQUOTE = '"'

• FIELDTERMINATOR = ','

• ROWTERMINATOR = '\n'

• FIRSTROW = 1

• ENCODING = 'UTF8'

• FILE_TYPE = 'CSV'

• IDENTITY_INSERT = 'OFF'

B. Realizar la carga mediante la autenticación a través de la firma de acceso compartido (SAS)

En el ejemplo siguiente se cargan archivos que usan la fuente de líneas como terminador de fila, como una salida de UNIX. En este ejemplo también se usa una clave SAS para autenticarse en Azure Blob Storage.

COPY INTO test_1
FROM 'https://myaccount.blob.core.windows.net/myblobcontainer/folder1/'
WITH (
    FILE_TYPE = 'CSV',
    CREDENTIAL=(IDENTITY= 'Shared Access Signature', SECRET='<Your_SAS_Token>'),
    --CREDENTIAL should look something like this:
    --CREDENTIAL=(IDENTITY= 'Shared Access Signature', SECRET='?sv=2018-03-28&ss=bfqt&srt=sco&sp=rl&st=2016-10-17T20%3A14%3A55Z&se=2021-10-18T20%3A19%3A00Z&sig=IEoOdmeYnE9%2FKiJDSHFSYsz4AkNa%2F%2BTx61FuQ%2FfKHefqoBE%3D'),
    FIELDQUOTE = '"',
    FIELDTERMINATOR=';',
    ROWTERMINATOR='0X0A',
    ENCODING = 'UTF8',
    DATEFORMAT = 'ymd',
    MAXERRORS = 10,
    ERRORFILE = '/errorsfolder',--path starting from the storage container
    IDENTITY_INSERT = 'ON'
)

C. Realizar la carga con una lista de columnas con valores predeterminados mediante la autenticación a través de la clave de cuenta de almacenamiento

En este ejemplo se cargan archivos que especifican una lista de columnas con valores predeterminados.

--Note when specifying the column list, input field numbers start from 1
COPY INTO test_1 (Col_one default 'myStringDefault' 1, Col_two default 1 3)
FROM 'https://myaccount.blob.core.windows.net/myblobcontainer/folder1/'
WITH (
    FILE_TYPE = 'CSV',
    CREDENTIAL=(IDENTITY= 'Storage Account Key', SECRET='<Your_Account_Key>'),
    FIELDQUOTE = '"',
    FIELDTERMINATOR=',',
    ROWTERMINATOR='0x0A',
    ENCODING = 'UTF8',
    FIRSTROW = 2
)

D. Realizar la carga de ORC o Parquet con el objeto de formato de archivo existente

En este ejemplo se usa un carácter comodín para cargar todos los archivos de Parquet en una carpeta.

COPY INTO test_parquet
FROM 'https://myaccount.blob.core.windows.net/myblobcontainer/folder1/*.parquet'
WITH (
    FILE_FORMAT = myFileFormat,
    CREDENTIAL=(IDENTITY= 'Shared Access Signature', SECRET='<Your_SAS_Token>')
)

E. Realizar la carga mediante la especificación de caracteres comodín y varios archivos

COPY INTO t1
FROM
'https://myaccount.blob.core.windows.net/myblobcontainer/folder0/*.txt',
    'https://myaccount.blob.core.windows.net/myblobcontainer/folder1'
WITH (
    FILE_TYPE = 'CSV',
    CREDENTIAL=(IDENTITY= '<client_id>@<OAuth_2.0_Token_EndPoint>',SECRET='<key>'),
    FIELDTERMINATOR = '|'
)

F. Realizar la carga con credenciales de MSI

COPY INTO dbo.myCOPYDemoTable
FROM 'https://myaccount.blob.core.windows.net/myblobcontainer/folder0/*.txt'
WITH (
    FILE_TYPE = 'CSV',
    CREDENTIAL = (IDENTITY = 'Managed Identity'),
    FIELDQUOTE = '"',
    FIELDTERMINATOR=','
)

G. Realizar la carga con la detección automática de esquemas

COPY INTO [myCOPYDemoTable]
FROM 'https://myaccount.blob.core.windows.net/customerdatasets/folder1/lineitem.parquet'
WITH (
    FILE_TYPE = 'Parquet',
    CREDENTIAL = ( IDENTITY = 'Shared Access Signature',  SECRET='<key>'),
    AUTO_CREATE_TABLE = 'ON'
)

FAQ

¿Cómo se compara el rendimiento del comando COPY con PolyBase?

El rendimiento del comando COPY puede ser mejor en función de la carga de trabajo.

• El almacén no puede dividir automáticamente los archivos comprimidos. Para obtener el mejor rendimiento de carga, considere la posibilidad de dividir la entrada en varios archivos al cargar CSV comprimidos.

• El almacenamiento puede dividir automáticamente archivos CSV grandes sin comprimir para la carga en paralelo, por lo que normalmente no es necesario dividir manualmente archivos CSV sin comprimir. En determinados casos en los que la división automática de archivos no es factible debido a las características de los datos, la división manual de grandes CSV podría seguir beneficiando al rendimiento.

¿Cuál es el procedimiento para dividir archivos a la hora de cargar archivos .csv comprimidos con el comando COPY?

En la tabla siguiente se describe el número de archivos que debe usar. Cuando llegue al número recomendado de archivos, obtendrá un mejor rendimiento con archivos más grandes. El número de archivos viene determinado por el número de nodos de proceso multiplicados por 60. Por ejemplo, en 6000 DWU, tiene 12 nodos de proceso, por lo que tiene 12 * 60 = 720 particiones. Para obtener una experiencia sencilla de división de archivos, consulte Cómo maximizar el rendimiento de carga copy con divisiones de archivos.

DWU	Número de archivos
100	60
200	60
300	60
400	60
500	60
1,000	120
1,500	180
2,000	240
2,500	300
3,000	360
5,000	600
6,000	720
7,500	900
10,000	1200
15,000	1800
30,000	3600

¿Cuál es el procedimiento para dividir archivos a la hora de cargar archivos ORC o Parquet con el comando COPY?

No es necesario dividir archivos Parquet y ORC porque el comando COPY divide automáticamente los archivos. Para obtener el mejor rendimiento, los archivos Parquet y ORC de la cuenta de almacenamiento de Azure deben ser de 256 MB o más.

¿Hay alguna limitación en el número o el tamaño de los archivos?

No hay limitaciones en el número o el tamaño de los archivos. Sin embargo, para obtener el mejor rendimiento, use archivos que tienen al menos 4 MB. Además, limite el recuento de archivos de origen a un máximo de 5000 archivos para mejorar el rendimiento.

¿Hay algún problema conocido con la instrucción COPY?

Si tiene un área de trabajo de Azure Synapse que creó antes del 7 de diciembre de 2020, es posible que se produzca un mensaje de error similar al autenticarse mediante la identidad administrada: com.microsoft.sqlserver.jdbc.SQLServerException: Managed Service Identity isn't enabled on this server. Please enable Managed Service Identity and try again.

Para solucionar este problema, vuelva a registrar la identidad administrada del área de trabajo:

1. Instale Azure PowerShell. Consulte Instalación de PowerShell.
2. Registre la identidad administrada del área de trabajo mediante PowerShell:

   Connect-AzAccount
   Select-AzSubscription -SubscriptionId <subscriptionId>
   Set-AzSqlServer -ResourceGroupName your-database-server-resourceGroup -ServerName your-SQL-servername -AssignIdentity
   

Contenido relacionado

• Información general sobre la carga con Azure Synapse Analytics

Se aplica a:Warehouse en Microsoft Fabric

En este artículo se explica cómo usar la instrucción /> de COPY proporciona la mayor flexibilidad para la ingesta de datos de alto rendimiento en el almacén en Microsoft Fabric y es la estrategia para Insertos más importantes en el almacén en Microsoft Fabric.

En Fabric Data Warehouse, la instrucción COPY admite actualmente formatos de archivo CSV, JSONL y PARQUET. En el caso de los orígenes de datos, se admiten las cuentas de Azure Data Lake Storage Gen2 y los orígenes de OneLake.

Para obtener más información sobre el uso COPY INTO en el almacenamiento en Microsoft Fabric, consulte Ingesta de datos en el almacén en Microsoft Fabric mediante la instrucción COPY.

De forma predeterminada, COPY INTO se autentica como el usuario que ejecuta Microsoft Entra ID.

Úsalo COPY para las siguientes capacidades:

• Use usuarios con privilegios inferiores para cargar datos sin necesidad de permisos estrictos de CONTROL en el almacenamiento.
• Ejecute una instrucción T-SQL única sin tener que crear objetos de base de datos adicionales.
• Analice y cargue correctamente los archivos CSV donde los delimitadores (cadena, campo y fila) se escapan dentro de las columnas delimitadas por cadenas.
• Analice y cargue correctamente los archivos JSONL en los que cada línea es un objeto JSON válido y los campos se asignan mediante expresiones de ruta de acceso JSON.
• Especifique un modelo de permisos más fino sin exponer las claves de cuenta de almacenamiento mediante firmas de acceso compartido (SAS).
• Usa una cuenta de almacenamiento diferente para la ERRORFILE ubicación (REJECTED_ROW_LOCATION).
• Personalice los valores predeterminados de cada columna de destino y especifique los campos de datos de origen que se van a cargar en columnas de destino concretas.
• Especifica un terminador de fila personalizado, un terminador de campo y una cita de campo para archivos CSV.
• Especifique caracteres comodín y varios archivos en la ruta de acceso de la ubicación de almacenamiento.
• Para obtener más información sobre las opciones de ingesta de datos y los procedimientos recomendados, consulte Ingesta de datos en el almacenamiento en Microsoft Fabric mediante la instrucción COPY.

Syntax

COPY INTO [ warehouse_name. ] [ schema_name. ] table_name
[ (Column_list) ]
FROM '<external_location>' [ , ...n ]
WITH
 (
 [ FILE_TYPE = { 'CSV' | 'JSONL' | 'PARQUET' } ]
 [ , CREDENTIAL = (AZURE CREDENTIAL) ]
 [ , ERRORFILE = ' [ http(s)://storageaccount/container ] /errorfile_directory [ / ] ] '
 [ , ERRORFILE_CREDENTIAL = (AZURE CREDENTIAL) ]
 [ , MAXERRORS = max_errors ]
 [ , COMPRESSION = { 'Gzip' | 'Snappy' } ]
 [ , FIELDQUOTE = 'string_delimiter' ]
 [ , FIELDTERMINATOR =  'field_terminator' ]
 [ , ROWTERMINATOR = 'row_terminator' ]
 [ , FIRSTROW = first_row ]
 [ , DATEFORMAT = 'date_format' ]
 [ , ENCODING = { 'UTF8' | 'UTF16' } ]
 [ , PARSER_VERSION = { '1.0' | '2.0' } ]
 [ , MATCH_COLUMN_COUNT = { 'ON' | 'OFF' } ]
)

Arguments

warehouse_name

Es opcional si el almacén actual del usuario que realiza la operación es el almacén de la tabla especificada. Si no especifica el almacenamiento y el esquema y la tabla especificados no existen en el almacén actual, COPY se produce un error y se devuelve un mensaje de error.

schema_name

Es opcional si el esquema predeterminado para el usuario que realiza la operación es el esquema de la tabla especificada. Si no especifica el esquema y el esquema predeterminado del usuario que realiza la COPY operación es diferente del esquema de la tabla especificada, COPY se cancela y se devuelve un mensaje de error.

nombre_de_tabla

El nombre de la tabla a la que COPY se puede dar datos. La tabla de destino ya debe existir en el almacén.

(column_list)

Lista opcional de columnas usadas para asignar campos de datos de origen a columnas de tabla de destino durante la carga de datos.

column_list debe ir entre paréntesis y delimitada con comas. La sintaxis es:

[(Column_name [Default_value predeterminado] [Field_number | JSON_path] [,... n])]

• Column_name: el nombre de la columna en la tabla de destino.
• Default_value - el valor por defecto que reemplaza cualquier NULL valor en el archivo de entrada. El valor predeterminado se aplica a todos los formatos de archivo. COPY Intenta cargar NULL desde el archivo de entrada cuando una columna se omite de la lista de columnas o cuando hay un campo de archivo de entrada vacío. El valor predeterminado va precedido de la palabra clave "default".
• Field_number : solo se aplica a los archivos CSV. Especifica la posición ordinal del campo en los datos de entrada. La indización de campos comienza en 1.
• JSON_path : solo se aplica a los archivos JSONL. Especifica una expresión de ruta de acceso JSON que identifica el campo que se va a extraer de cada objeto JSON (por ejemplo, $.CustomerName).

Cuando no se especifica column_list, COPY asigna columnas basadas en el orden de origen y destino: el campo de entrada 1 va a la columna 1 de destino, el campo 2 va a la columna 2, etc.

Cuando no se especifica una lista de columnas, COPY asigna columnas basadas en el orden de origen y destino: el campo de entrada 1 va a la columna 1 de destino, el campo 2 va a la columna 2, etc.

Ubicación externa

Especifica dónde se almacenan provisionalmente los archivos que contienen los datos. Actualmente, Azure Data Lake Storage (ADLS) Gen2, Azure Blob Storage y OneLake son compatibles:

• Ubicación externa para Blob Storage: https://<account\>.blob.core.windows.net/<container\>/<path\>
• Ubicación externa para ADLS Gen2: https://<account\>.dfs.core.windows.net/<container\>/<path\>
• Ubicación externa de OneLake: https://onelake.dfs.fabric.microsoft.com/<workspaceId>/<lakehouseId>/Files/

Azure Data Lake Storage (ADLS) Gen2 ofrece un mejor rendimiento que Azure Blob Storage (heredado). Considere la posibilidad de usar una cuenta de ADLS Gen2 siempre que sea posible.

• Cuenta: el nombre de la cuenta de almacenamiento

• Contenedor: el nombre del contenedor de blobs

• Ruta: la carpeta o la ruta de acceso de archivo para los datos. La ubicación comienza en el contenedor. Si especifica una carpeta, COPY recupera todos los archivos de la carpeta y todas sus subcarpetas. COPYomite las carpetas ocultas y no devuelve archivos que comienzan con un subrayado () o un punto (_.), a menos que se especifique explícitamente en la ruta de acceso. Este comportamiento es el mismo incluso cuando se especifica una ruta de acceso con un carácter comodín.

Se pueden incluir caracteres comodín en la ruta de acceso, donde

• La coincidencia de nombres de la ruta de acceso de caracteres comodín distingue mayúsculas de minúsculas
• Puede escapar un carácter comodín mediante el carácter de barra diagonal inversa (\)

Puede especificar varias ubicaciones de archivos solo desde la misma cuenta de almacenamiento y contenedor a través de una lista separada por comas, como:

• https://<account>.blob.core.windows.net/<container>/<path>, https://<account>.blob.core.windows.net/<container>/<path>

Ubicaciones externas detrás del firewall

Para acceder a los archivos de Azure Data Lake Storage (ADLS) Gen2 y las ubicaciones de Azure Blob Storage que están detrás de un firewall, se aplican los siguientes requisitos previos:

• Se debe aprovisionar una identidad de área de trabajo para el área de trabajo que hospeda el almacenamiento. Para más información sobre cómo configurar una identidad de área de trabajo, consulte Identidad del área de trabajo.
• La cuenta de Id. de Entra debe poder usar la identidad del área de trabajo.
• La cuenta de Entra ID debe tener acceso a los archivos subyacentes mediante el control de acceso basado en rol (RBAC) de Azure o las ACL del lago de datos.
• El área de trabajo de Fabric que hospeda el almacenamiento debe agregarse como regla de instancia de recurso. Para más información sobre cómo agregar el área de trabajo de Fabric con una regla de instancia de recurso, consulte Regla de instancia de recurso.

FILE_TYPE = { 'CSV' | 'JSONL' | 'PARQUET' }

FILE_TYPE especifica el formato de los datos externos.

• CSV: especifica un archivo de valores separados por comas compatible con el estándar RFC 4180 .
• JSONL: especifica un archivo JSON (líneas JSON) delimitado por nueva línea, donde cada línea es un objeto JSON válido.
• PARQUET: Especifica un formato Parquet.

CREDENTIAL (IDENTITY = '', SECRET = '')

CREDENTIAL Especifica el mecanismo de autenticación para acceder a la cuenta de almacenamiento externa.

En Fabric Data Warehouse:

• COPY INTO no se admite cuando el acceso público está deshabilitado.
• En el caso de las cuentas de almacenamiento públicas, los mecanismos de autenticación admitidos son el identificador de Microsoft Entra, la firma de acceso compartido (SAS) o la clave de cuenta de almacenamiento (SAK).
• En el caso de las cuentas de almacenamiento público detrás de un firewall, la autenticación de identificador de Microsoft Entra es el único método de autenticación admitido. COPY INTO el uso de OneLake como fuente solo admite la autenticación EntraID.

La autenticación Microsoft Entra ID del usuario es predeterminada. No es necesario especificar ninguna credencial.

• Autenticación con firma de acceso compartido (SAS)
  • IDENTITY: constante con un valor de Shared Access Signature.
  • SECRET: la firma de acceso compartido proporciona acceso delegado a los recursos de la cuenta de almacenamiento.
  • Permisos mínimos requeridos: READ y LIST.
• Autenticación con clave de cuenta de almacenamiento
  • IDENTITY: constante con un valor de Storage Account Key.
  • SECRET: Clave de cuenta de almacenamiento.

ERRORFILE = Ubicación del directorio

ERRORFILE se aplica a CSV y JSONL. Especifica el directorio donde se deben escribir las filas rechazadas y el archivo de error correspondiente. Puede especificar la ruta de acceso completa desde la cuenta de almacenamiento o la ruta de acceso relativa al contenedor. Si la ruta de acceso especificada no existe, el sistema crea una en su nombre. Se crea un directorio secundario con el nombre _rejectedrows. El _ carácter garantiza que el directorio se escape para otro procesamiento de datos, a menos que se indique explícitamente el nombre en el parámetro location.

Dentro de este directorio, el almacén crea una carpeta en función del tiempo de envío de carga en el formato YearMonthDay -HourMinuteSecond (por ejemplo, 20180330-173205). En esta carpeta, el almacenamiento crea una carpeta con el identificador de instrucción y, en esa carpeta, se escriben dos tipos de archivos: un error. Archivo JSON que contiene los motivos de rechazo y un archivo row.csv que contiene las filas rechazadas.

Si ERRORFILE tiene definida la ruta de acceso completa de la cuenta de almacenamiento, ERRORFILE_CREDENTIAL se usa para conectarse a ese almacenamiento. De lo contrario, se usa el valor mencionado para CREDENTIAL . Cuando se usa la misma credencial que se usa para los datos de origen se usa para ERRORFILE, las restricciones que se aplican también se ERRORFILE_CREDENTIAL aplican.

Cuando se usa una cuenta de Azure Storage protegida por firewall, el archivo de error se crea en el mismo contenedor especificado en la ruta de acceso de la cuenta de almacenamiento. Al considerar la posibilidad de usar la ERRORFILE opción en este escenario, también es necesario especificar el MAXERROR parámetro . Si ERRORFILE tiene definida la ruta de acceso completa de la cuenta de almacenamiento, ERRORFILE_CREDENTIAL se usa para conectarse a ese almacenamiento. De lo contrario, se usa el valor mencionado para CREDENTIAL .

ERRORFILE_CREDENTIAL = (IDENTITY = '', SECRET = '')

ERRORFILE_CREDENTIAL se aplica a archivos CSV y JSONL. En el almacenamiento de Microsoft Fabric, el único mecanismo de autenticación admitido es Firma de acceso compartido (SAS).

• Autenticación con firmas de acceso compartido (SAS)
  • IDENTITY: constante con un valor de Shared Access Signature
  • SECRET: la firma de acceso compartido proporciona acceso delegado a los recursos de la cuenta de almacenamiento.
• Permisos mínimos necesarios: READ, LIST, WRITE, CREATE, DELETE

MAXERRORS = max_errors

MAXERRORS se aplica a CSV y JSONL. Especifica el número máximo de filas de rechazo permitidas en la carga antes de que se produzca un error en la COPY operación. Cada fila que la COPY operación no puede importar se ignora y cuenta como un error. Si no especifica un número máximo de errores, el valor predeterminado es 0.

En Fabric Data Warehouse, no puede usar MAXERRORS cuando FILE_TYPE es PARQUET.

COMPRESSION = { 'Snappy' | 'GZIP' | 'NONE'}

COMPRESSION es opcional y especifica el método de compresión de datos para los datos externos.

• CSV admite GZIP.
• Parquet admite GZIP y Snappy.
• No se admite para JSONL

El COPY comando detecta automáticamente el tipo de compresión basándose en la extensión del archivo cuando este parámetro no está especificado:

• .gz - GZIP

La carga de archivos comprimidos solo se admite actualmente con la versión 1.0 del analizador.

El COPY comando requiere que los archivos gzip no contengan elementos no utilizados finales para funcionar normalmente. El formato gzip requiere estrictamente que los archivos se componen de miembros válidos sin ninguna información adicional antes, entre o después de ellos. Cualquier desviación de este formato, como la presencia de datos finales que no son gzip, da como resultado el error del COPY comando. Para asegurarse de que COPY las ejecuciones se ejecutan correctamente, asegúrese de comprobar que no hay elementos no utilizados finales al final de los archivos gzip.

CITA DE CAMPO = 'field_quote'

FIELDQUOTE solo se aplica a CSV. Especifica un solo carácter que se usa como carácter de comilla (delimitador de cadena) en el archivo CSV. Si no especifica FIELDQUOTE, el carácter de comillas (") se usa como carácter de comilla tal como se define en el estándar RFC 4180. También se admite la notación hexadecimal para FIELDQUOTE. Los caracteres ASCII y multibyte extendidos no se admiten con UTF-8 para FIELDQUOTE.

FIELDTERMINATOR = 'field_terminator'

FIELDTERMINATOR solo se aplica a CSV. Especifica el terminador de campo que se usa en el archivo CSV. También puede especificar el terminador de campo mediante notación hexadecimal. El terminador de campo puede ser multicharacter. El terminador de campo predeterminado es una coma (,). Los caracteres ASCII y multibyte extendidos no se admiten con UTF-8 para FIELDTERMINATOR.

ROWTERMINATOR = "row_terminator"

ROWTERMINATOR solo se aplica a CSV. Especifica el terminador de fila que se usa en el archivo CSV. Puede especificar el terminador de fila mediante notación hexadecimal. El terminador de fila puede ser multicharacter. Los terminadores predeterminados son \r\n, \ny \r.

El COPY comando prefija el \r carácter al especificar \n (nueva línea), resultando en \r\n. Para especificar solo el carácter \n, use la notación hexadecimal (0x0A). Al especificar terminadores de fila multicharacter en hexadecimal, no especifique 0x entre cada carácter.

Los caracteres ASCII y multibyte extendidos no se admiten con UTF-8 para ROWTERMINATOR.

FIRSTROW = First_row_int

FIRSTROW solo se aplica a CSV. Especifica el número de fila que se lee primero en todos los archivos del COPY comando. Los valores comienzan desde 1, que es el valor predeterminado. Si establece el valor 2en , se omite la primera fila de cada archivo (fila de encabezado) cuando se cargan los datos. Las filas se omiten en función de la existencia de terminadores de fila.

DATEFORMAT = { 'mdy' | 'dmy' | 'ymd' | 'ydm' | 'myd' | 'dym' }

DATEFORMAT se aplica a CSV y JSONL. Especifica el formato de fecha de la asignación de fechas a SQL Server formatos de fecha. Para una introducción acerca de todos los tipos de datos y funciones de fecha y hora de Transact-SQL, vea Funciones de fecha y hora (Transact-SQL). DATEFORMAT dentro del COPY comando tiene prioridad sobre DATEFORMAT configurado a nivel de sesión.

ENCODING = 'UTF8' | 'UTF16'

ENCODING se aplica a CSV y JSONL. El valor predeterminado es UTF8. Especifica el estándar de codificación de datos para los archivos cargados por el COPY comando.

PARSER_VERSION = { '1.0' | '2.0' }

PARSER_VERSION solo se aplica a los archivos CSV. El valor predeterminado es 2.0. PARSER_VERSION especifica el analizador de archivos usado para la ingesta cuando el tipo de archivo de origen es CSV. El analizador 2.0 ofrece un rendimiento mejorado para la ingesta de archivos CSV.

La versión 2.0 del analizador tiene las siguientes limitaciones:

• No se admiten archivos CSV comprimidos.
• No se admiten archivos con codificación UTF-16.
• No se admite multicharacter o multibyte ROWTERMINATOR, FIELDTERMINATORo FIELDQUOTE . Sin embargo, \r\n se acepta como predeterminado ROWTERMINATOR.

Cuando se usa la versión 1.0 del analizador con archivos UTF-8, los terminadores multibyte y multicharacter no se admiten para FIELDTERMINATOR.

La versión 1.0 del analizador solo está disponible para la compatibilidad con versiones anteriores. Úselo solo cuando encuentre estas limitaciones.

MATCH_COLUMN_COUNT = { 'ON' | 'OFF' }

MATCH_COLUMN_COUNT solo se aplica a los archivos CSV. El valor predeterminado es OFF. Especifica si el COPY comando debe comprobar si las filas de recuento de columnas de los archivos de origen coinciden con el recuento de columnas de la tabla de destino. Se aplica el siguiente comportamiento:

• Si MATCH_COLUMN_COUNT es OFF:
  • El comando omite la superación de columnas de las filas de origen.
    • El comando inserta NULL valores en columnas que aceptan valores NULL para las filas con menos columnas.
  • Si no se proporciona un valor a una columna que no acepta valores NULL, se produce un error en el COPY comando.
• Si MATCH_COLUMN_COUNT es ON:
  • El COPY comando comprueba si el conteo de columnas en cada fila de cada archivo desde el archivo fuente coincide con el conteo de columnas de la tabla de destino.
• Si hay un error de coincidencia de recuento de columnas, se produce un error en el COPY comando.

Uso de COPY INTO con OneLake

Use COPY INTO para cargar datos directamente desde archivos almacenados en Fabric OneLake, en elementos existentes. Este método elimina la necesidad de cuentas de almacenamiento provisional externas, como ADLS Gen2 o Blob Storage, y habilita la ingesta nativa de SaaS controlada por el área de trabajo mediante permisos de Fabric. Esta funcionalidad admite:

• Lectura desde cualquier ubicación dentro de un área de trabajo y un elemento
• Cargas de área de trabajo a almacenamiento dentro del mismo inquilino
• Aplicación de identidad nativa mediante Microsoft Entra ID

Example:

COPY INTO t1
FROM 'https://onelake.dfs.fabric.microsoft.com/<workspaceId>/<lakehouseId>/Files/*.csv'
WITH (
    FILE_TYPE = 'CSV',
    FIRSTROW = 2
);

Permissions

Permisos del plano de control

Para ejecutar el COPY INTO comando, debe concederse la pertenencia a un rol de área de trabajo a través de Administrar el acceso en el área de trabajo, con al menos el rol Visor. Como alternativa, puede compartir el acceso de almacenamiento con un usuario a través de los permisos de Item en el portal de Fabric, con al menos permisos de lectura. Para alinearse con el principio de privilegios mínimos, el permiso de lectura es suficiente.

Permisos del plano de datos

Después de conceder permisos de plano de control a través de roles de área de trabajo o permisos de elemento, si el usuario solo tiene permisos de lectura en el nivel del plano de datos, conceda también al usuario INSERT y ADMINISTER DATABASE BULK OPERATIONS permisos mediante comandos de T-SQL.

Por ejemplo, el siguiente script de T-SQL concede estos permisos a un usuario individual mediante su Microsoft Entra ID.

GRANT ADMINISTER DATABASE BULK OPERATIONS to [mike@contoso.com];
GO

GRANT INSERT to [mike@contoso.com];
GO

Cuando se usa la opción de archivo de error, el usuario debe tener el permiso mínimo de Blob Storage Colaborador en el contenedor de la cuenta de almacenamiento.

Cuando se usa OneLake como origen, el usuario debe tener permisos De colaborador o superior en el área de trabajo de origen (donde se encuentra Lakehouse) y el área de trabajo de destino (donde reside el almacén). Microsoft Entra ID y Fabric roles de área de trabajo rigen todo el acceso.

Remarks

La COPY instrucción solo acepta caracteres válidos UTF-8 y UTF-16 para los datos de fila y parámetros de comando. Si usa archivos de origen o parámetros (como ROWTERMINATOR o FIELDTERMINATOR) que contienen caracteres no válidos, la COPY instrucción puede interpretarlos incorrectamente y provocar resultados inesperados, como daños en los datos u otros errores. Antes de invocar la COPY instrucción , asegúrese de que los archivos y parámetros de origen son compatibles con UTF-8 o UTF-16.

La COPY INTO instrucción tiene restricciones en el tamaño de las columnas varchar(max) y varbinary(max) individuales, así como en el tamaño total de fila que puede ingerir.

• Parquet: tamaño máximo de columna varchar(max)/varbinary(max) de 16 MB, tamaño máximo de fila 1 GB.
• CSV y JSONL: tamaño máximo de columna varchar(max)/varbinary(max) de 1 MB, tamaño máximo de fila 16 MB.

Para garantizar una ejecución confiable, no cambie los archivos y carpetas de origen durante la COPY INTO operación.

• Modificar, eliminar o reemplazar los archivos o carpetas a los que se hace referencia mientras se ejecuta el comando puede provocar un error en la operación o provocar una ingesta de datos incoherente.
• Antes de ejecutar COPY INTO, compruebe que todos los datos de origen son estables y no se modifican durante el proceso.

Si los datos de origen tienen mayor precisión que la definición de columna de destino, el valor se trunca, no se redondea, para los tipos numéricos, de fecha y hora.

Limitaciones de OneLake como origen

• Sólo se admite la autenticación Microsoft Entra ID. No se permiten otros métodos de autenticación, como tokens de SAS, claves compartidas o cadenas de conexión.

• Los elementos de almacenamiento no se admiten como ubicaciones de origen. Los archivos deben originarse en otros elementos de Fabric que expongan archivos a través de OneLake Storage.

• Las rutas oneLake deben usar identificadores de área de trabajo y almacenamiento. En este momento no se admiten nombres descriptivos para áreas de trabajo o Lakehouses.

• Los permisos de colaborador son necesarios en ambas áreas de trabajo. El usuario que ejecuta debe tener al menos el rol Colaborador en el área de trabajo de Source Lakehouse y en el área de trabajo De almacenamiento de destino.

Examples

Para obtener más información sobre el uso COPY INTO en el almacenamiento en Microsoft Fabric, consulte Ingesta de datos en el almacén en Microsoft Fabric mediante la instrucción COPY.

A. Realizar la carga desde una cuenta de almacenamiento público

En el ejemplo siguiente se muestra la forma más sencilla del COPY comando , que carga datos de una cuenta de almacenamiento pública. En este ejemplo, los valores predeterminados de la COPY instrucción coinciden con el formato del archivo CSV del elemento de línea.

COPY INTO dbo.[lineitem]
FROM 'https://unsecureaccount.blob.core.windows.net/customerdatasets/folder1/lineitem.csv'

Los valores por defecto del COPY comando son:

• MAXERRORS = 0

• COMPRESSION (el valor predeterminado es sin comprimir)

• FIELDQUOTE = '"'

• FIELDTERMINATOR = ','

• ROWTERMINATOR = '\n'

  Important

  COPY Trata \n como \r\n internamente. Para obtener más información, vea la sección ROWTERMINATOR.

• FIRSTROW = 1

• ENCODING = 'UTF8'

• FILE_TYPE = 'CSV'

B. Realizar la carga mediante la autenticación a través de la firma de acceso compartido (SAS)

En el ejemplo siguiente se cargan archivos que usan la fuente de líneas como terminador de fila, como una salida de UNIX. En este ejemplo también se usa una clave SAS para autenticarse en Azure Blob Storage.

COPY INTO test_1
FROM 'https://myaccount.blob.core.windows.net/myblobcontainer/folder1/'
WITH (
    FILE_TYPE = 'CSV',
    CREDENTIAL=(IDENTITY= 'Shared Access Signature', SECRET='<Your_SAS_Token>'),
    FIELDQUOTE = '"',
    FIELDTERMINATOR = ';',
    ROWTERMINATOR = '0X0A',
    ENCODING = 'UTF8',
    MAXERRORS = 10,
    ERRORFILE = '/errorsfolder'--path starting from the storage container
)

C. Realizar la carga con una lista de columnas con valores predeterminados mediante la autenticación a través de la clave de cuenta de almacenamiento (SAK)

En este ejemplo se cargan archivos que especifican una lista de columnas con valores predeterminados.

--Note when specifying the column list, input field numbers start from 1
COPY INTO test_1 (Col_one default 'myStringDefault' 1, Col_two default 1 3)
FROM 'https://myaccount.blob.core.windows.net/myblobcontainer/folder1/'
WITH (
    FILE_TYPE = 'CSV',
    CREDENTIAL=(IDENTITY= 'Storage Account Key', SECRET='<Your_account_key>'),
    FIELDQUOTE = '"',
    FIELDTERMINATOR=',',
    ROWTERMINATOR='0x0A',
    ENCODING = 'UTF8',
    FIRSTROW = 2
)

D. Carga de Parquet

En este ejemplo se usa un carácter comodín para cargar todos los archivos Parquet en una carpeta mediante el Entra ID del usuario en ejecución.

COPY INTO test_parquet
FROM 'https://myaccount.blob.core.windows.net/myblobcontainer/folder1/*.parquet'
WITH (
    FILE_TYPE = 'PARQUET'
)

E. Carga de JSONL

En este ejemplo se usa un carácter comodín para cargar todos los archivos JSONL en una carpeta mediante el Entra ID del usuario en ejecución.

COPY INTO test_jsonl
FROM 'https://myaccount.blob.core.windows.net/myblobcontainer/folder1/*.jsonl'
WITH (
    FILE_TYPE = 'JSONL'
)

F. Asignación de nombres de columna a rutas de acceso de campo en documentos JSONL

En el ejemplo siguiente se muestra un archivo JSON Lines (JSONL), donde cada línea representa un único objeto JSON:

{"CountryKey": 0, "CountryName": "ALGERIA", "RegionID": 0, "Population": 34800000}
{"CountryKey": 1, "CountryName": "ARGENTINA", "RegionID": 1, "Population": 46044703}
{"CountryKey": 2, "CountryName": "BRAZIL", "RegionID": 1, "Population": 203080756}

En COPY INTO, puede asignar columnas de tabla a campos JSON específicos mediante expresiones de ruta de acceso JSON. Esta asignación permite ingerir solo los campos necesarios de los datos de origen.

COPY INTO Countries (
  CountryID '$.CountryKey', 
  CountryName '$.CountryName', 
  RegionID '$.RegionKey', 
  Population '$.Population'
)
FROM 'https://myaccount.blob.core.windows.net/myblobcontainer/folder1/countries.jsonl'
WITH (   
    FILE_TYPE = 'JSONL' 
)

G. Cargar datos especificando caracteres comodín y varios archivos

COPY INTO t1
FROM
'https://myaccount.blob.core.windows.net/myblobcontainer/folder0/*.txt',
    'https://myaccount.blob.core.windows.net/myblobcontainer/folder1'
WITH (
    FILE_TYPE = 'CSV',
    CREDENTIAL=(IDENTITY= 'Shared Access Signature', SECRET='<Your_SAS_Token>')
    FIELDTERMINATOR = '|'
)

H. Carga de datos desde OneLake

COPY INTO t1
FROM 'https://onelake.dfs.fabric.microsoft.com/<workspaceId>/<lakehouseId>/Files/*.csv'
WITH (
    FILE_TYPE = 'CSV',
    FIRSTROW = 2
);

Contenido relacionado

• Ingesta de datos en el almacén de Microsoft Fabric
• Ingesta de datos en el almacén mediante la instrucción COPY