Exportar dados com o dbSlice: guia dos 11 formatos

Exemplo: SQL Server MASTER → item → JSON · 11.172 registros sintéticos

A aba Export reúne num só lugar a escolha da origem, o filtro, o formato do arquivo e o retorno da execução. Este guia percorre os controles, reproduz a configuração mostrada na demonstração fornecida e explica o que cada saída realmente contém.

As capturas mostram o dbSlice 2.3. O comportamento dos formatos também foi conferido com o código do aplicativo que acompanha o material. Os rótulos e a disponibilidade dos formatos podem variar conforme a versão instalada e a licença. Na implementação revisada, o modo de avaliação permite exportar em CSV; os outros formatos exigem ativação.

1. Conheça a aba Export

Há duas seções principais. Source identifica o que o dbSlice lê. Target define o arquivo que ele cria. Os botões de ação e o log de execução ficam abaixo delas. O progresso aparece no painel fixo Processing status, abaixo da árvore de conexões, que também tem o botão Cancel.

O nome MASTER é um perfil de conexão salvo nesta demonstração. Ele não se refere ao banco de sistema do SQL Server chamado master. As credenciais de conexão são guardadas à parte e não fazem parte dos exemplos deste artigo.

Use uma chave única, sem nulos, que fique estável durante a exportação. Uma chave primária como id é a escolha natural. Numa consulta própria, devolva a coluna-chave no resultado e garanta que os joins não a duplicaram.

O tamanho de página é um tamanho de lote. Pôr 10.000 não limita a exportação inteira a 10.000 linhas e não cria um arquivo para cada página. Use um filtro ou uma consulta para definir um conjunto menor.

A exportação lê a origem sem aplicar INSERT, UPDATE ou DELETE nela. Ela grava, sim, o arquivo de saída escolhido. Em particular, escolher SQLite cria um arquivo de banco local; escolher SQL gera um texto que só é executado se você mesmo rodá-lo depois.

2. Passo a passo: exportar 11.172 itens para JSON

Este exemplo usa o conjunto de dados sintético de vendas dos artigos anteriores do dbSlice. A tabela de origem tem 11.172 itens com identificadores, referências de categoria, nomes, preços, quantidades, status e datas de criação.

1. Abra Export e escolha MASTER [SQL Server] em Connection.
2. Clique em Connect e escolha Table e depois item.
3. Ponha Key column (unique) em id.
4. Deixe WHERE filter desmarcado para incluir a tabela inteira.
5. Escolha JSON em Format.
6. Use Browse para escolher um arquivo de saída novo, por exemplo C:\dbSliceDemo\exports\items.json.
7. Ponha Page (rows) em 10.000.
8. Deixe Obfuscate values desmarcado para este conjunto sintético.
9. Clique em Export e acompanhe o log de execução.
10. Abra o arquivo gerado e confira a estrutura, a contagem de linhas e valores representativos.

A demonstração fornecida informa:

Export completed: 11,172 rows, 2,623 KB in 0.1s.

A duração mostrada é uma observação da execução fornecida, não uma garantia de desempenho nem um benchmark entre formatos. A rede, a atividade do banco, a largura das linhas, o desempenho do disco e o formato de saída afetam as próximas execuções. As mensagens de progresso podem ser espaçadas; então o log não precisa ter uma linha para cada lote.

O primeiro registro mostrado na demonstração tem esta estrutura:

[
  {
    "id": 1,
    "category_id": 1,
    "sku": "SKU-00000001",
    "name": "Demo Item 00000001",
    "unit_price": 10.00,
    "stock_quantity": 13,
    "is_active": 1,
    "created_at": "2023-01-01T00:00:00.0000000"
  }
]

É um trecho de um registro, não o arquivo completo de 11.172 registros. O valor numérico de is_active reflete a representação desta origem; uma exportação JSON não transforma automaticamente todo campo 0/1 em booleano.

3. Escolha o formato pelo próximo passo

A lista tem 11 opções. Dez produzem uma representação dos dados ou das chaves das linhas escolhidas. A SQL — MERGE / upsert produz um modelo de comando parametrizado a partir da estrutura da origem.

4. Arquivos de dados: CSV, JSON e XML

CSV: uma tabela compacta e de uso amplo

O CSV grava um cabeçalho seguido de registros separados por vírgula. O exportador revisado usa UTF-8 com byte-order mark. Valores com vírgulas, aspas ou quebras de linha vão entre aspas, e as aspas dentro de um campo são escapadas dobrando-as.

O exemplo resumido a seguir usa só três colunas, para facilitar a leitura:

id,sku,unit_price
1,SKU-00000001,10.00
2,SKU-00000002,19.37

Escolha CSV para troca de dados planos e fluxos de importação em massa. Configure a ferramenta que recebe para usar vírgula como delimitador e os tipos de coluna pretendidos. Um arquivo CSV não leva o esquema original do banco, e uma planilha pode reinterpretar identificadores ou datas ao abri-lo. Neste exportador, valores nulos e strings vazias podem aparecer os dois como campos vazios; use JSON se essa diferença importa para quem consome.

JSON: registros estruturados para aplicações

O JSON produz um único array de objetos, com os nomes das colunas da origem como nomes das propriedades. Números, booleanos e nulos mantêm as representações JSON correspondentes onde os valores da origem permitem. As datas são serializadas como strings; os valores binários usam Base64.

Escolha JSON para dados de teste, payloads de integração e scripts de processamento. A saída é um array JSON padrão, não JSON delimitado por linhas. Um consumidor que carrega o documento inteiro na memória precisa de capacidade para o arquivo completo, independentemente do tamanho de página do dbSlice.

XML: um documento baseado em elementos

O XML grava uma raiz DocumentElement, um elemento para cada linha e elementos filhos para as colunas exportadas. O nome do objeto dá o nome do elemento de linha. Os nomes são ajustados quando preciso para formar nomes de elemento XML válidos.

<DocumentElement>
  <item>
    <id>1</id>
    <sku>SKU-00000001</sku>
    <unit_price>10.00</unit_price>
  </item>
</DocumentElement>

Este exemplo resumido mostra o formato. As colunas com valor nulo são omitidas do elemento de linha no exportador revisado. O arquivo é um documento de dados, sem XSD acompanhando. Combine os nomes dos elementos e a convenção de nulos com o que o sistema que recebe espera.

5. Saídas legíveis: Markdown e Excel

Markdown: pôr um conjunto pequeno num documento

O Markdown cria uma tabela com os títulos das colunas e um título opcional tirado do nome do objeto. É útil em arquivos README, relatos de problemas e artigos técnicos em que uma amostra pequena deve aparecer junto de uma explicação.

| id | sku | unit_price |
| --- | --- | --- |
| 1 | SKU-00000001 | 10.00 |
| 2 | SKU-00000002 | 19.37 |

Use um filtro como id <= 20 para manter o resultado legível. Dá para pedir a exportação de centenas de milhares de linhas como tabela Markdown, mas o documento resultante fica difícil de navegar e de renderizar.

Excel: uma planilha para revisão e análise

O Excel cria uma pasta de trabalho .xlsx com uma planilha, uma linha de cabeçalho e os registros exportados. O exportador atribui os valores das células para os tipos de origem suportados e ajusta a largura das colunas a partir de uma amostra dos dados.

Escolha Excel quando o próximo usuário quer inspecionar, ordenar, filtrar ou fazer gráficos dos resultados numa planilha. Confira identificadores numéricos longos, valores sensíveis à precisão e células de data antes de distribuir o arquivo.

O gerador de Excel revisado monta a pasta de trabalho na memória. Reduzir o Page (rows) muda os lotes de leitura do banco, mas não transforma a pasta de trabalho numa saída em streaming. Filtre conjuntos grandes para um subconjunto útil de trabalho, ou escolha CSV ou JSON para um fluxo de processamento de arquivos.

6. SQLite: exporte uma tabela que dá para consultar localmente

O SQLite database (.db) cria um arquivo de banco local e uma tabela baseada nas colunas e na chave da origem escolhidas. Os registros são inseridos em lotes. Ponha no nome do objeto de destino um nome de tabela simples, como item, e escolha um arquivo .db novo.

A saída pode então ser aberta com uma ferramenta compatível com SQLite. Por exemplo:

SELECT COUNT(*) AS row_count FROM item;

SELECT id, sku, unit_price
FROM item
ORDER BY id
LIMIT 10;

Isso serve para uma demonstração portátil, um conjunto local de consulta ou um extrato que precisa de consultas SQL. Uma operação de Export trata o objeto escolhido. Ela não deve ser descrita como um backup completo do banco de origem: não suponha que todas as chaves estrangeiras, índices secundários, triggers, stored procedures ou tabelas relacionadas foram reproduzidos.

Escolha o caminho de saída com cuidado. A exportação para SQLite revisada substitui um arquivo existente naquele caminho antes de criar a tabela exportada. Ela não acrescenta outra tabela a um banco existente. Use o Synchronize quando a tarefa for atualizar uma tabela num banco de destino existente.

7. Saídas SQL: INSERT, UPDATE e MERGE / upsert

SQL INSERT: um comando para cada linha escolhida

O SQL INSERT grava valores literais em comandos INSERT. Um exemplo resumido:

INSERT INTO item (id, sku, unit_price)
VALUES (1, 'SKU-00000001', 10.00);

A tabela de destino precisa existir quando você rodar o script. Chaves existentes, regras de colunas identity e constraints podem afetar a execução. Este formato exporta comandos de dados; ele não faz a carga durante o Export e não inclui um esquema completo do banco.

SQL UPDATE: case os registros existentes pela chave

O SQL UPDATE grava um comando para cada linha da origem, com a chave escolhida na condição WHERE e as outras colunas nas atribuições SET.

UPDATE item
SET sku = 'SKU-00000001', unit_price = 10.00
WHERE id = 1;

Este exemplo resumido ilustra o padrão. A exportação real inclui as outras colunas que não são chave devolvidas pela origem. O UPDATE não insere um registro que falta e não é um relatório de comparação de campos alterados: ele gera atribuições a partir dos dados escolhidos.

Para o INSERT e o UPDATE, confira nomes de objetos, identificadores, literais e tipos de dados contra o banco que vai rodar o arquivo. Os comandos gerados não garantem portabilidade entre todos os bancos.

SQL — MERGE / upsert: um modelo baseado no esquema

Esta opção é diferente das duas exportações SQL por linha. Ela lê a estrutura da origem e cria um comando parametrizado, com parâmetros que correspondem às colunas. Ela não grava um comando de upsert preenchido para cada registro.

A sintaxe segue o dialeto do banco da conexão de origem. Para os bancos usados nestes artigos, a implementação revisada escolhe:

Use o modelo como ponto de partida para um comando de aplicação: revise a chave, associe os parâmetros e adapte ao destino e ao contexto de execução. Um filtro WHERE não embute um conjunto filtrado neste modelo, porque o gerador não lê linhas de dados. Para transferir registros reais com comportamento de upsert, configure a aba Synchronize ou um job de Sync.

8. Exporte uma seleção de registros: key IN e CSV de chaves

SQL — key IN (...)

Este formato exporta os valores das chaves escolhidas como um predicado:

id IN (1, 2, 3)

É um fragmento de SQL, não um SELECT completo. Você pode incluí-lo numa consulta num banco compatível:

SELECT id, sku
FROM item
WHERE id IN (1, 2, 3);

Use numa seleção pequena de registros. Listas IN muito grandes podem esbarrar em limites de tamanho de comando ou específicos de cada banco; uma tabela intermediária ou uma lista de chaves importável costuma ser mais fácil de administrar. Chaves de texto são gravadas como literais SQL, e não como números soltos.

CSV — key list

Esta opção grava um arquivo CSV de uma coluna, incluindo o cabeçalho da coluna-chave:

id
1
2
3

É útil quando outro processo precisa dos identificadores escolhidos, mas não dos nomes, preços ou outros atributos. Aplique primeiro o filtro WHERE para definir a seleção. A saída só de chaves reduz as colunas exportadas, mas os identificadores ainda podem ser sensíveis num conjunto de dados real.

9. Filtros, nomes de objeto e ofuscação

Marque WHERE filter e digite uma condição escrita para o banco de origem, como:

id <= 100

Digite o predicado sem outra palavra WHERE. Os dados da origem são filtrados antes de a saída por linha ser gravada. Para escolher outra projeção de colunas ou montar um conjunto com joins, use a opção de consulta como origem e devolva uma chave única adequada.

Quando o Target object aparecer, revise-o depois de mudar a origem ou o formato. Ele fornece nomes como a tabela SQL, a tabela SQLite, o elemento de linha XML ou o título da planilha. Ele é separado do nome do arquivo de saída e não escolhe outra conexão. Alguns formatos precisam de um nome de objeto significativo quando a origem é uma consulta.

O Obfuscate values (except keys and foreign keys) transforma a saída, sem atualizar a origem. Para uma tabela ou view, o escopo revisado exclui a chave escolhida e as chaves primárias e estrangeiras informadas pelo provider. Resultados de consultas arbitrárias não trazem os mesmos metadados de chave estrangeira; então confira como as colunas deles são tratadas.

A ofuscação é útil para preparar amostras, mas não é criptografia de arquivo. Inspecione a saída real antes de compartilhá-la, inclusive identificadores mantidos, texto livre e cabeçalhos de artefatos gerados. Na demonstração deste artigo, os dados são sintéticos e a opção fica desligada.

10. Reaproveite a configuração como job de Export

Para uma extração JSON repetível, o job de exemplo que acompanha o guia usa o perfil salvo MASTER:

{
  "nome": "export-demo-items-json",
  "tipo": "Export",
  "origem": {
    "environment": "article",
    "db": "MASTER",
    "type": "TABLE",
    "object": "item",
    "key": "id"
  },
  "directory": "C:\\dbSliceDemo\\exports",
  "file": "items.json",
  "format": "JSON",
  "pageSize": 10000,
  "ofuscar": false,
  "alertemail": false
}

Os nomes das propriedades seguem o esquema de jobs do dbSlice. O arquivo contém referências a perfis e configurações de exportação, sem credenciais de conexão. Ajuste o ambiente, o nome do perfil e a pasta de saída à sua instalação. Carregue em CLI jobs, confira as configurações e use Run now ou Copy CLI command para obter o comando daquela instalação.

Esta definição de job JSON foi validada sem conectar a um banco nem rodar outra exportação. O suporte a formatos na interface e na CLI deve ser conferido em separado: no parser de CLI revisado, as opções SQLite database e MERGE / upsert desta lista não são aceitas como nomes de formato de Export. Use a interface para esses dois fluxos deste guia.

11. Confira a saída antes de entregá-la

Comece pelo estado final e pela contagem de linhas. No exemplo sem filtro, espere 11.172 registros; numa exportação filtrada, compare com o mesmo predicado na origem. Contar linhas de texto não é uma contagem confiável de registros em CSV com aspas ou em JSON formatado.

Para o array JSON da demonstração, esta verificação em PowerShell lê o arquivo concluído:

$exportPath = 'C:\dbSliceDemo\exports\items.json'
$exportRows = @(Get-Content -LiteralPath $exportPath -Raw | ConvertFrom-Json)
$exportRows.Count
$exportRows | Select-Object -First 3 id, sku, unit_price

Esta verificação carrega o arquivo na memória e foi pensada para o exemplo de 11.172 linhas. Valide nulos, caracteres especiais, datas, valores numéricos e identificadores contra alguns registros conhecidos da origem. No SQLite, consulte a tabela gerada; no SQL, revise o script antes de executá-lo no banco pretendido.

Use um conjunto de origem estável quando precisar de um extrato coerente internamente. A paginação, sozinha, não garante uma foto num instante se outros processos estiverem mudando registros enquanto a exportação roda.

Escolha um nome de arquivo de saída novo para cada resultado que for guardar. Arquivos de saída existentes podem ser sobrescritos, e cancelar uma operação não restaura um arquivo anterior. Se uma exportação falhar ou for cancelada, inspecione o destino antes de tratá-lo como um artefato concluído.

Feitas essas conferências, escolha o formato que combina com quem consome: JSON para dados estruturados de aplicação, CSV para troca plana, Excel para revisão interativa, SQLite para consultas SQL locais, e SQL ou saída só de chaves para um fluxo de banco mais direcionado.

Referências e escopo da demonstração

• Site do produto dbSlice — informações do produto e ponto de partida da instalação.
• Capturas do Export fornecidas — a lista, a configuração de exemplo e o resultado JSON informado.
• Implementação do aplicativo que acompanha o material — painel Export, operações e geradores de exportação, escopo de ofuscação e parser de jobs, revisados para este guia.

O resultado de exportação informado vem da demonstração fornecida. Os outros exemplos de formato são trechos explicativos; este artigo não afirma que todos os formatos foram executados ou medidos naquela execução. Nenhum endereço de servidor real, senha ou caminho de conta pessoal aparece nos arquivos publicados.