Como usar o utilitário bcp

Aplica-se a:SQL ServerAzure SQL DatabaseAzure SQL Managed InstanceAzure Synapse AnalyticsAnalytics Platform System (PDW)SQL database in Microsoft Fabric

O utilitário de cópia em massa (bcp) copia dados entre uma instância do SQL Server e um arquivo de dados em um formato especificado pelo usuário.

Observações

• Para obter informações sobre onde encontrar ou como executar o utilitário bcp e sobre as convenções de sintaxe de utilitários de prompt de comando, consulte utilitários de linha de comando SQL (Mecanismo de Banco de Dados).

• Para obter informações sobre como preparar dados para importar ou exportar operações em massa, confira Preparar dados para exportação ou importação em massa.

• Para obter informações sobre quando as operações de inserção de linhas executadas por importações em massa são registradas no log de transações, confira Pré-requisitos para registro em log mínimo na importação em massa.

• Os caracteres <, >, |, &, e ^ são caracteres especiais de shell de comando, e devem ser precedidos pelo caractere de escape (^) ou entre aspas quando usados em uma cadeia de caracteres (por exemplo, ""StringContaining&Symbol""). Se você usar aspas para incluir uma cadeia de caracteres que contenha um dos caracteres especiais, as aspas serão definidas como parte do valor da variável de ambiente. Para obter mais informações, consulte Usando caracteres especiais adicionais.

Suporte de arquivos de dados nativos

No SQL Server, o utilitário bcp dá suporte a arquivos de dados nativos compatíveis com versões do SQL Server começando com o SQL Server 2000 (8.x) em diante.

Colunas computadas e colunas de carimbo de data/hora

Os valores no arquivo de dados que está sendo importado para colunas computadas ou de carimbo de data/hora são ignorados e o SQL Server atribui valores automaticamente. Se o arquivo de dados não contiver valores para as colunas computadas ou timestamp na tabela, use um arquivo de formato para especificar que as colunas computadas ou timestamp na tabela devem ser ignoradas ao importar dados; o SQL Server automaticamente atribuirá valores para a coluna.

Colunas computadas e colunas de carimbo de data/hora são copiadas em massa do SQL Server para um arquivo de dados, como sempre.

Especifique identificadores que contêm espaços ou aspas

Os identificadores do SQL Server podem incluir caracteres como espaços inseridos e aspas. Tais identificadores devem ser tratados do seguinte modo:

• Quando você especificar um identificador ou nome de arquivo que inclua um espaço ou aspas no prompt de comando, coloque o identificador entre aspas ("").

  Por exemplo, o comando bcp out a seguir cria um arquivo de dados nomeado Currency Types.dat:

  bcp AdventureWorks2022.Sales.Currency out "Currency Types.dat" -T -c
  

• Para especificar um nome de banco de dados que contenha um espaço ou aspas, você deve usar a opção -q.

• Para nomes de proprietário, tabela ou exibição que contenham espaços inseridos ou aspas, você também pode:

  • Especificar a opção -q ou

  • Inserir o nome de proprietário, tabela ou exibição entre colchetes ([]) dentro das aspas.

Validação de dados

Agora, o bcp impõe uma validação de dados e verificações de dados que poderão provocar falhas em scripts se forem executados em dados inválidos em um arquivo de dados. Por exemplo, o bcp agora verifica se:

• As representações nativas dos tipos de dados float ou real são válidas.

• Dados Unicode têm um comprimento regular de byte.

Formas de dados inválidos que podiam ser importadas em massa em versões anteriores do SQL Server podem falhar ao serem carregadas agora; enquanto em versões anteriores a falha só ocorria quando um cliente tentava acessar os dados inválidos. A validação adicional minimiza as surpresas ao consultar os dados depois do carregamento em massa.

Exportar ou importar documentos SQLXML em massa

Para exportar ou importar dados SQLXML em massa, use um dos tipos de dados a seguir em seu arquivo de formato.

Melhores práticas de modo de caractere (-c) e modo nativo (-n)

Esta seção apresenta recomendações para modo de caractere (-c) e modo nativo (-n).

• (Administrador/Usuário) Quando possível, use o formato nativo (-n) para evitar o problema de separador. Use o formato nativo para exportar e importar com o uso do SQL Server. Exporte dados do SQL Server usando a opção -c ou a opção -w se você planeja exportar os dados para um banco de dados que não seja do SQL Server.

• (Administrador) Verificar dados ao usar bcp out. Por exemplo, quando você usa bcp oute bcp inbcp out verifica se os dados são exportados corretamente e os valores do terminador não são usados como parte de algum valor de dados. Considere substituir os terminadores padrão (com as opções -t e -r) por valores hexadecimais aleatórios para evitar conflitos entre valores de terminadores e valores de dados.

• (Usuário) Use um terminador longo e exclusivo (qualquer sequência de bytes ou de caracteres) para minimizar a possibilidade de conflito com o valor real da cadeia de caracteres. Isso pode ser feito com as opções -t e -r.

Exemplos

Os exemplos nesta seção fazem uso do banco de dados de amostra WideWorldImporters para SQL Server 2016 (13.x) e versões posteriores, Banco de Dados SQL do Azure e Instância Gerenciada de SQL do Azure. WideWorldImporters pode ser baixado de https://github.com/Microsoft/sql-server-samples/releases/tag/wide-world-importers-v1.0. Consulte Instruções RESTORE para obter a sintaxe para restaurar o banco de dados de exemplo.

Condições de teste de exemplo

Exceto quando especificado de outra forma, os exemplos presumem que você esteja usando a Autenticação do Windows e tenha uma conexão confiável com a instância do servidor na qual está executando o comando bcp. Um diretório chamado D:\bcp é usado em muitos dos exemplos. Substitua <server_name> e outros valores de marcadores de posição por valores para seu ambiente.

O script de Transact-SQL a seguir cria uma cópia vazia da WideWorldImporters.Warehouse.StockItemTransactions tabela e adiciona uma restrição de chave primária:

USE WideWorldImporters;
GO

SET NOCOUNT ON;

IF NOT EXISTS (SELECT *
               FROM sys.tables
               WHERE name = 'Warehouse.StockItemTransactions_bcp')
    BEGIN
        SELECT *
        INTO WideWorldImporters.Warehouse.StockItemTransactions_bcp
        FROM WideWorldImporters.Warehouse.StockItemTransactions
        WHERE 1 = 2;

        ALTER TABLE Warehouse.StockItemTransactions_bcp
        ADD CONSTRAINT PK_Warehouse_StockItemTransactions_bcp
            PRIMARY KEY NONCLUSTERED (StockItemTransactionID ASC);
    END

Você pode truncar a tabela StockItemTransactions_bcp conforme necessário:

TRUNCATE TABLE WideWorldImporters.Warehouse.StockItemTransactions_bcp;

A. Identificar a versão do utilitário bcp

No prompt de comando, digite o seguinte comando:

bcp -v

B. Copie linhas de tabela em um arquivo de dados (com uma conexão confiável)

Os exemplos a seguir ilustram a opção out na tabela WideWorldImporters.Warehouse.StockItemTransactions.

• Basic

  Este exemplo cria um arquivo de dados nomeado StockItemTransactions_character.bcp e copia os dados da tabela nesse arquivo usando o formato de caractere .

  No prompt de comando, digite o seguinte comando:

  bcp WideWorldImporters.Warehouse.StockItemTransactions out D:\bcp\StockItemTransactions_character.bcp -c -T
  

• Expanded

  Este exemplo cria um arquivo de dados nomeado StockItemTransactions_native.bcp e copia os dados da tabela nesse arquivo usando formato nativo . O exemplo também: especifica o número máximo de erros de sintaxe, um arquivo de erro e um arquivo de saída.

  No prompt de comando, digite o seguinte comando:

  bcp WideWorldImporters.Warehouse.StockItemTransactions OUT D:\bcp\StockItemTransactions_native.bcp -m 1 -n -e D:\bcp\Error_out.log -o D:\bcp\Output_out.log -S <server_name> -T
  

Analise Error_out.log e Output_out.log. Error_out.log deve ficar em branco. Compare os tamanhos de arquivo entre StockItemTransactions_character.bcp e StockItemTransactions_native.bcp.

C. Copie linhas de tabela em um arquivo de dados (com autenticação mista)

O exemplo a seguir ilustra a opção out na tabela WideWorldImporters.Warehouse.StockItemTransactions. Este exemplo cria um arquivo de dados nomeado StockItemTransactions_character.bcp e copia os dados da tabela nesse arquivo usando o formato de caractere .

O exemplo pressupõe que você esteja usando autenticação mista; você deve usar a opção -U para especificar sua ID de logon. Além disso, a menos que você esteja se conectando à instância padrão do SQL Server no computador local, use a opção -S para especificar o nome do sistema e, se quiser, um nome de instância.

No prompt de comando, digite o seguinte comando: (O sistema solicitará sua senha.)

bcp WideWorldImporters.Warehouse.StockItemTransactions out D:\bcp\StockItemTransactions_character.bcp -c -U<login_id> -S<server_name\instance_name>

D. Copie dados de um arquivo para uma tabela

Os exemplos a seguir ilustram a opção in na tabela WideWorldImporters.Warehouse.StockItemTransactions_bcp usando os arquivos criados anteriormente.

• Basic

  Este exemplo usa o arquivo de dados StockItemTransactions_character.bcp criado anteriormente.

  No prompt de comando, digite o seguinte comando:

  bcp WideWorldImporters.Warehouse.StockItemTransactions_bcp IN D:\bcp\StockItemTransactions_character.bcp -c -T
  

• Expanded

  Este exemplo usa o arquivo de dados StockItemTransactions_native.bcp criado anteriormente. O exemplo também usa a TABLOCK dica e especifica o tamanho do lote, o número máximo de erros de sintaxe, um arquivo de erro e um arquivo de saída.

  No prompt de comando, digite o seguinte comando:

  bcp WideWorldImporters.Warehouse.StockItemTransactions_bcp IN D:\bcp\StockItemTransactions_native.bcp -b 5000 -h "TABLOCK" -m 1 -n -e D:\bcp\Error_in.log -o D:\bcp\Output_in.log -S <server_name> -T
  

  Analise Error_in.log e Output_in.log.

E. Copie uma coluna específica em um arquivo de dados

Para copiar uma coluna específica, você pode usar a opção queryout. O exemplo a seguir copia apenas a coluna StockItemTransactionID da tabela Warehouse.StockItemTransactions em um arquivo de dados.

No prompt de comando, digite o seguinte comando:

bcp "SELECT StockItemTransactionID FROM WideWorldImporters.Warehouse.StockItemTransactions WITH (NOLOCK)" queryout D:\bcp\StockItemTransactionID_c.bcp -c -T

F. Copie uma linha específica em um arquivo de dados

Para copiar uma linha específica, você pode usar a opção queryout. O exemplo a seguir copia apenas a linha para a pessoa nomeada Amy Trefl da tabela WideWorldImporters.Application.People em um arquivo de dados Amy_Trefl_c.bcp.

No prompt de comando, digite o seguinte comando:

bcp "SELECT * from Application.People WHERE FullName = 'Amy Trefl'" queryout D:\bcp\Amy_Trefl_c.bcp -d WideWorldImporters -c -T

G. Copie dados de uma consulta em um arquivo de dados

Para copiar o conjunto de resultados de uma instrução Transact-SQL em um arquivo de dados, use a opção queryout . O exemplo a seguir copia os nomes da tabela WideWorldImporters.Application.People , classificados pelo nome completo, no arquivo de dados People.txt .

No prompt de comando, digite o seguinte comando:

bcp "SELECT FullName, PreferredName FROM WideWorldImporters.Application.People ORDER BY FullName" queryout D:\bcp\People.txt -t, -c -T

H. Crie arquivos de formato

O exemplo a seguir cria três arquivos de formato diferentes para a tabela Warehouse.StockItemTransactions no banco de dados do WideWorldImporters . Revise o conteúdo de cada arquivo criado.

No prompt de comando, digite os seguintes comandos:

REM non-XML character format
bcp WideWorldImporters.Warehouse.StockItemTransactions format nul -f D:\bcp\StockItemTransactions_c.fmt -c -T

REM non-XML native format
bcp WideWorldImporters.Warehouse.StockItemTransactions format nul -f D:\bcp\StockItemTransactions_n.fmt -n -T

REM XML character format
bcp WideWorldImporters.Warehouse.StockItemTransactions format nul -f D:\bcp\StockItemTransactions_c.xml -x -c -T

Para obter mais informações, consulte Usar arquivos de formato não XML (SQL Server) e arquivos de formato XML (SQL Server).

I. Use um arquivo de formato para importação em massa com bcp

Para usar um arquivo de formato criado anteriormente ao importar dados para uma instância do SQL Server, utilize o parâmetro -f juntamente com a alternativa in. Por exemplo, o comando a seguir copia em massa o conteúdo de um arquivo de dados, StockItemTransactions_character.bcp, em uma cópia da tabela Warehouse.StockItemTransactions_bcp usando o arquivo de formato criado anteriormente StockItemTransactions_c.xml.

No prompt de comando, digite o seguinte comando:

bcp WideWorldImporters.Warehouse.StockItemTransactions_bcp in D:\bcp\StockItemTransactions_character.bcp -L 100 -f D:\bcp\StockItemTransactions_c.xml -T

J. Especifique uma página de código.

O exemplo de código parcial a seguir mostra a importação de bcp ao especificar uma página de código 65001:

bcp MyTable in "D:\data.csv" -T -c -C 65001 -t , ...

K. Exemplo de arquivo de saída usando um campo personalizado e terminadores de linha

Este exemplo mostra dois arquivos de exemplo, gerados por bcp usando terminadores de linha e de campo personalizados.

1. Crie uma tabela dbo.T1 no banco de dados tempdb, com duas colunas, ID e Name.

   USE tempdb;
   GO
   
   CREATE TABLE dbo.T1
   (
       ID INT,
       [Name] NVARCHAR (20)
   );
   GO
   
   INSERT INTO dbo.T1 VALUES (1, N'Natalia');
   INSERT INTO dbo.T1 VALUES (2, N'Mark');
   INSERT INTO dbo.T1 VALUES (3, N'Randolph');
   GO
   

2. Gere um arquivo de saída da tabela dbo.T1 de exemplo , usando um terminador de campo personalizado.

   Neste exemplo, -t , especifica o terminador de campo personalizado. Substitua <server_name> por um valor para seu ambiente.

   bcp dbo.T1 out T1.txt -T -S <server_name> -d tempdb -w -t ,
   

   Veja aqui o conjunto de resultados.

   1,Natalia
   2,Mark
   3,Randolph
   

3. Gere um arquivo de saída da tabela dbo.T1 de exemplo , usando um terminador de campo personalizado e um terminador de linha personalizado.

   Neste exemplo, -t , especifica o terminador de campo personalizado e -r : especifica o terminador de linha personalizado. Substitua <server_name> por um valor para seu ambiente.

   bcp dbo.T1 out T1.txt -T -S <server_name> -d tempdb -w -t , -r :
   

   Veja aqui o conjunto de resultados.

   1,Natalia:2,Mark:3,Randolph:
   

   Note

   O terminador de linha sempre é adicionado, mesmo que ao último registro. No entanto, o terminador de campo não é adicionado ao último campo.

Exemplos adicionais

Os artigos a seguir contêm exemplos de como usar o bcp:

• Formatos de dados para importação em massa ou exportação em massa (SQL Server)

  • Usar o formato nativo para importar ou exportar dados (SQL Server)
  • Usar o formato de caractere para importar ou exportar dados (SQL Server)
  • Usar o formato nativo Unicode para importar ou exportar dados (SQL Server)
  • Usar o formato de caractere Unicode para importar ou exportar dados (SQL Server)

• Especificar terminadores de linha e de campo (SQL Server)

• Manter valores nulos ou padrão durante a importação em massa (SQL Server)

• Manter valores de identidade ao importar dados em massa (SQL Server)

• Formatar arquivos para importar ou exportar dados (SQL Server)

  • Criar um arquivo de formato com bcp (SQL Server)
  • Usar um arquivo de formato para importação em massa de dados (SQL Server)
  • Usar um arquivo de formato para ignorar uma coluna de tabela (SQL Server)
  • Usar um arquivo de formato para ignorar um campo de dados (SQL Server)
  • Usar um arquivo de formato para mapear colunas de tabela para campos de arquivo de dados (SQL Server)

• Exemplos de importação e exportação em massa de documentos XML (SQL Server)

Conteúdo relacionado

• Preparar dados para exportação ou importação em massa
• BULK INSERT (Transact-SQL)
• OPENROWSET (Transact-SQL)
• SET QUOTED_IDENTIFIER (Transact-SQL)
• sp_configure (Transact-SQL)
• sp_tableoption (Transact-SQL)
• Arquivos de formato para importação ou exportação de dados (SQL Server)

Obter ajuda

• Ideias para SQL: Tem sugestões para melhorar o SQL Server?
• Microsoft Q&A (SQL Server)
• DBA Stack Exchange (tag sql-server): Faça perguntas sobre SQL Server
• Stack Overflow (tag sql-server): respostas para perguntas sobre desenvolvimento SQL
• Informações e termos de licença do Microsoft SQL Server
• Opções de suporte para usuários empresariais
• Ajuda e comentários adicionais sobre o SQL Server

Contribua com a documentação do SQL

Você sabia que pode editar o conteúdo do SQL por conta própria? Ao fazer isso, além de melhorar nossa documentação, você também será creditado como um colaborador da página.

Para obter mais informações, consulte a documentação Edit Microsoft Learn.