INSERÇÃO A GRANEL (Transact-SQL)

Artigo
02/21/2025

Aplica-se a:SQL Server Banco de Dados SQL do Azure Instância Gerenciada SQL do Azure

Importa um arquivo de dados para uma tabela ou exibição de banco de dados em um formato especificado pelo usuário no SQL Server.

Transact-SQL convenções de sintaxe

Sintaxe

BULK INSERT
   { database_name.schema_name.table_or_view_name | schema_name.table_or_view_name | table_or_view_name }
      FROM 'data_file'
     [ WITH
    (
   [ [ , ] DATA_SOURCE = 'data_source_name' ]

   -- text formatting options
   [ [ , ] CODEPAGE = { 'RAW' | 'code_page' | 'ACP' | 'OEM' } ]
   [ [ , ] DATAFILETYPE = { 'char' | 'native' | 'widechar' | 'widenative' } ]
   [ [ , ] ROWTERMINATOR = 'row_terminator' ]
   [ [ , ] FIELDTERMINATOR = 'field_terminator' ]
   [ [ , ] FORMAT = 'CSV' ]
   [ [ , ] FIELDQUOTE = 'quote_characters']

   [ [ , ] FIRSTROW = first_row ]
   [ [ , ] LASTROW = last_row ]

   -- input file format options
   [ [ , ] FORMATFILE = 'format_file_path' ]
   [ [ , ] FORMATFILE_DATA_SOURCE = 'data_source_name' ]

   -- error handling options
   [ [ , ] MAXERRORS = max_errors ]
   [ [ , ] ERRORFILE = 'file_name' ]
   [ [ , ] ERRORFILE_DATA_SOURCE = 'errorfile_data_source_name' ]

   -- database options
   [ [ , ] KEEPIDENTITY ]
   [ [ , ] KEEPNULLS ]
   [ [ , ] FIRE_TRIGGERS ]
   [ [ , ] CHECK_CONSTRAINTS ]
   [ [ , ] TABLOCK ]

   -- source options
   [ [ , ] ORDER ( { column [ ASC | DESC ] } [ ,...n ] ) ]
   [ [ , ] ROWS_PER_BATCH = rows_per_batch ]
   [ [ , ] KILOBYTES_PER_BATCH = kilobytes_per_batch 
   [ [ , ] BATCHSIZE = batch_size ]

    )]

Argumentos

A declaração BULK INSERT tem diferentes argumentos e opções em diferentes plataformas. As diferenças estão resumidas na tabela a seguir:

Funcionalidade	Servidor SQL	Banco de Dados SQL do Azure e Instância Gerenciada SQL do Azure	Armazém de dados de malha
Fonte de dados	Caminho local, caminho de rede (UNC) ou Armazenamento do Azure	Armazenamento do Azure	Armazenamento do Azure
Autenticação de origem	Autenticação do Windows, SAS	ID do Microsoft Entra, token SAS, identidade gerenciada	Microsoft Entra ID
Opções não suportadas	`*` curingas no caminho	`*` curingas no caminho	`DATA_SOURCE`, `FORMATFILE_DATA_SOURCE`, `ERRORFILE`, `ERRORFILE_DATA_SOURCE`
Opções ativadas, mas sem efeito			`KEEPIDENTITY`, `FIRE_TRIGGERS`, `CHECK_CONSTRAINTS`, `TABLOCK`, `ORDER`, `ROWS_PER_BATCH`, `KILOBYTES_PER_BATCH`e `BATCHSIZE` não são aplicáveis. Eles não lançarão um erro de sintaxe, mas não terão qualquer efeito

Observação

A instrução BULK INSERT está em visualização no Fabric Data Warehouse.

database_name

O nome do banco de dados no qual a tabela ou exibição especificada reside. Se não for especificado, database_name é o banco de dados atual.

schema_name

Especifica o nome da tabela ou esquema de exibição. schema_name é opcional se o esquema padrão para o usuário que executa a operação de importação em massa for o esquema da tabela ou exibição especificada. Se de esquema não for especificado e o esquema padrão do usuário que executa a operação de importação em massa for diferente da tabela ou exibição especificada, o SQL Server retornará uma mensagem de erro e a operação de importação em massa será cancelada.

table_name

Especifica o nome da tabela ou exibição para a qual importar dados em massa. Somente modos de exibição em que todas as colunas se referem à mesma tabela base podem ser usados. Para obter mais informações sobre as restrições para carregar dados em modos de exibição, consulte INSERT (Transact-SQL).

DE 'data_file'

Especifica o caminho completo do arquivo de dados que contém dados a serem importados para a tabela ou exibição especificada. BULK INSERT pode importar dados de um disco ou do Armazenamento de Blobs do Azure (incluindo rede, disquete, disco rígido e assim por diante).

BULK INSERT bing_covid_19_data
FROM 'C:\\bing_covid-19_data\public\curated\covid-19\latest\bing_covid-19_data.csv';

data_file deve especificar um caminho válido do servidor no qual o SQL Server está sendo executado. Se data_file for um arquivo remoto, especifique o nome UNC (Convenção Universal de Nomenclatura). Um nome UNC tem a forma \\SystemName\ShareName\Path\FileName. Por exemplo:

BULK INSERT bing_covid_19_data
FROM '\\ShareX\bing_covid-19_data\public\curated\covid-19\latest\bing_covid-19_data.csv';

A Base de Dados SQL do Azure e o Fabric Warehouse suportam apenas a leitura a partir do Armazenamento de Blobs do Azure.

A partir do SQL Server 2017 (14.x), o data_file pode estar no Armazenamento de Blobs do Azure. Nesse caso, você precisa especificar data_source_name opção também. Para obter um exemplo, consulte Importar dados de um arquivo no Armazenamento de Blobs do Azure.

O Fabric Warehouse suporta dois estilos de caminho diferentes para especificar o caminho de origem:

https://<storage account>.blob.core.windows.net/<container name>/<path to file>
abfss://<container name>@<storage account>.dfs.core.windows.net/<path to file>

O Fabric Warehouse oferece suporte a curingas * que podem corresponder a qualquer caractere no URI e permitem que você defina um padrão de URI para os arquivos que devem ser importados. Por exemplo:

BULK INSERT bing_covid_19_data
FROM 'https://pandemicdatalake.blob.core.windows.net/public/curated/covid-19/bing_covid-19_data/latest/*.csv';

BATCHSIZE = batch_size

Especifica o número de linhas em um lote. Cada lote é copiado para o servidor como uma transação. Se isso falhar, o SQL Server confirmará ou reverterá a transação para cada lote. Por padrão, todos os dados no arquivo de dados especificado são um lote. Para obter informações sobre considerações de desempenho, consulte Considerações de desempenho mais adiante neste artigo.

CHECK_CONSTRAINTS

Especifica que todas as restrições na tabela ou exibição de destino devem ser verificadas durante a operação de importação em massa. Sem a opção CHECK_CONSTRAINTS, todas as restrições CHECK e FOREIGN KEY são ignoradas e, após a operação, a restrição na tabela é marcada como não confiável.

As restrições UNIQUE e PRIMARY KEY são sempre impostas. Ao importar para uma coluna de caracteres definida com uma restrição NOT NULL, BULK INSERT insere uma cadeia de caracteres em branco quando não há nenhum valor no arquivo de texto.

Em algum momento, você deve examinar as restrições em toda a mesa. Se a tabela não estava vazia antes da operação de importação em massa, o custo de revalidação da restrição pode exceder o custo da aplicação de restrições CHECK aos dados incrementais.

Uma situação em que você pode querer restrições desabilitadas (o comportamento padrão) é se os dados de entrada contiverem linhas que violam restrições. Com as restrições CHECK desabilitadas, você pode importar os dados e, em seguida, usar instruções Transact-SQL para remover os dados inválidos.

Observação

A opção MAXERRORS não se aplica à verificação de restrições.

CODEPAGE = { 'ACP' | 'OEM' | 'CRU' | 'code_page' }

Especifica a página de código dos dados no arquivo de dados. CODEPAGE só é relevante se os dados contiverem char, varcharou texto colunas com valores de caracteres superiores 127 ou inferiores a 32. Para obter um exemplo, consulte Especificar uma página de código.

CODEPAGE não é uma opção suportada no Linux para SQL Server 2017 (14.x). Para o SQL Server 2019 (15.x), apenas a opção de 'RAW' é permitida para CODEPAGE.

Você deve especificar um nome de agrupamento para cada coluna em um arquivo de formato .

Valor CODEPAGE	Descrição
ACP	Colunas de char , varcharou texto tipo de dados são convertidas da página de código ANSI/Microsoft Windows (ISO 1252) para a página de código do SQL Server.
OEM (padrão)	Colunas de char , varcharou texto tipo de dados são convertidas da página de código OEM do sistema para a página de código do SQL Server.
CRU	Nenhuma conversão de uma página de código para outra ocorre. RAW é a opção mais rápida.
code_page	Número de página de código específico, por exemplo, 850. As versões anteriores ao SQL Server 2016 (13.x) não oferecem suporte à página de código 65001 (codificação UTF-8).

DATAFILETYPE = { 'char' | 'nativo' | 'Widechar' | 'widenative' }

Especifica que BULK INSERT executa a operação de importação usando o valor de tipo de arquivo de dados especificado.

Valor DATAFILETYPE	Todos os dados representados em:
char (padrão)	Formato do caractere. Para obter mais informações, consulte Usar formato de caractere para importar ou exportar dados (SQL Server).
nativo	Tipos de dados nativos (banco de dados). Crie o arquivo de dados nativo importando dados em massa do SQL Server usando o utilitário bcp. O valor nativo oferece uma alternativa de desempenho mais alto ao valor char. O formato nativo é recomendado quando você transfere dados em massa entre várias instâncias do SQL Server usando um arquivo de dados que não contém caracteres DBCS (conjunto de caracteres estendidos/de byte duplo). Para obter mais informações, consulte Usar formato nativo para importar ou exportar dados (SQL Server).
widechar	Caracteres Unicode. Para obter mais informações, consulte Usar o formato de caractere Unicode para importar ou exportar dados (SQL Server).
widenative	Tipos de dados nativos (banco de dados), exceto em char, varchare colunas de de texto, nas quais os dados são armazenados como Unicode. Crie o arquivo de dados de widenative importando dados em massa do SQL Server usando o utilitário bcp. O valor de widenative oferece uma alternativa de maior desempenho para widechar. Se o arquivo de dados contiver caracteres ANSI estendidos, especifique widenative. Para obter mais informações, consulte Usar o formato nativo Unicode para importar ou exportar dados (SQL Server).

DATA_SOURCE = 'data_source_name'

Aplica-se a: SQL Server 2017 (14.x) e Banco de Dados SQL do Azure.

Especifica uma fonte de dados externa nomeada apontando para o local do Armazenamento de Blobs do Azure do arquivo que será importado. A fonte de dados externa deve ser criada usando a opção TYPE = BLOB_STORAGE adicionada no SQL Server 2017 (14.x). Para obter mais informações, consulte CREATE EXTERNAL DATA SOURCE. Para obter um exemplo, consulte Importar dados de um arquivo no Armazenamento de Blobs do Azure.

CREATE EXTERNAL DATA SOURCE pandemicdatalake
WITH (LOCATION='https://pandemicdatalake.blob.core.windows.net/public/',TYPE=BLOB_STORAGE)
GO
BULK INSERT bing_covid_19_data
FROM 'curated/covid-19/bing_covid-19_data/latest/bing_covid-19_data.csv'
WITH (DATA_SOURCE='pandemicdatalake',FIRSTROW = 2,LASTROW = 100,FIELDTERMINATOR = ',');

ERRORFILE = 'error_file_path'

Especifica o arquivo usado para coletar linhas com erros de formatação e que não podem ser convertidas em um conjunto de linhas OLE DB. Essas linhas são copiadas para este arquivo de erro do arquivo de dados "como está".

O arquivo de erro é criado quando o comando é executado. Ocorrerá um erro se o ficheiro já existir. Além disso, um arquivo de controle que tem a extensão .ERROR.txt é criado, que faz referência a cada linha no arquivo de erro e fornece diagnóstico de erro. Assim que os erros forem corrigidos, os dados podem ser carregados.

A partir do SQL Server 2017 (14.x), o error_file_path pode estar no Armazenamento de Blobs do Azure.

ERRORFILE_DATA_SOURCE = 'errorfile_data_source_name'

Aplica-se a: SQL Server 2017 (14.x).

Especifica uma fonte de dados externa nomeada apontando para o local do Armazenamento de Blobs do Azure do arquivo de erro que conterá erros encontrados durante a importação. A fonte de dados externa deve ser criada usando a opção TYPE = BLOB_STORAGE adicionada no SQL Server 2017 (14.x). Para obter mais informações, consulte CREATE EXTERNAL DATA SOURCE.

PRIMEIRA LINHA = first_row

Especifica o número da primeira linha a ser carregada. O padrão é a primeira linha no arquivo de dados especificado. FIRSTROW é baseado em 1.

O atributo FIRSTROW não se destina a ignorar cabeçalhos de coluna. Ignorar cabeçalhos não é suportado pela instrução BULK INSERT. Se você optar por ignorar linhas, o Mecanismo de Banco de Dados do SQL Server examinará apenas os terminadores de campo e não validará os dados nos campos de linhas ignoradas.

FIRE_TRIGGERS

Especifica que todos os gatilhos de inserção definidos na tabela de destino são executados durante a operação de importação em massa. Se os gatilhos forem definidos para operações INSERT na tabela de destino, eles serão disparados para cada lote concluído.

Se FIRE_TRIGGERS não for especificado, nenhum gatilho de inserção será executado.

FORMATFILE_DATA_SOURCE = 'data_source_name'

Aplica-se a: SQL Server 2017 (14.x).

Especifica uma fonte de dados externa nomeada apontando para o local do Armazenamento de Blobs do Azure do arquivo de formato que definirá o esquema de dados importados. A fonte de dados externa deve ser criada usando a opção TYPE = BLOB_STORAGE adicionada no SQL Server 2017 (14.x). Para obter mais informações, consulte CREATE EXTERNAL DATA SOURCE.

MANTERIDENTIDADE

Especifica que o valor ou valores de identidade no arquivo de dados importado devem ser usados para a coluna de identidade. Se KEEPIDENTITY não for especificado, os valores de identidade para esta coluna serão verificados, mas não importados, e o SQL Server atribuirá automaticamente valores exclusivos com base nos valores seed e increment especificados durante a criação da tabela. Se o arquivo de dados não contiver valores para a coluna de identidade na tabela ou exibição, use um arquivo de formato para especificar que a coluna de identidade na tabela ou exibição deve ser ignorada ao importar dados; O SQL Server atribui automaticamente valores exclusivos para a coluna. Para obter mais informações, consulte DBCC CHECKIDENT (Transact-SQL).

Para obter mais informações, consulte Sobre como manter valores de identificação, consulte Manter valores de identidade ao importar dados em massa (SQL Server).

KEEPNULLS

Especifica que as colunas vazias devem manter um valor nulo durante a operação de importação em massa, em vez de ter quaisquer valores padrão para as colunas inseridas. Para obter mais informações, consulte manter nulos ou usar valores padrão durante a importação em massa (SQL Server).

KILOBYTES_PER_BATCH = kilobytes_per_batch

Especifica o número aproximado de kilobytes (KB) de dados por lote como kilobytes_per_batch. Por padrão, KILOBYTES_PER_BATCH é desconhecido. Para obter informações sobre considerações de desempenho, consulte Considerações de desempenho mais adiante neste artigo.

ÚLTIMA LINHA = last_row

Especifica o número da última linha a ser carregada. O padrão é 0, que indica a última linha no arquivo de dados especificado.

MAXERRORS = max_errors

Especifica o número máximo de erros de sintaxe permitidos nos dados antes que a operação de importação em massa seja cancelada. Cada linha que não pode ser importada pela operação de importação em massa é ignorada e contada como um erro. Se max_errors não for especificado, o padrão será 10.

A opção MAX_ERRORS não se aplica a verificações de restrição ou à conversão de de dinheiro e tipos de dados bigint.

ORDER ( { coluna [ ASC | DESC ] } [ ,... n ] )

Especifica como os dados no arquivo de dados são classificados. O desempenho da importação em massa será melhorado se os dados que estão sendo importados forem classificados de acordo com o índice clusterizado na tabela, se houver. Se o arquivo de dados for classificado em uma ordem diferente da ordem de uma chave de índice clusterizada, ou se não houver nenhum índice clusterizado na tabela, a cláusula ORDER será ignorada. Os nomes de coluna fornecidos devem ser nomes de coluna válidos na tabela de destino. Por padrão, a operação de inserção em massa pressupõe que o arquivo de dados não está ordenado. Para importação em massa otimizada, o SQL Server também valida se os dados importados estão classificados.

n é um espaço reservado que indica que várias colunas podem ser especificadas.

ROWS_PER_BATCH = rows_per_batch

Indica o número aproximado de linhas de dados no arquivo de dados.

Por padrão, todos os dados no arquivo de dados são enviados ao servidor como uma única transação e o número de linhas no lote é desconhecido para o otimizador de consulta. Se você especificar ROWS_PER_BATCH (com um valor > 0), o servidor usará esse valor para otimizar a operação de importação em massa. O valor especificado para ROWS_PER_BATCH deve ser aproximadamente o mesmo que o número real de linhas. Para obter informações sobre considerações de desempenho, consulte Considerações de desempenho mais adiante neste artigo.

TABLOCK

Especifica que um bloqueio no nível da tabela é adquirido durante a operação de importação em massa. Uma tabela pode ser carregada simultaneamente por vários clientes se a tabela não tiver índices e TABLOCK for especificado. Por padrão, o comportamento de bloqueio é determinado pela opção de tabela bloqueio de tabela emde carga em massa. Segurar um bloqueio durante a operação de importação em massa reduz a contenção de bloqueio na mesa, em alguns casos pode melhorar significativamente o desempenho. Para obter informações sobre considerações de desempenho, consulte Considerações de desempenho mais adiante neste artigo.

Para um índice columnstore, o comportamento de bloqueio é diferente porque é dividido internamente em vários conjuntos de linhas. Cada thread carrega dados exclusivamente em cada conjunto de linhas, obtendo um bloqueio X no conjunto de linhas, permitindo o carregamento de dados paralelo com sessões de carregamento de dados simultâneas. O uso da opção TABLOCK fará com que o thread tenha um bloqueio X na tabela (ao contrário do bloqueio BU para conjuntos de linhas tradicionais), o que impedirá que outros threads simultâneos carreguem dados simultaneamente.

Opções de formato de arquivo de entrada

FORMATO = 'CSV'

Aplica-se a: SQL Server 2017 (14.x).

Especifica um arquivo de valores separados por vírgulas compatível com o padrão de RFC 4180.

BULK INSERT Sales.Orders
FROM '\\SystemX\DiskZ\Sales\data\orders.csv'
WITH ( FORMAT = 'CSV');

FIELDQUOTE = 'field_quote'

Aplica-se a: SQL Server 2017 (14.x).

Especifica um caractere que será usado como o caractere de aspas no arquivo CSV. Se não for especificado, o caractere de cotação (") será usado como o caractere de cotação, conforme definido no padrão de RFC 4180.

FORMATFILE = 'format_file_path'

Especifica o caminho completo de um arquivo de formato. Um arquivo de formato descreve o arquivo de dados que contém respostas armazenadas criadas usando o utilitário bcp na mesma tabela ou exibição. O ficheiro de formato deve ser utilizado se:

O arquivo de dados contém mais ou menos colunas do que a tabela ou exibição.
As colunas estão em uma ordem diferente.
Os delimitadores de coluna variam.
Há outras alterações no formato de dados. Os arquivos de formato são normalmente criados usando o utilitário bcp e modificados com um editor de texto, conforme necessário. Para obter mais informações, consulte do utilitário bcp e Criar um arquivo de formato.

A partir do SQL Server 2017 (14.x) e no Banco de Dados SQL do Azure, format_file_path pode estar no Armazenamento de Blobs do Azure.

FIELDTERMINATOR = 'field_terminator'

Especifica o terminador de campo a ser usado para char e widechar arquivos de dados. O terminador de campo padrão é \t (caractere de tabulação). Para obter mais informações, consulte Especificar terminadores de campo e linha (SQL Server).

ROWTERMINATOR = 'row_terminator'

Especifica o terminador de linha a ser usado para char e widechar arquivos de dados. O terminador de linha padrão é \r\n (caractere de nova linha). Para obter mais informações, consulte Especificar terminadores de campo e linha (SQL Server).

Compatibilidade

BULK INSERT impõe validação de dados rigorosa e verificações de dados de dados lidos de um arquivo que podem fazer com que scripts existentes falhem quando são executados em dados inválidos. Por exemplo, BULK INSERT verifica que:

As representações nativas de flutuante ou tipos de dados reais são válidas.
Os dados Unicode têm um comprimento de byte par.

Tipos de dados

Conversões de tipo de dados de cadeia de caracteres para decimais

As conversões de tipo de dados string-to-decimal usadas em BULK INSERT seguem as mesmas regras que a função Transact-SQL CONVERT, que rejeita cadeias de caracteres que representam valores numéricos que usam notação científica. Portanto, BULK INSERT trata essas cadeias de caracteres como valores inválidos e relata erros de conversão.

Para contornar esse comportamento, use um arquivo de formato para importar em massa notação científica flutuar dados em uma coluna decimal. No arquivo de formato, descreva explicitamente a coluna como real ou flutuar dados. Para obter mais informações sobre esses tipos de dados, consulte float e real (Transact-SQL).

Os arquivos de formato representam dados reais como o tipo de dados SQLFLT4 e flutuam dados como o tipo de dados SQLFLT8. Para obter informações sobre arquivos de formato não-XML, consulte especificar o tipo de armazenamento de arquivo usando bcp (SQL Server).

Exemplo de importação de um valor numérico que usa notação científica

Este exemplo usa a tabela a seguir no banco de dados bulktest:

CREATE TABLE dbo.t_float(c1 FLOAT, c2 DECIMAL (5,4));

O usuário deseja importar dados em massa para a tabela t_float. O arquivo de dados, C:\t_float-c.dat, contém notação científica flutuar dados; Por exemplo:

8.0000000000000002E-2 8.0000000000000002E-2

Ao copiar este exemplo, esteja ciente de diferentes editores de texto e codificações que salvam caracteres de tabulação (\t) como espaços. Um caractere de tabulação é esperado posteriormente neste exemplo.

No entanto, BULK INSERT não pode importar esses dados diretamente para t_float, porque sua segunda coluna, c2, usa o tipo de dados decimal. Portanto, um arquivo de formato é necessário. O arquivo de formato deve mapear a notação científica flutuar dados para o formato decimal da coluna c2.

O seguinte arquivo de formato usa o tipo de dados SQLFLT8 para mapear o segundo campo de dados para a segunda coluna:

<?xml version="1.0"?>
<BCPFORMAT xmlns="http://schemas.microsoft.com/sqlserver/2004/bulkload/format" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<RECORD>
<FIELD ID="1" xsi:type="CharTerm" TERMINATOR="\t" MAX_LENGTH="30"/>
<FIELD ID="2" xsi:type="CharTerm" TERMINATOR="\r\n" MAX_LENGTH="30"/> </RECORD> <ROW>
<COLUMN SOURCE="1" NAME="c1" xsi:type="SQLFLT8"/>
<COLUMN SOURCE="2" NAME="c2" xsi:type="SQLFLT8"/> </ROW> </BCPFORMAT>

Para usar esse arquivo de formato (usando o nome de arquivo C:\t_floatformat-c-xml.xml) para importar os dados de teste para a tabela de teste, emita a seguinte instrução Transact-SQL:

BULK INSERT bulktest.dbo.t_float
FROM 'C:\t_float-c.dat' WITH (FORMATFILE = 'C:\t_floatformat-c-xml.xml');

Importante

A Base de Dados SQL do Azure apenas suporta a leitura a partir do Armazenamento de Blobs do Azure.

Tipos de dados para exportação ou importação em massa de documentos SQLXML

Para exportar ou importar dados SQLXML em massa, use um dos seguintes tipos de dados em seu arquivo de formato:

Tipo de dados	Efeito
SQLCHAR ou SQLVARCHAR	Os dados são enviados na página de código do cliente ou na página de código implícita pelo agrupamento). O efeito é o mesmo que especificar o DATAFILETYPE = 'char' sem especificar um arquivo de formato.
SQLNCHAR ou SQLNVARCHAR	Os dados são enviados como Unicode. O efeito é o mesmo que especificar o `DATAFILETYPE = 'widechar'` sem especificar um arquivo de formato.
SQLBINARY ou SQLVARBIN	Os dados são enviados sem qualquer conversão.

Comentários

Para obter uma comparação da instrução BULK INSERT, da instrução INSERT ... SELECT * FROM OPENROWSET(BULK...) e do comando bcp, consulte Bulk Import and Export of Data.

Para obter informações sobre como preparar dados para importação em massa, consulte Preparar dados para exportação em massa ou importação.

A instrução BULK INSERT pode ser executada dentro de uma transação definida pelo usuário para importar dados para uma tabela ou exibição. Opcionalmente, para usar várias correspondências para importação em massa de dados, uma transação pode especificar a cláusula BATCHSIZE na instrução BULK INSERT. Se uma transação de vários lotes for revertida, cada lote que a transação enviou para o SQL Server será revertida.

Interoperabilidade

Importar dados de um arquivo CSV

A partir do SQL Server 2017 (14.x), BULK INSERT dá suporte ao formato CSV, assim como o Banco de Dados SQL do Azure.

Antes do SQL Server 2017 (14.x), os arquivos CSV (valores separados por vírgula) não eram suportados por operações de importação em massa do SQL Server. No entanto, em alguns casos, um arquivo CSV pode ser usado como o arquivo de dados para uma importação em massa de dados para o SQL Server. Para obter informações sobre os requisitos para importar dados de um arquivo de dados CSV, consulte Preparar dados para exportação ou importação em massa (SQL Server).

Comportamento de log

Para obter informações sobre quando as operações de inserção de linha executadas por importação em massa para o SQL Server são registradas no log de transações, consulte Pré-requisitos para registro em log mínimo na importação em massa. Não há suporte para o log mínimo no Banco de Dados SQL do Azure.

Restrições

Ao usar um arquivo de formato com BULK INSERT, você pode especificar apenas até 1024 campos. Isso é o mesmo que o número máximo de colunas permitido em uma tabela. Se você usar um arquivo de formato com BULK INSERT com um arquivo de dados que contém mais de 1024 campos, BULK INSERT gerará o erro 4822. O utilitário bcp não tem essa limitação, portanto, para arquivos de dados que contêm mais de 1024 campos, use BULK INSERT sem um arquivo de formato ou use o comando bcp.

Considerações sobre desempenho

Se o número de páginas a serem liberadas em um único lote exceder um limite interno, poderá ocorrer uma verificação completa do pool de buffers para identificar quais páginas serão liberadas quando o lote for confirmado. Essa verificação completa pode prejudicar o desempenho da importação em massa. Um caso provável de exceder o limite interno ocorre quando um grande pool de buffers é combinado com um subsistema de E/S lento. Para evitar estouros de buffer em máquinas grandes, não use a dica TABLOCK (que removerá as otimizações em massa) ou use um tamanho de lote menor (que preserva as otimizações em massa).

Você deve testar vários tamanhos de lote com sua carga de dados para descobrir o que funciona melhor para você. Lembre-se de que o tamanho do lote tem implicações de reversão parcial. Se o processo falhar e antes de usar BULK INSERT novamente, talvez seja necessário fazer trabalho manual adicional para remover uma parte das linhas que foram inseridas com êxito, antes que ocorra uma falha.

Com o Banco de Dados SQL do Azure, considere aumentar temporariamente o nível de desempenho do banco de dados ou da instância antes da importação se estiver importando um grande volume de dados.

Segurança

Delegação de conta de segurança (falsificação de identidade)

Se um usuário usar um logon do SQL Server, o perfil de segurança da conta de processo do SQL Server será usado. Um logon usando a autenticação do SQL Server não pode ser autenticado fora do Mecanismo de Banco de Dados. Portanto, quando um comando BULK INSERT é iniciado por um logon usando a autenticação do SQL Server, a conexão com os dados é feita usando o contexto de segurança da conta de processo do SQL Server (a conta usada pelo serviço Mecanismo de Banco de Dados do SQL Server).

Para ler com êxito os dados de origem, você deve conceder à conta usada pelo Mecanismo de Banco de Dados do SQL Server, acesso aos dados de origem. Por outro lado, se um usuário do SQL Server fizer logon usando a Autenticação do Windows, o usuário poderá ler somente os arquivos que podem ser acessados pela conta de usuário, independentemente do perfil de segurança do processo do SQL Server.

Ao executar a instrução BULK INSERT usando sqlcmd ou osql, de um computador, inserindo dados no SQL Server em um segundo computador e especificando um data_file no terceiro computador usando um caminho UNC, você pode receber um erro 4861.

Para resolver esse erro, use a Autenticação do SQL Server e especifique um logon do SQL Server que use o perfil de segurança da conta de processo do SQL Server ou configure o Windows para habilitar a delegação de conta de segurança. Para obter informações sobre como habilitar uma conta de usuário confiável para delegação, consulte a Ajuda do Windows.

Para obter mais informações sobre essa e outras considerações de segurança para usar BULK INSERT, consulte Importar dados em massa usando BULK INSERT ou OPENROWSET(BULK...) (SQL Server).

Ao importar do Armazenamento de Blobs do Azure e os dados não forem públicos (acesso anônimo), crie uma CREDENCIAL COM ESCOPO DE BANCO DE DADOS baseada em uma chave SAS criptografada com uma CHAVE MESTRAe, em seguida, crie um de origem de banco de dados externo para uso no comando BULK INSERT.

Como alternativa, crie um DE CREDENCIAIS COM ESCOPO DE BANCO DE DADOS com base em MANAGED IDENTITY autorizar solicitações de acesso a dados em contas de armazenamento não públicas. Ao usar MANAGED IDENTITY, o armazenamento do Azure deve conceder permissões à identidade gerenciada da instância adicionando o Colaborador de Dados de Blob de Armazenamento função RBAC (controle de acesso baseado em função) interna do Azure que fornece acesso de leitura/gravação à identidade gerenciada para os contêineres de Armazenamento de Blob do Azure necessários. A Instância Gerenciada SQL do Azure tem uma identidade gerenciada atribuída ao sistema e também pode ter uma ou mais identidades gerenciadas atribuídas pelo usuário. Você pode usar identidades gerenciadas atribuídas pelo sistema ou identidades gerenciadas atribuídas pelo usuário para autorizar as solicitações. Para autorização, a identidade default da instância gerenciada seria usada (ou seja, a identidade gerenciada atribuída pelo usuário principal ou a identidade gerenciada atribuída ao sistema se a identidade gerenciada atribuída pelo usuário não for especificada). Para obter um exemplo, consulte Importar dados de um arquivo no Armazenamento de Blobs do Azure.

Importante

A Identidade Gerenciada é aplicável somente ao SQL do Azure. O SQL Server não oferece suporte à Identidade Gerenciada.

Permissões

Requer as permissões INSERT e ADMINISTER BULK OPERATIONS. No Banco de Dados SQL do Azure, as permissões INSERT e ADMINISTER DATABASE BULK OPERATIONS são necessárias. As permissões ADMINISTER BULK OPERATIONS ou a função bulkadmin não têm suporte para o SQL Server no Linux. Somente o sysadmin pode executar inserções em massa para o SQL Server no Linux.

Além disso, a permissão ALTER TABLE é necessária se uma ou mais das seguintes condições forem verdadeiras:

Existem restrições e a opção CHECK_CONSTRAINTS não é especificada.

Desabilitar restrições é o comportamento padrão. Para verificar as restrições explicitamente, use a opção CHECK_CONSTRAINTS.
Existem gatilhos e a opção FIRE_TRIGGER não é especificada.

Por padrão, os gatilhos não são acionados. Para disparar gatilhos explicitamente, use a opção FIRE_TRIGGER.
Use a opção KEEPIDENTITY para importar o valor de identidade do arquivo de dados.

Exemplos

Um. Usar pipes para importar dados de um arquivo

O exemplo a seguir importa informações de detalhes da ordem para a tabela AdventureWorks2022.Sales.SalesOrderDetail do arquivo de dados especificado usando um pipe (|) como o terminador de campo e |\n como o terminador de linha.

BULK INSERT AdventureWorks2022.Sales.SalesOrderDetail
   FROM 'f:\orders\lineitem.tbl'
   WITH
      (
         FIELDTERMINATOR = ' |'
         , ROWTERMINATOR = ' |\n'
      );

Importante

A Base de Dados SQL do Azure apenas suporta a leitura a partir do Armazenamento de Blobs do Azure.

B. Use o argumento FIRE_TRIGGERS

O exemplo a seguir especifica o argumento FIRE_TRIGGERS.

BULK INSERT AdventureWorks2022.Sales.SalesOrderDetail
   FROM 'f:\orders\lineitem.tbl'
   WITH
     (
         FIELDTERMINATOR = ' |'
         , ROWTERMINATOR = ':\n'
         , FIRE_TRIGGERS
      );

Importante

A Base de Dados SQL do Azure apenas suporta a leitura a partir do Armazenamento de Blobs do Azure.

C. Usar alimentação de linha como terminador de linha

O exemplo a seguir importa um arquivo que usa o feed de linha como um terminador de linha, como uma saída UNIX:

DECLARE @bulk_cmd VARCHAR(1000);
SET @bulk_cmd = 'BULK INSERT AdventureWorks2022.Sales.SalesOrderDetail
FROM ''<drive>:\<path>\<filename>''
WITH (ROWTERMINATOR = '''+CHAR(10)+''')';
EXEC(@bulk_cmd);

Observação

Devido à forma como o Microsoft Windows trata os ficheiros de texto, \n é automaticamente substituído por \r\n.

Importante

A Base de Dados SQL do Azure apenas suporta a leitura a partir do Armazenamento de Blobs do Azure.

D. Especificar uma página de código

O exemplo a seguir mostra como especificar uma página de código.

BULK INSERT MyTable
FROM 'D:\data.csv'
WITH
( CODEPAGE = '65001'
   , DATAFILETYPE = 'char'
   , FIELDTERMINATOR = ','
);

Importante

A Base de Dados SQL do Azure apenas suporta a leitura a partir do Armazenamento de Blobs do Azure.

E. Importar dados de um arquivo CSV

O exemplo a seguir mostra como especificar um arquivo CSV, ignorando o cabeçalho (primeira linha), usando ; como terminador de campo e 0x0a como terminador de linha:

BULK INSERT Sales.Invoices
FROM '\\share\invoices\inv-2016-07-25.csv'
WITH (FORMAT = 'CSV'
      , FIRSTROW = 2
      , FIELDQUOTE = '\'
      , FIELDTERMINATOR = ';'
      , ROWTERMINATOR = '0x0a');

O exemplo a seguir mostra como especificar um arquivo CSV no formato UTF-8 (usando uma CODEPAGE de 65001), ignorando o cabeçalho (primeira linha), usando ; como terminador de campo e 0x0a como terminador de linha:

BULK INSERT Sales.Invoices
FROM '\\share\invoices\inv-2016-07-25.csv'
WITH ( CODEPAGE = '65001'
      , FORMAT = 'CSV'
      , FIRSTROW = 2
      , FIELDQUOTE = '\'
      , FIELDTERMINATOR = ';'
      , ROWTERMINATOR = '0x0a');

Importante

A Base de Dados SQL do Azure apenas suporta a leitura a partir do Armazenamento de Blobs do Azure.

F. Importar dados de um arquivo no Armazenamento de Blobs do Azure

O exemplo a seguir mostra como carregar dados de um arquivo CSV em um local de Armazenamento de Blob do Azure no qual você criou uma Assinatura de Acesso Compartilhado (SAS). O local do Armazenamento de Blobs do Azure é configurado como uma fonte de dados externa, que requer uma credencial de escopo de banco de dados usando uma chave SAS criptografada usando uma chave mestra no banco de dados do usuário.

--> Optional - a MASTER KEY is not required if a DATABASE SCOPED CREDENTIAL is not required because the blob is configured for public (anonymous) access!
CREATE MASTER KEY ENCRYPTION BY PASSWORD = 'YourStrongPassword1';
GO
--> Optional - a DATABASE SCOPED CREDENTIAL is not required because the blob is configured for public (anonymous) access!
CREATE DATABASE SCOPED CREDENTIAL MyAzureBlobStorageCredential
WITH IDENTITY = 'SHARED ACCESS SIGNATURE',
SECRET = '******srt=sco&sp=rwac&se=2017-02-01T00:55:34Z&st=2016-12-29T16:55:34Z***************';

-- NOTE: Make sure that you don't have a leading ? in SAS token, and
-- that you have at least read permission on the object that should be loaded srt=o&sp=r, and
-- that expiration period is valid (all dates are in UTC time)

CREATE EXTERNAL DATA SOURCE MyAzureBlobStorage
WITH ( TYPE = BLOB_STORAGE,
          LOCATION = 'https://****************.blob.core.windows.net/invoices'
          , CREDENTIAL = MyAzureBlobStorageCredential --> CREDENTIAL is not required if a blob is configured for public (anonymous) access!
);

BULK INSERT Sales.Invoices
FROM 'inv-2017-12-08.csv'
WITH (DATA_SOURCE = 'MyAzureBlobStorage');

O exemplo a seguir mostra como usar o comando BULK INSERT para carregar dados de um arquivo csv em um local de armazenamento de Blob do Azure usando a Identidade Gerenciada. O local de armazenamento de Blob do Azure é configurado como uma fonte de dados externa.

--> Optional - a MASTER KEY is not required if a DATABASE SCOPED CREDENTIAL is not required because the blob is configured for public (anonymous) access!
CREATE MASTER KEY ENCRYPTION BY PASSWORD = 'YourStrongPassword1';
GO
--> Optional - a DATABASE SCOPED CREDENTIAL is not required because the blob is configured for public (anonymous) access!
CREATE DATABASE SCOPED CREDENTIAL MyAzureBlobStorageCredential 
WITH IDENTITY = 'Managed Identity';
-- NOTE: Make sure you have granted Storage Bob Data Contributor RBAC on storage to provides read/write access to the managed identity for the necessary Azure Blob Storage containers.
CREATE EXTERNAL DATA SOURCE MyAzureBlobStorage
WITH ( TYPE = BLOB_STORAGE,
          LOCATION = 'https://****************.blob.core.windows.net/invoices'
          , CREDENTIAL= MyAzureBlobStorageCredential --> CREDENTIAL is not required if a blob is configured for public (anonymous) access!
);
BULK INSERT Sales.Invoices
FROM 'inv-2017-12-08.csv'
WITH (DATA_SOURCE = 'MyAzureBlobStorage');

Importante

A Identidade Gerenciada é aplicável somente ao SQL do Azure. O SQL Server não oferece suporte à Identidade Gerenciada.

Importante

O Azure SQL suporta apenas a leitura do Armazenamento de Blobs do Azure.

G. Importar dados de um arquivo no Armazenamento de Blobs do Azure e especificar um arquivo de erro

O exemplo a seguir mostra como carregar dados de um arquivo CSV em um local de Armazenamento de Blob do Azure, que foi configurado como uma fonte de dados externa, e também especifica um arquivo de erro. Você precisará de uma credencial com escopo de banco de dados usando uma assinatura de acesso compartilhado. Se estiver sendo executada no Banco de Dados SQL do Azure, a opção ERRORFILE deverá ser acompanhada por ERRORFILE_DATA_SOURCE caso contrário, a importação poderá falhar com erro de permissões. O arquivo especificado em ERRORFILE não deve existir no contêiner.

BULK INSERT Sales.Invoices
FROM 'inv-2017-12-08.csv'
WITH (
         DATA_SOURCE = 'MyAzureInvoices'
         , FORMAT = 'CSV'
         , ERRORFILE = 'MyErrorFile'
         , ERRORFILE_DATA_SOURCE = 'MyAzureInvoices');

Para obter exemplos completos de BULK INSERT, incluindo a configuração da credencial e da fonte de dados externa, consulte Exemplos de acesso em massa a dados no Armazenamento de Blobs do Azure.

Mais exemplos

Outros exemplos BULK INSERT são fornecidos nos seguintes artigos:

Partilhar via

INSERÇÃO A GRANEL (Transact-SQL)

Sintaxe

Argumentos

database_name

schema_name

table_name

DE 'data_file'

BATCHSIZE = batch_size

CHECK_CONSTRAINTS

CODEPAGE = { 'ACP' | 'OEM' | 'CRU' | 'code_page' }

DATAFILETYPE = { 'char' | 'nativo' | 'Widechar' | 'widenative' }

DATA_SOURCE = 'data_source_name'

ERRORFILE = 'error_file_path'

ERRORFILE_DATA_SOURCE = 'errorfile_data_source_name'

PRIMEIRA LINHA = first_row

FIRE_TRIGGERS

FORMATFILE_DATA_SOURCE = 'data_source_name'

MANTERIDENTIDADE

KEEPNULLS

KILOBYTES_PER_BATCH = kilobytes_per_batch

ÚLTIMA LINHA = last_row

MAXERRORS = max_errors

ORDER ( { coluna [ ASC | DESC ] } [ ,... n ] )

ROWS_PER_BATCH = rows_per_batch

TABLOCK

Opções de formato de arquivo de entrada

FORMATO = 'CSV'

FIELDQUOTE = 'field_quote'

FORMATFILE = 'format_file_path'

FIELDTERMINATOR = 'field_terminator'

ROWTERMINATOR = 'row_terminator'

Compatibilidade

Tipos de dados

Conversões de tipo de dados de cadeia de caracteres para decimais

Exemplo de importação de um valor numérico que usa notação científica

Tipos de dados para exportação ou importação em massa de documentos SQLXML

Comentários

Interoperabilidade

Importar dados de um arquivo CSV

Comportamento de log

Restrições

Considerações sobre desempenho

Segurança

Delegação de conta de segurança (falsificação de identidade)

Permissões

Exemplos

Um. Usar pipes para importar dados de um arquivo

B. Use o argumento FIRE_TRIGGERS

C. Usar alimentação de linha como terminador de linha

D. Especificar uma página de código

E. Importar dados de um arquivo CSV

F. Importar dados de um arquivo no Armazenamento de Blobs do Azure

G. Importar dados de um arquivo no Armazenamento de Blobs do Azure e especificar um arquivo de erro

Mais exemplos

Ver também

Comentários

Recursos adicionais