INSERÇÃO A GRANEL (Transact-SQL)

Aplica-se a:Servidor SQLBanco de Dados SQL do AzureInstância Gerenciada SQL do AzureArmazém no Microsoft Fabric

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' | 'widechar' | 'native' | '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	SQL Server	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	Azure Storage, One Lake
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	* Wildcards no caminho, FORMAT = 'PARQUET'	* Wildcards no caminho, FORMAT = 'PARQUET'	DATAFILETYPE = {'native' | 'widenative'}
Opções ativadas, mas sem efeito			KEEPIDENTITY, FIRE_TRIGGERS, CHECK_CONSTRAINTS, , TABLOCK, ORDERROWS_PER_BATCH, e KILOBYTES_PER_BATCHBATCHSIZE não são aplicáveis. Eles não lançam um erro de sintaxe, mas não têm qualquer efeito

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 INSERIR.

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 Azure Storage (incluindo rede, disquete, disco rígido, etc.).

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';

O Azure SQL Database e o Fabric Data Warehouse suportam a leitura de dados de URI, mas não suportam caminhos de ficheiros on-premises.

BULK INSERT bing_covid_19_data
FROM 'https://<data-lake>.blob.core.windows.net/public/curated/covid-19/bing_covid-19_data/latest/bing_covid-19_data.csv';

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

Observação

Substitua <data-lake>.blob.core.windows.net por um URL apropriado.

FONTE_DE_DADOS

Aplica-se a: SQL Server 2017 (14.x) e versões posteriores, Azure SQL Database e Warehouse no Microsoft Fabric.

Especifica uma fonte de dados externa nomeada que aponta para uma localização raiz do Azure Storage para a importação do ficheiro.

CREATE EXTERNAL DATA SOURCE pandemicdatalake
WITH (LOCATION = 'https://<data-lake>.blob.core.windows.net/public/');

Observação

Substitua <data-lake>.blob.core.windows.net por um URL apropriado.

Para obter mais informações, consulte CREATE EXTERNAL DATA SOURCE.

O caminho do ficheiro na FROM cláusula deve ser um caminho relativo, que será acrescentado à localização raiz definida na fonte de dados externa.

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

Observação

Para simplificar, os seguintes exemplos usam caminhos relativos e fontes de dados externas pré-definidas...

PÁGINA DE CÓDIGO

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

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, CODEPAGE = '65001');

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

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

CODEPAGE valor	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)	As colunas do tipo de dados char, varchar ou text são convertidas da página de código do sistema OEM para a página de código do SQL Server.
RAW	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

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

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, DATAFILETYPE = 'char');

Observação

Substitua <data-lake>.blob.core.windows.net por um URL apropriado.

DATAFILETYPE valor	Todos os dados representados em
char (padrão)	Formato do caractere. Para mais informações, consulte Usar formato de carácter para importar ou exportar dados.
widechar	Caracteres Unicode. Para mais informações, consulte Usar o formato de caracteres Unicode para importar ou exportar dados.
native	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 mais informações, consulte Usar formato nativo para importar ou exportar dados.
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 widenative arquivo de dados importando dados em massa do SQL Server usando o utilitário bcp . O widenative valor oferece uma alternativa de maior desempenho ao widechar. Se o arquivo de dados contiver caracteres estendidos ANSI, especifique widenative. Para mais informações, veja Usar Formato Nativo Unicode para Importar ou Exportar Dados.

MAXERRORS

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.

BULK INSERT bing_covid_19_data
FROM 'curated/covid-19/bing_covid-19_data/latest/bing_covid-19_data.csv'
WITH (DATA_SOURCE = 'pandemicdatalake', MAXERRORS = 0);

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

ERRORFILE

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á".

BULK INSERT bing_covid_19_data
FROM 'curated/covid-19/bing_covid-19_data/latest/bing_covid-19_data.csv'
WITH (DATA_SOURCE = 'pandemicdatalake',
      ERRORFILE = 'https://<data-lake>.blob.core.windows.net/public/curated/covid-19/bing_covid-19_data/latest/errors');

Observação

Substitua <data-lake>.blob.core.windows.net por um URL apropriado.

O arquivo de erro é criado quando o comando é executado. Ocorrerá um erro se o ficheiro já existir. Além disso, um arquivo de controle com 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 Azure Storage.

SOURCE_DADOS_ARQUIVO_ERRO

Aplica-se a: SQL Server 2017 (14.x) e versões posteriores.

Especifica uma fonte de dados externa nomeada que aponta para a localização Azure Storage do ficheiro de erro para acompanhar os erros encontrados durante a importação.

BULK INSERT bing_covid_19_data
FROM 'curated/covid-19/bing_covid-19_data/latest/bing_covid-19_data.csv'
WITH (
    DATA_SOURCE = 'pandemicdatalake',
    ERRORFILE = 'curated/covid-19/bing_covid-19_data/latest/errors',
    ERRORFILE_DATA_SOURCE = 'pandemicdatalake'
);

Para mais detalhes sobre a criação de fontes de dados externas, consulte CRIAR FONTE DE DADOS EXTERNA.

PRIMEIRA FILA

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.

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);

O FIRSTROW atributo não se destina a ignorar cabeçalhos de coluna. A BULK INSERT instrução não suporta pular cabeçalhos. 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.

ÚLTIMA FILA

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

TAMANHO DO LOTE

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.

VERIFICAR_RESTRIÇÕES

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 CHECK_CONSTRAINTS opção, todas CHECK as FOREIGN KEY restrições são ignoradas e, após a operação, a restrição na tabela é marcada como não confiável.

UNIQUE e PRIMARY KEY as restrições são sempre aplicadas. Ao importar para uma coluna de caracteres definida com uma NOT NULL restrição, 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 CHECK de restrições 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 CHECK as restrições desabilitadas, você pode importar os dados e, em seguida, usar instruções Transact-SQL para remover os dados inválidos.

Observação

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

DISPARADORES_DE_FOGO

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 INSERT operações 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.

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 de semente e incremento 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.

Para mais informações, veja sobre manter valores de identificação, veja Manter valores de identidade ao importar dados em massa.

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 mais informações, veja Manter valores nulos ou predefinidos durante a importação em massa.

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.

ORDER

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

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 especificada. 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, tomando um bloqueio exclusivo (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 faz com que o thread tenha um bloqueio exclusivo na tabela (ao contrário do bloqueio de atualização em massa (BU) para conjuntos de TABLOCK linhas tradicionais) que impede que outros threads simultâneos carreguem dados simultaneamente.

Opções de formato de arquivo de entrada

FORMAT

Aplica-se a: SQL Server 2017 (14.x) e versões posteriores.

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

BULK INSERT bing_covid_19_data
FROM 'curated/covid-19/bing_covid-19_data/latest/bing_covid-19_data.csv'
WITH (DATA_SOURCE = 'pandemicdatalake', FORMAT = 'CSV');

CITAÇÃO DE CAMPO

Aplica-se a: SQL Server 2017 (14.x) e versões posteriores.

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

FORMATFILE

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.

BULK INSERT bing_covid_19_data
FROM 'curated/covid-19/bing_covid-19_data/latest/bing_covid-19_data.csv'
WITH (DATA_SOURCE = 'pandemicdatalake',
      FORMATFILE = 'https://<data-lake>.blob.core.windows.net/public/curated/covid-19/bing_covid-19_data/latest/bing_covid-19_data.fmt');

Observação

Substitua <data-lake>.blob.core.windows.net por um URL apropriado.

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 mais informações, consulte Utilitário bcp e Criar um ficheiro de formato com bcp.

A partir do SQL Server 2017 (14.x), e no Azure SQL Database, format_file_path pode ser no Azure Storage.

FORMATFILE_DATA_SOURCE

Aplica-se a: SQL Server 2017 (14.x) e versões posteriores.

Especifica uma fonte de dados externa nomeada que aponta para a localização Azure Storage do ficheiro de formato para definir o esquema dos dados importados.

BULK INSERT bing_covid_19_data
FROM 'curated/covid-19/bing_covid-19_data/latest/bing_covid-19_data.csv'
WITH (
    DATA_SOURCE = 'pandemicdatalake',
    FORMATFILE = 'curated/covid-19/bing_covid-19_data/latest/bing_covid-19_data.fmt',
    FORMATFILE_DATA_SOURCE = 'pandemicdatalake'
);

TERMINADOR DE CAMPO

Especifica o terminador de campo a usar e charwidechar os ficheiros 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.

BULK INSERT bing_covid_19_data
FROM '/curated/covid-19/bing_covid-19_data/latest/bing_covid-19_data.csv'
WITH (DATA_SOURCE = 'pandemicdatalake', FIELDTERMINATOR = ',', FIRSTROW = 2);

ROWTERMINATOR

Especifica o terminador de linha a usar para char e widechar ficheiros de dados.

BULK INSERT bing_covid_19_data
FROM '/curated/covid-19/bing_covid-19_data/latest/bing_covid-19_data.csv'
WITH (DATA_SOURCE = 'pandemicdatalake', ROWTERMINATOR = '\r\n', FIRSTROW = 2);

O terminador de linha por defeito é \r\n (retorno de carro e carácter de nova linha). Para obter mais informações, consulte Especificar terminadores de campo e linha.

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 se:

• 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 seguem BULK INSERT as mesmas regras da 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.

Os arquivos de formato representam dados reais como o tipo de dados SQLFLT4 e flutuam dados como o tipo de dados SQLFLT8. Para informações sobre ficheiros em formato não XML, veja Especificar tipo de armazenamento de ficheiro usando bcp.

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, , contém dados de C:\t_float-c.dat de notação científica, 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 é possível importar esses dados diretamente para t_floato , 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

Azure SQL Database e Fabric Data Warehouse suportam apenas a leitura de URI (por exemplo, Azure Storage).

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 uma comparação entre a BULK INSERT instrução, a INSERT ... SELECT * FROM OPENROWSET(BULK...) instrução e o bcp comando, veja Importação e Exportação em Massa de Dados.

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

A BULK INSERT instrução 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 BATCHSIZEBULK INSERT cláusula na instrução. Se uma transação de vários lotes for revertida, cada lote enviado para o SQL Server será revertido.

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.

Comportamento de log

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

Limitações

Ao usar um arquivo de formato com BULK INSERTo , você pode especificar apenas até 1.024 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 um arquivo de dados que contém mais de 1.024 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 1.024 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 remove 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 BULK INSERT comando é 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 BULK INSERT instrução 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 INSERTo , consulte Usar BULK INSERT ou OPENROWSET(BULK...) para importar dados para o SQL Server.

Ao importar do Azure Storage e os dados não forem públicos (acesso anónimo), crie uma CREDENCIAL COM ALCANCE DE BASE DE DADOS baseada numa chave SAS encriptada com uma chave mestra de base de dados (DMK), e depois crie uma fonte de base de dados externa para usar no seu BULK INSERT comando.

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 utilizar MANAGED IDENTITY, o Azure Storage deve conceder permissões à identidade gerida da instância, adicionando o papel incorporado Azure Blob Data Contributor (role-based access control) (RBAC), que fornece acesso de leitura/escrita à identidade gerida para os contentores necessários do Azure Storage. 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 default identidade da instância gerenciada seria usada (ou seja, a identidade gerenciada atribuída pelo usuário principal ou a identidade gerenciada atribuída pelo sistema se a identidade gerenciada atribuída pelo usuário não for especificada). Para um exemplo, veja Importar dados de um ficheiro no Azure Storage.

Importante

A Identidade Gerida aplica-se ao Azure SQL, SQL Server 2025 (17.x) e versões posteriores.

Permissões

As permissões a seguir se aplicam ao local onde os dados estão sendo importados em massa (o destino).

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

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

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

  Desabilitar restrições é o comportamento padrão. Para verificar as restrições explicitamente, use a CHECK_CONSTRAINTS opção.

• Existem gatilhos e a FIRE_TRIGGER opção não é especificada.

  Por padrão, os gatilhos não são acionados. Para disparar gatilhos explicitamente, use a FIRE_TRIGGER opção.

• Use a opção para importar o KEEPIDENTITY valor de identidade do arquivo de dados.

Exemplos

Os exemplos de código neste artigo usam o banco de dados de exemplo AdventureWorks2025 ou AdventureWorksDW2025, que pode ser descarregado da página inicial de Exemplos e Projetos da Comunidade do Microsoft SQL Server.

Importante

O Azure SQL Database e o Fabric Warehouse suportam apenas a leitura do Azure Storage.

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');

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);

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 AS VARCHAR (1000);

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

EXECUTE (@bulk_cmd);

Observação

No Windows, \n é automaticamente substituído por \r\n.

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

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'
);

F. Importar dados de um ficheiro no Azure Storage

Carregar dados a partir de um CSV no Azure Storage com token SAS

O exemplo seguinte mostra como carregar dados de um ficheiro CSV numa localização Azure Storage onde criou uma Assinatura de Acesso Partilhada (SAS). A localização do Azure Storage está configurada como uma fonte de dados externa, que requer uma credencial com âmbito de base de dados usando uma chave SAS encriptada através de um DMK na base de dados do utilizador.

Observação

Certifique-se de que não tem um início ? no token SAS, e que tem pelo menos permissão de leitura no objeto que deve ser carregado srt=o&sp=r, e que o período de expiração é válido (todas as datas estão em tempo UTC).

(Opcional) Um DMK não é necessário se a DATABASE SCOPED CREDENTIAL não for necessário, porque o blob está configurado para acesso público (anónimo).

CREATE MASTER KEY ENCRYPTION BY PASSWORD = '<password>';

(Opcional) A DATABASE SCOPED CREDENTIAL não é obrigatório porque o blob está configurado para acesso público (anónimo).

Não incluas uma liderança ? no token SAS. Certifique-se de que tem pelo menos permissão de leitura sobre o objeto que deve ser carregado (srt=o&sp=r), e que o período de expiração é válido (todas as datas estão em tempo UTC).

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***************';

Observação

CREDENTIAL não é obrigatório se um blob estiver configurado para acesso público (anónimo).

CREATE EXTERNAL DATA SOURCE MyAzureBlobStorage
WITH (
    TYPE = BLOB_STORAGE,
    LOCATION = 'https://****************.blob.core.windows.net/invoices',
    CREDENTIAL = MyAzureBlobStorageCredential
);

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

Carregar dados de um CSV no Azure Storage com uma identidade gerida

O exemplo seguinte mostra como usar o BULK INSERT comando para carregar dados de um ficheiro CSV numa localização Azure Storage usando Identidade Gerida. A localização do Azure Storage está configurada como uma fonte de dados externa.

(Opcional) Um DMK não é necessário se a DATABASE SCOPED CREDENTIAL não for necessário, porque o blob está configurado para acesso público (anónimo).

CREATE MASTER KEY ENCRYPTION BY PASSWORD = '<password>';

(Opcional) A DATABASE SCOPED CREDENTIAL não é obrigatório, porque o blob está configurado para acesso público (anónimo):

CREATE DATABASE SCOPED CREDENTIAL MyAzureBlobStorageCredential
WITH IDENTITY = 'Managed Identity';

Conceder o papel de Contribuidor de Dados do Blob de Armazenamento, para fornecer acesso de leitura/escrita à identidade gerida para os contentores necessários do Azure Storage.

Observação

CREDENTIAL não é obrigatório se um blob estiver configurado para acesso público (anónimo).

CREATE EXTERNAL DATA SOURCE MyAzureBlobStorage
WITH (
    TYPE = BLOB_STORAGE,
    LOCATION = 'https://****************.blob.core.windows.net/invoices',
    CREDENTIAL = MyAzureBlobStorageCredential
);

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

Importante

A identidade gerida aplica-se ao SQL Server 2025 (17.x) e versões posteriores, bem como ao Azure SQL.

G. Importar dados de um ficheiro no Azure Storage e especificar um ficheiro de erro

O exemplo seguinte mostra como carregar dados de um ficheiro CSV numa localização Azure Storage, que está configurada como fonte de dados externa, e também especifica um ficheiro de erro. Você precisa de uma credencial com escopo de banco de dados usando uma assinatura de acesso compartilhado. Se estiver a correr na base de dados SQL do Azure, a ERRORFILE opção deve vir acompanhada de ERRORFILE_DATA_SOURCE, caso contrário a importação pode 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 exemplos completos BULK INSERT , incluindo a configuração da credencial e da fonte de dados externa, veja Exemplos de acesso em massa a dados no Azure Storage.

Mais exemplos

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

• Exemplos de importação e exportação em massa de documentos XML
• Mantenha os valores de identidade ao importar dados em massa
• Mantém os valores nulos ou predefinidos durante a importação em massa
• Especificar terminadores de campo e linha
• Use um ficheiro de formatação para importar dados em massa
• Use o formato de carácter para importar ou exportar dados
• Use o formato nativo para importar ou exportar dados
• Usar o formato de caracteres Unicode para importar ou exportar dados
• Use o formato nativo Unicode para importar ou exportar dados
• Use um ficheiro de formato para saltar uma coluna de tabela
• Use um ficheiro de formato para mapear colunas de tabelas para campos de ficheiro de dados

Conteúdo relacionado

• Importação e exportação em massa de dados (SQL Server)
• Utilitário bcp
• Formatar arquivos para importar ou exportar dados (SQL Server)
• INSERIR (Transact-SQL)
• OPENROWSET (Transact-SQL)
• Preparar dados para exportação ou importação em massa
• sp_tableoption (Transact-SQL)