COPIAR EN (Transact-SQL)

Se aplica a:Azure Synapse Analytics

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/SERVICE DIRECTOR/TECLADO/Entra	SAS/KEY	SAS/KEY
Azure Data Lake Gen2	SAS/MSI/SERVICE DIRECTOR/TECLADO/Entra	SAS (blob 1 )/MSI (dfs 2 )/SERVICE PRINCIPAL/KEY/Entra	SAS (blob 1 )/MSI (dfs 2 )/SERVICE PRINCIPAL/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

  • 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

ERRORFILE = Ubicación del directorio

ERRORFILE Solo 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 = '', SECRETO = '')

ERRORFILE_CREDENTIAL solo aplica a 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 requeridos: LEER, LISTAR, ESCRIBIR, CREAR, 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 falle 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 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.

PRIMERA FILA = 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' }

DATEFORMATsolo se aplica a CSV y especifica el formato de fecha del mapeo de fechas a 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 la configuración a nivel de sesión.

CODIFICACIÓN = { '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 por defecto no está soportado para la IDENTITY columna 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 = { 'ENCENDIDO' | 'APAGADO' }

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:

• ADMINISTRAR DATABASE OPERACIONES A GRANEL
• INSERT

Requiere INSERT y ADMINISTRAR PERMISOS DE OPERACIONES MASIVAS. En Azure Synapse Analytics, necesitas INSERT y ADMINISTRAR DATABASE PERMISOS BULK OPERATIONS.

Si el usuario que ejecuta el comando COPY también quiere crear una nueva tabla y cargar datos en ella, necesita CREATE TABLE permisos de ALTERAR ON SCHEMA .

Por ejemplo, para permitir mike@contoso.com usar COPY para crear una nueva tabla en el HR esquema e insertar datos de un archivo Parquet, utilice el siguiente ejemplo 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 por defecto del COPY comando son:

• DATEFORMAT = Sesión DATEFORMAT

• MAXERRORS = 0

• COMPRESSION por defecto es sin comprimir

• FIELDQUOTE = '"'

• FIELDTERMINATOR = ','

• ROWTERMINATOR = '\n'

• FIRSTROW = 1

• ENCODING = 'UTF8'

• FILE_TYPE = 'CSV'

• IDENTITY_INSERT = 'OFF'

B. Carga de autenticación mediante 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. Carga especificando comodines y múltiples 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

Este artículo explica cómo usar la COPY instrucción en Warehouse en Microsoft Fabric para cargar desde Azure Storage y OneLake. La COPY declaración ofrece la mayor flexibilidad para la ingesta de datos de alto rendimiento en tu Warehouse en Microsoft Fabric, y es una estrategia para ingir datos en tu Warehouse en Microsoft Fabric.

En Fabric Data Warehouse, la COPY instrucción soporta formatos de archivo CSV, JSONL y PARQUET. Las fuentes de datos soportadas incluyen Azure Data Lake Storage Gen2, Azure Blob Storage y 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.

COPY INTO se ejecuta en el contexto de seguridad SQL del usuario actual. Las comprobaciones de permisos SQL y la atribución de auditoría permanecen asociadas a ese usuario. Cuando especificas CREDENTIAL = (IDENTITY = 'Workspace Identity'), la identidad del espacio de trabajo se usa solo para autorizar el acceso a los archivos fuente.

Ú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 = (IDENTITY = '' , SECRET = '') ]
 [ , 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' } ]
 [ , IDENTITY_INSERT = { '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.

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>

Caracteres comodín

Los comodines pueden incluirse en el camino:

• La coincidencia de nombres de caminos comodines es sensible a mayúsculas y minúsculas.
• Puedes escapar de un comodín usando el personaje con barra inversa (\).

Ubicaciones externas detrás del cortafuegos

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:

• Debe proporcionarse una identidad de espacio de trabajo para el espacio de trabajo de Fabric que aloja tu almacén. Para más información sobre cómo configurar una identidad de área de trabajo, consulte Identidad del área de trabajo.
• Para suplantar la identidad de Fabric Workspace, tu cuenta de Microsoft Entra ID debe ser miembro de un rol de espacio de trabajo. Los permisos de los elementos por sí solos no otorgan acceso para usar la identidad del espacio de trabajo.
• Concede acceso a los archivos subyacentes mediante control de acceso basado en roles (RBAC) de Azure o ACLs de data lake. Concede este acceso al usuario ejecutante cuando no especifiques una credencial o a la identidad del espacio de trabajo cuando especifiques la identidad del espacio de trabajo.
• 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' | 'JSON' | '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 la credencial que COPY INTO se utiliza al autorizar el acceso a la cuenta de almacenamiento externa o a la fuente de OneLake. No cambia el contexto de seguridad actual de SQL ni la identidad que ejecuta la sentencia.

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).
• Para cuentas de almacenamiento público detrás de un cortafuegos, se soportan Microsoft Entra ID e Identidad de Espacio de Trabajo.
• COPY INTOusar OneLake como fuente soporta Microsoft Entra ID y Workspace Identity.

La identidad Microsoft Entra del usuario que ejecuta es la credencial predeterminada para el acceso fuente. 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.
• Usa la identidad de Fabric Workspace
  • IDENTITY: constante con un valor de Workspace Identity.
  • SECRET: no es obligatorio.
  • La declaración continúa ejecutándose en el contexto de seguridad SQL del usuario actual. La CREDENTIAL cláusula permite COPY INTO suplantar la identidad del espacio de trabajo solo cuando se autoriza el acceso al código fuente. El usuario que ejecuta no necesita permiso directo sobre los datos fuente.
  • Para Azure Blob Storage y ADLS Gen2, busca la identidad del espacio de trabajo junto al nombre del espacio de trabajo y asigna el rol Storage Blob Data Reader en la cuenta o contenedor de almacenamiento. Para el acceso a nivel de directorio de ADLS Gen2, concede los permisos ACL requeridos.
  • Para OneLake, busque la identidad del espacio de trabajo a partir del nombre del espacio de trabajo, añádala al espacio de trabajo que contiene los datos de origen y asígnele al menos el rol de colaborador del espacio de trabajo.

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 = '', SECRETO = '')

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 requeridos: LEER, LISTAR, ESCRIBIR, CREAR, 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.

COMPRESIÓN = { 'Snappy' | 'GZIP' | 'NINGUNA'}

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.

PRIMERA FILA = 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 comando COPY tiene prioridad sobre DATEFORMAT la configuración a nivel de sesión.

CODIFICACIÓN = { '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 = { 'ENCENDIDO' | 'APAGADO' }

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.

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 (por defecto), los valores identidad de esta columna 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 por defecto no está soportado para la IDENTITY columna de la lista de columnas.
• Solo se puede establecer IDENTITY_INSERT para una tabla a la vez.

Para más información sobre IDENTITY las columnas en Fabric Data Warehouse, consulte IDENTITY las columnas en Fabric Data Warehouse.

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 nativa de identidad mediante Microsoft Entra ID o Workspace Identity

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

El requisito de permiso del plano de control depende de la credencial utilizada para el acceso fuente:

• Sin identidad de espacio de trabajo: Concede al usuario al menos el rol de espacio de trabajo Visor mediante el acceso a Gestionar, o comparte el almacén con el usuario mediante permisos de Artículo con al menos permiso de lectura. Un usuario con acceso a nivel de elemento no necesita un rol de espacio de trabajo para ejecutar COPY INTO.
• Con la identidad del espacio de trabajo: Cuando especifiques CREDENTIAL = (IDENTITY = 'Workspace Identity'), el usuario que ejecuta debe tener al menos el rol de espacio de trabajo Visor. Los permisos de elemento por sí solos no autorizan a un usuario a suplantar la identidad del espacio de trabajo.

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.

Cuando especifiques CREDENTIAL = (IDENTITY = 'Workspace Identity'), concede permiso al usuario INSERT que ejecuta en la tabla objetivo. ADMINISTER DATABASE BULK OPERATIONS No se requiere permiso cuando la identidad del espacio de trabajo se suplantó para acceder al código fuente.

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

Por ejemplo, la siguiente sentencia otorga el permiso a nivel de tabla requerido cuando el usuario ejecuta COPY INTO con Identidad de Espacio de Trabajo:

GRANT INSERT ON OBJECT::dbo.SalesOrders 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.

Permisos de fuente para la identidad del espacio de trabajo

Concede al usuario de espacio de trabajo acceso a cada ubicación de origen utilizada por COPY INTO:

• Para Azure Blob Storage y ADLS Gen2, busca la identidad del espacio de trabajo usando el nombre del espacio de trabajo y asigna el rol Storage Blob Data Reader en la cuenta o contenedor de almacenamiento. Para el acceso a nivel de directorio de ADLS Gen2, concede los permisos ACL requeridos. Asigna permisos como harías para un usuario de Microsoft Entra.
• Para OneLake, añade la identidad del espacio de trabajo al espacio que contiene los datos fuente usando el nombre del espacio de trabajo, y asigna al menos el rol de espacio de trabajo Contribuyente.

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 sentencia, asegúrate de que tus archivos fuente y parámetros cumplan 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 fuente para COPY INTO

• Al usar COPY INTO, solo se soportan Microsoft Entra ID e Fabric Workspace Identity como .CREDENTIAL No se permiten otros tipos de credenciales, como tokens 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.

• Se requieren permisos de colaborador en ambos espacios de trabajo cuando se utiliza la identidad Microsoft Entra del usuario que ejecuta. El usuario ejecutante debe tener al menos el rol de Contribuidor en el espacio de trabajo Lakehouse de origen y en el espacio de trabajo de almacén objetivo.

• Workspace Identity tiene requisitos de permisos separados. Cuando especificas CREDENTIAL = (IDENTITY = 'Workspace Identity'), la identidad del espacio de trabajo debe tener al menos el rol Contribuidor en el espacio de trabajo que contiene los datos fuente. El usuario que ejecuta no necesita acceso directo al espacio de trabajo de origen, pero debe tener al menos el rol de Visor en el espacio de trabajo destino y INSERT permisos en la tabla 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. Carga de autenticación mediante 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
);

I. Carga de datos desde ADLS Gen2 usando Fabric Workspace Identity

El siguiente ejemplo se ejecuta COPY INTO en el contexto de seguridad SQL del usuario actual e imita la identidad de Fabric Workspace para acceder a un archivo CSV en ADLS Gen2. Asigna a la identidad del espacio de trabajo el rol Storage Blob Data Reader en la cuenta de almacenamiento o contenedor de origen. El usuario que ejecuta debe tener al menos el rol INSERT y permisos del espacio de trabajo Visor en la tabla objetivo.

COPY INTO dbo.SalesOrders
FROM 'https://<storage-account>.dfs.core.windows.net/<container>/orders/*.csv'
WITH (
    FILE_TYPE = 'CSV',
    FIRSTROW = 2,
    CREDENTIAL = (IDENTITY = 'Workspace Identity')
);

J. Cargar datos desde OneLake usando Fabric Workspace Identity

El siguiente ejemplo se ejecuta COPY INTO en el contexto de seguridad SQL del usuario actual e imita la identidad del espacio de trabajo Fabric para acceder a un archivo CSV en OneLake. El usuario que ejecuta debe tener al menos el rol INSERT y permiso del espacio de trabajo Visor en la tabla objetivo, pero no necesita permiso directo sobre el archivo fuente.

COPY INTO dbo.SalesOrders
FROM 'https://onelake.dfs.fabric.microsoft.com/<workspace-id>/<item-id>/Files/orders/*.csv'
WITH (
    FILE_TYPE = 'CSV',
    FIRSTROW = 2,
    CREDENTIAL = (IDENTITY = 'Workspace Identity')
);

K. Cargar datos en IDENTITY columnas con IDENTITY_INSERT

COPY INTO las opciones anulan cualquier configuración a nivel de sesión para IDENTITY_INSERT.

COPY INTO dbo.Employees (EmployeeID 1, FirstName 2, LastName 3)
FROM 'https://myaccount.blob.core.windows.net/myblobcontainer/folder1/'
WITH (
    FILE_TYPE = 'CSV',
    IDENTITY_INSERT = 'ON'
);

Contenido relacionado

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