Fluxo de importação de dados

Uma importação confiável não consiste em enviar todas as tabelas de uma vez. O fluxo recomendado é iterativo: preparar uma etapa, verificar o que já existe, enviar um lote pequeno, recuperar os IDs produzidos, reconciliá-los com a tabela de origem e validar o resultado antes de importar os objetos dependentes.

Antes de enviar dados

1. Defina o projeto e o dataset de destino.
2. Confirme que sua conta é colaboradora ou administradora dos objetos que serão alterados.
3. Preserve uma cópia imutável dos dados recebidos.
4. Acrescente à tabela de trabalho uma chave local única, como source_row_id. Ela permitirá associar cada resultado à linha original.
5. Normalize codificação, datas, valores ausentes, números decimais e nomes de colunas.
6. Consulte as bibliotecas compartilhadas antes de criar Pessoas, Referências, Taxons, Localidades ou Traits.
7. Confira os campos do endpoint na API POST.

Não substitua a chave local pelos IDs do OpenDataBio. Mantenha ambos: a chave local documenta a origem; o ID ou UUID permite relacionar registros no sistema.

Ordem de dependências

Uma sequência comum é:

Essa ordem deve ser adaptada ao conjunto. Uma linha pode usar nomes, siglas ou outros identificadores aceitos pelo endpoint, mas guardar os IDs/UUIDs obtidos reduz ambiguidades nas etapas seguintes.

Validar coordenadas antes da importação

O endpoint POST locations-validation recebe latitude e longitude em graus decimais. Ele permite verificar previamente quais Localidades registradas contêm cada ponto, antes de criar Indivíduos ou Localidades automáticas.

Use essa etapa para detectar:

• latitude e longitude trocadas;
• sinal incorreto nos hemisférios sul ou oeste;
• pontos fora do país, estado, município ou área de estudo esperados;
• pontos que caem em unidades de conservação, terras indígenas ou camadas ambientais já cadastradas;
• coordenadas repetidas ou com precisão inadequada.

Exemplo em R:

library(opendatabio)

cfg = odb_config(
  base_url = "http://localhost/opendatabio/api",
  token = Sys.getenv("ODB_TOKEN")
)

coordinates = data.frame(
  source_row_id = c("plot-001", "plot-002"),
  latitude = c(-3.101, -3.115),
  longitude = c(-60.120, -60.135)
)

job = odb_validate_locations(
  coordinates[c("latitude", "longitude")],
  odb_cfg = cfg
)

odb_get_jobs(params = list(id = job$id), odb_cfg = cfg)
validated = odb_get_jobs(
  params = list(id = job$id, get_file = 1),
  odb_cfg = cfg
)

Reassocie o resultado a source_row_id pela ordem ou por uma chave preservada no arquivo de trabalho. Revise casos inesperados manualmente. A validação não decide se uma coordenada é cientificamente correta; ela informa sua relação com as Localidades existentes.

Ciclo de cada UserJob

1. Enviar um lote pequeno

Comece com algumas linhas representativas: uma simples, uma com relações e uma que você espera que produza aviso ou erro. Guarde o ID do UserJob retornado.

2. Acompanhar o processamento

O estado pode ser Submitted, Processing, Success, Failed ou Cancelled. Acompanhe também o percentual e o log. Não envie novamente o mesmo lote apenas porque a tarefa ainda está processando.

3. Examinar resultados por linha

Na interface, abra os resultados do UserJob. O arquivo de resultados pode conter:

• row: número da linha recebida;
• status: resultado daquela linha;
• id: ID criado ou encontrado no OpenDataBio;
• first_field e first_value: valores usados para reconhecer a entrada;
• error: motivo pelo qual a linha não foi concluída;
• warning: situação que exige revisão, mesmo quando existe um ID.

Uma tarefa com estado Success pode conter avisos ou resultados que reutilizam registros existentes. Valide linha por linha.

4. Reconciliar com a tabela enviada

Baixe os resultados e acrescente-os à tabela de trabalho sem alterar a cópia original. Um padrão útil é manter:

Use row para relacionar o arquivo de resultados à ordem enviada e confira first_field/first_value antes de copiar o ID. Se o cliente R fornecer uma tabela de IDs afetados, aplique a mesma conferência. Nunca associe IDs apenas pela posição depois de ordenar ou filtrar uma das tabelas.

5. Validar os registros no servidor

Consulte por ID ou UUID os registros criados ou reutilizados e compare campos essenciais com a entrada. Para dados espaciais, confira o mapa; para Taxons, confira nome aceito, autoria e pai; para medições, confira Trait, objeto, valor, unidade, data e Pessoa.

6. Corrigir somente as linhas necessárias

Separe erros de entrada, duplicatas legítimas e falhas externas. Corrija a tabela de trabalho e envie somente as linhas pendentes. Registre o novo ID de UserJob para manter a rastreabilidade de cada tentativa.

7. Avançar para a próxima dependência

Somente depois de reconciliar e validar uma etapa, use seus IDs na etapa seguinte. Por exemplo:

1. importe Pessoas e registre person_id;
2. use esses IDs em coletores, identificadores e medidores;
3. importe Taxons e Localidades e registre seus IDs;
4. importe Indivíduos usando dataset, coletores, Taxon e Localidade já conferidos;
5. use individual_id para Vouchers, medições, mídias e histórico de identificações.

Exemplo concreto de encadeamento

Considere uma planilha de árvores medidas em parcelas:

1. Pessoas: localize ou importe coletores e medidores; acrescente seus IDs.
2. Referências: importe DOIs ou BibTeX usados nas identificações e Traits.
3. Taxons: valide nomes publicados e resolva morfotipos separadamente.
4. Parcelas: localize as parcelas existentes; crie apenas as ausentes.
5. Coordenadas: execute locations-validation e revise os pontos fora das parcelas ou unidades administrativas esperadas.
6. Traits: localize dbh, altura e demais variáveis por export_name.
7. Indivíduos: importe um lote piloto, recupere individual_id e confira no mapa.
8. Medições: use individual_id, trait_id, Pessoa, data e dataset.
9. Validação final: consulte indivíduos e medições, compare contagens e preserve os arquivos de resultados dos UserJobs.

Encerrar a importação

Uma importação está concluída quando:

• todas as linhas possuem resultado documentado;
• erros foram corrigidos ou justificados;
• avisos foram revisados;
• IDs e UUIDs foram incorporados à tabela de trabalho;
• registros foram consultados novamente no OpenDataBio;
• contagens, relações, datas, coordenadas e permissões foram conferidas;
• os arquivos de entrada, resultados e IDs dos UserJobs foram preservados.

Continue nos tutoriais de importação com R para exemplos de cada objeto.