COPY INTO (Transact-SQL)

Se aplica a: Azure Synapse Analytics

En este artículo se explica cómo usar la instrucción COPY en Azure Synapse Analytics para la carga desde cuentas de almacenamiento externo. La instrucción COPY proporciona la máxima flexibilidad para la ingesta de datos de alto rendimiento en Azure Synapse Analytics.

Nota:

Para el almacenamiento de Microsoft Fabric, visite COPY INTO.

Use COPY para las siguientes funcionalidades:

• Utilizar la carga de usuarios con menos privilegios sin necesidad de estrictos permisos de CONTROL en el almacenamiento de datos
• Ejecución de una instrucción T-SQL única sin tener que crear objetos de base de datos adicionales
• Analizar y cargar correctamente los archivos CSV donde los delimitadores (cadena, campo y fila) se escapan dentro de las columnas delimitadas por cadenas
• Especificar un modelo de permisos más preciso sin exponer las claves de la cuenta de almacenamiento mediante firmas de acceso compartido (SAS)
• Usar una cuenta de almacenamiento diferente para la ubicación de ERRORFILE (REJECTED_ROW_LOCATION)
• Personalizar los valores predeterminados de cada columna de destino y especificar los campos de datos de origen que se van a cargar en columnas de destino concretas
• Especificar un terminador de fila personalizado, un terminador de campo y una comilla de campo para los archivos CSV
• Uso de los formatos de fecha de SQL Server para archivos .csv
• Especificar 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 los datos de origen a tablas de destino
• El proceso de creación automática de tablas crea las tablas automáticamente y funciona junto con la detección automática de esquemas.
• Cargar directamente tipos de datos complejos desde archivos Parquet, como Mapas y listas en columnas de cadena, sin usar otras herramientas para preprocesar los datos

Nota:

Para cargar tipos de datos complejos desde archivos Parquet, la creación automática de tablas debe activarse mediante AUTO_CREATE_TABLE.

Consulte la documentación siguiente para obtener ejemplos completos y guías de inicio rápido con la instrucción COPY:

• 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

Nota:

Microsoft Entra ID era conocido anteriormente como Azure Active Directory (Azure AD).

Sintaxis

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' } ]
)

Argumentos

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 se especifica el esquema y el esquema predeterminado del usuario que realiza la operación COPY es diferente del esquema de la tabla especificada, se cancela COPY y se devuelve un mensaje de error.

table_name

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 Default_value] [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 en función de la posición ordinal de origen y de destino: El campo de entrada 1 va a la columna de destino 1, el campo 2 va a la columna 2, etc.

Ubicaciones externas

Es 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\>

Nota

El punto de conexión .blob también está disponible para ADLS Gen2 y actualmente ofrece el mejor rendimiento. Use el punto de conexión .blob cuando no se requiera .dfs para su método de autenticación.

• 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 se especifica una carpeta, COPY recupera todos los archivos de la carpeta y todas sus subcarpetas. COPY omite las carpetas ocultas y no devuelve los archivos que comienzan por un carácter de 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
• El carácter comodín se puede escapar 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

Nota

Para obtener el mejor rendimiento, evite especificar caracteres comodín que se expandan en un número elevado de archivos. Si es posible, enumere varias ubicaciones de archivo en lugar de especificar caracteres comodín.

Solo se pueden especificar varias ubicaciones de archivos desde el mismo contenedor y cuenta de almacenamiento a través de una lista separada por comas, por ejemplo:

• 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 conforme a la norma RFC 4180.
• PARQUET: Especifica un formato Parquet.
• ORC: Especifica un formato ORC (Optimized Row Columnar).

Nota

El tipo de archivo de “texto delimitado” en PolyBase se reemplaza por el formato de archivo “CSV” cuando el delimitador predeterminado de coma se puede configurar mediante el parámetro FIELDTERMINATOR.

FILE_FORMAT = external_file_format_name

FILE_FORMAT se aplica solo a archivos Parquet y ORC y especifica nombre del objeto de formato de archivo externo que almacena el tipo de archivo y el método de compresión de 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 tener acceso a la cuenta de almacenamiento externa. Los métodos de autenticación son:

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

1: Para este método de autenticación, se requiere el punto de conexión .blob ( .blob.core.windows.net) en la ruta de acceso a la ubicación externa.

2: Para este método de autenticación, se requiere el punto de conexión .dfs ( .dfs.core.windows.net) en la ruta de acceso a la ubicación externa.

Nota:

• Al autenticarse mediante microsoft Entra ID o en una cuenta de almacenamiento pública, no es necesario especificar CREDENTIAL.
• Si la cuenta de almacenamiento está asociada a una red virtual, debe autenticarse mediante una identidad administrada.

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

  • IDENTITY: constante con un valor de “firma de acceso compartido”
  • 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>
  • SECRETO: Clave de entidad de servicio de la 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 “clave de cuenta de almacenamiento”
  • 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 “identidad administrada”
  • 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 lista de control de acceso (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 CREDENCIAL
  • 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 de la instrucción COPY donde se deben escribir las filas rechazadas y el archivo de error correspondiente. Se puede especificar la ruta de acceso completa de la cuenta de almacenamiento o se puede especificar la ruta de acceso relativa al contenedor. Si la ruta de acceso especificada no existe, se crea una en su nombre. Se crea un directorio secundario con el nombre «_rejectedrows». El carácter «_» garantiza que se escape el directorio para otro procesamiento de datos a menos que se mencione explícitamente en el parámetro de ubicación.

Nota:

Cuando se pasa una ruta de acceso relativa a ERRORFILE, la ruta de acceso es relativa a la ruta de acceso del contenedor especificada en external_location.

En este directorio hay una carpeta que se crea según la hora de envío de la carga con el formato AñoMesDía-HoraMinutoSegundo (por ejemplo, 20180330-173205). En esta carpeta, se escriben dos tipos de archivos, el archivo de motivos (error) y el archivo de datos (fila) cada uno anexado previamente con queryID, distributionID y GUID de archivo. Como los datos y los motivos están en archivos independientes, los archivos correspondientes tienen un prefijo coincidente.

Si ERRORFILE tiene la ruta de acceso completa de la cuenta de almacenamiento definida, ERRORFILE_CREDENTIAL se usa para conectarse al 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 para ERRORFILE, también se aplican restricciones que se aplican a ERRORFILE_CREDENTIAL también se aplican

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/SERVICE PRINCIPAL/AAD

• Azure Data Lake Gen2: SAS/MSI/SERVICE PRINCIPAL/AAD

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

  • IDENTITY: constante con un valor de “firma de acceso compartido”
  • 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>
  • SECRETO: Clave de entidad de servicio de la aplicación Microsoft Entra
  • Roles de RBAC mínimos necesarios: Colaborador de datos de Storage Blob o propietario de datos de Storage Blob

Nota

Usar el punto de conexión de token de OAuth 2.0 V1

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

  • IDENTITY: constante con un valor de “identidad administrada”
  • 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

  • No se requiere CREDENCIAL
  • 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.

Nota:

Si usa la misma cuenta de almacenamiento para ERRORFILE y especifica la ruta de acceso de ERRORFILE relativa a la raíz del contenedor, no es necesario especificar ERROR_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 se especifica max_errors, 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 parquet a entero de SQL) seguirán provocando un error en COPY INTO, omindo 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 según la extensión del archivo si no se especifica este parámetro:

• .gz - GZIP
• .snappy – Snappy
• .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, producirá el error del comando COPY. Asegúrese de comprobar que no hay elementos no utilizados finales al final de los archivos gzip para asegurarse de que COPY puede procesar correctamente estos archivos.

FIELDQUOTE = 'field_quote'

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

Nota:

Los caracteres FIELDQUOTE se escapan en columnas de cadena en las que existe la presencia de un doble FIELDQUOTE (delimitador).

FIELDTERMINATOR = 'field_terminator'

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

ROW TERMINATOR = 'row_terminator'

ROW TERMINATOR solo se aplica a CSV. Especifica el terminador de fila que se usa en el archivo CSV. El terminador de fila se puede especificar mediante notación hexadecimal. El terminador de fila puede ser de varios caracteres. 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 los terminadores de fila de varios caracteres en formato hexadecimal, no especifique 0x entre cada carácter.

Los caracteres ASCII y multi byte extendidos no se admiten con UTF-8 para ROW TERMINATOR.

FIRSTROW = First_row_int

FIRSTROW se aplica a CSV y especifica el número de fila que se lee primero en todos los archivos para el comando COPY. Los valores se inician a partir de 1, que es el valor predeterminado. Si el valor se establece en dos, se omite la primera fila de cada archivo (fila de encabezado) al cargar 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 o los valores de identidad del archivo de datos importado se van a utilizar para la columna de identidad. Si IDENTITY_INSERT está desactivado (OFF, valor predeterminado), se comprueban los valores de identidad de esta columna, pero no se importan. 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. Tenga en cuenta el siguiente comportamiento con el comando COPY:

• Si IDENTITY_INSERT es OFF y la tabla tiene una columna de identidad
  • Se debe especificar una lista de columnas que no asigne un campo de entrada a la columna de identidad.
• Si IDENTITY_INSERT está activado y la tabla tiene una columna de identidad
  • Si se pasa una lista de columnas, debe asignar un campo de entrada a la columna de identidad.
• No se admite el valor predeterminado para IDENTITY COLUMN en la lista de columnas.
• IDENTITY_INSERT solo se puede establecer para una tabla cada vez.

AUTO_CREATE_TABLE = { 'ON' | 'OFF' }

AUTO_CREATE_TABLE especifica si la tabla se podría crear automáticamente trabajando junto con la detección automática de esquemas. Solo está disponible para archivos de Parquet.

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

Nota

La creación automática de tablas funciona junto con la detección automática de esquemas. La creación automática de tablas NO está habilitada de forma predeterminada.

No lo cargue en tablas distribuidas por hash desde archivos de Parquet mediante COPY INTO con AUTO_CREATE_TABLE = "ON".

Si los archivos de Parquet se van a cargar en tablas distribuidas por hash mediante COPY INTO, cárguelo en una tabla de almacenamiento provisional round robin seguida de INSERT ... SELECT de esa tabla a la tabla distribuida por hash de destino.

Permisos

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

• ADMINISTER DATABASE BULK OPERATIONS
• 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];

Comentarios

La instrucción COPY solo acepta caracteres válidos UTF-8 y UTF-16 para los parámetros de comando y datos de fila. Los archivos o parámetros de origen (como ROW TERMINATOR o FIELD TERMINATOR) que usan caracteres no válidos pueden interpretarse incorrectamente por la instrucción COPY y provocar resultados inesperados como daños en los datos u otros errores. Asegúrese de que los archivos de origen y los parámetros son compatibles con UTF-8 o UTF-16 antes de invocar la instrucción COPY.

Ejemplos

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

El ejemplo siguiente es la forma más sencilla del comando COPY, que carga datos desde una cuenta de almacenamiento pública. En este ejemplo, los valores predeterminados de la instrucción COPY 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 = DATEFORMAT de la sesión

• MAXERRORS = 0

• COMPRESSION = descomprimido

• FIELDQUOTE = '"'

• FIELDTERMINATOR = ','

• ROWTERMINATOR = '\n'

Importante

Internamente, COPY trata \n como si fuera \r\n. Para más información, vea la sección ROWTERMINATOR.

• 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 el avance de línea 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>'),
    --CREDENTIAL should look something like this:
    --CREDENTIAL=(IDENTITY= 'Storage Account Key', SECRET='x6RWv4It5F2msnjelv3H4DA80n0PQW0daPdw43jM0nyetx4c6CpDkdj3986DX5AHFMIf/YN4y6kkCnU8lb+Wx0Pj+6MDw=='),
    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'
)

Preguntas más frecuentes

¿Cuál es el rendimiento del comando COPY en comparación con PolyBase?

El comando COPY tiene un mejor rendimiento en función de la carga de trabajo.

• Los archivos comprimidos no se pueden dividir automáticamente. Para obtener el mejor rendimiento, considere la posibilidad de dividir la entrada en varios archivos al cargar archivos .csv comprimidos.

• Los archivos .csv grandes sin comprimir se pueden dividir y cargar en paralelo automáticamente, por lo que no es necesario dividir manualmente archivos .csv sin comprimir en la mayoría de los casos. 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 archivos .csv de gran tamaño puede seguir favoreciendo el rendimiento.

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

Las instrucciones sobre el número de archivos se describen en la tabla siguiente. Una vez alcanzado el número recomendado de archivos, obtendrá un mejor rendimiento cuanto mayor tamaño tengan estos. El número de archivos viene determinado por el número de nodos de proceso multiplicado por 60. Por ejemplo, en 6000DWU hay 12 nodos de proceso y 12*60 = 720 particiones. Para obtener una experiencia sencilla de división de archivos, consulte Procedimiento para maximizar el rendimiento de carga de COPY con divisiones de archivos.

DWU	Número de archivos
100	60
200	60
300	60
400	60
500	60
1,000	120
1500	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 los archivos ORC o Parquet porque el comando COPY lo hace de forma automática. Para obtener el mejor rendimiento, los archivos Parquet y ORC de la cuenta de almacenamiento de Azure deben tener un tamaño 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 cuanto al número o tamaño de los archivos. Sin embargo, para obtener el mejor rendimiento, se recomienda usar archivos que tengan al menos 4 MB.

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

Si tiene un área de trabajo de Azure Synapse que ha creado antes del 7 de diciembre de 2020, es posible que aparezca un mensaje de error similar al autenticarse con una identidad administrada: com.microsoft.sqlserver.jdbc.SQLServerException: Managed Service Identity has not been enabled on this server. Please enable Managed Service Identity and try again.

Siga estos pasos para solucionar este problema volviendo 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