Ir para o conteúdo

Suba dados na BD+

Por que minha organização deve subir dados na BD+?

  • Capacidade de cruzar suas bases com dados de diferentes organizações de forma simples e fácil. Já são centenas de conjuntos de dados públicos das maiores organizações do Brasil e do mundo presentes no nosso datalake.

  • Compromisso com a transparência, qualidade dos dados e desenvolvimento de melhores pesquisas, análises e soluções para a sociedade. Não só democratizamos o acesso a dados abertos, mas também dados de qualidade. Temos um time especializado que revisa e garante a qualidade dos dados adicionados ao datalake.

  • Participação de uma comunidade que cresce cada vez mais: milhares de jornalistas, pesquisadores(as), desenvolvedores(as), já utilizam e acompanham a Base dos Dados.

Passo a passo para subir dados

Quer subir dados na BD+ e nos ajudar a construir esse repositório? Maravilha! Organizamos tudo o que você precisa no manual abaixo, em 10 passos.

Para facilitar a explicação, vamos seguir um exemplo já pronto com dados da RAIS.

Você pode navegar pelas etapas no menu à esquerda.

Sugerimos fortemente que entre em nosso canal no Discord para tirar dúvidas e interagir com a equipe e outros(as) colaboradores(as)! 😉

Antes de começar

Alguns conhecimentos são necessárias para realizar esse processo:

  • Python, R, SQL e/ou Stata: para criar os códigos de captura e limpeza dos dados.
  • Linha de comando: para configurar seu ambiente local e conexão com o Google Cloud.
  • Github: para subir seu código para revisão da nossa equipe.

Não tem alguma dessas habilidades, mas quer colaborar?

Temos um time de dados que pode te ajudar, basta entrar no nosso Discord e mandar uma mensagem em #quero-contribuir.

1. Informar seu interesse para a gente

Mantemos a lista de conjuntos que ainda não estão na BD+ no nosso Github. Para começar a subir uma base do seu interesse, basta abrir uma nova issue de dados e preencher as informações indicadas por lá.

Caso sua base (conjunto) já esteja listada, basta marcar seu usuário do Github como assignee.

2. Baixar nossa pasta template para dados

Baixe aqui a pasta template e renomeie para o nome do seu conjunto de dados, <dataset_id> (veja aqui como nomear seu conjunto). Ela facilita todos os passos daqui pra frente. Sua estrutura é a seguinte:

  • <dataset_id>/
    • code/: Códigos necessários para captura e limpeza dos dados (veja no passo 5).
    • input/: Contém todos os arquivos com dados originais, exatamente como baixados da fonte primária. Esses arquivos não devem ser modificados.
    • output/: Arquivos finais, já no formato pronto para subir na BD+.
    • tmp/: Quaisquer arquivos temporários criados pelo código em /code no processo de limpeza e tratamento.
    • extra/

As pastas input, output e tmp não serão commitadas para o seu projeto e existirão apenas localmente.

3. Preencher as tabelas de arquitetura

As tabelas de arquitetura determinam qual a estrutura de cada tabela do seu conjunto de dados. Elas definem, por exemplo, o nome, ordem e metadados das colunas, e como uma coluna deve ser tratada quando há mudanças em versões (por exemplo, se uma coluna muda de nome de um ano para o outro).

Cada tabela do conjunto de dados deve ter sua própria tabela de arquitetura (planilha), que pode ser preenchida no Google Drive ou localmente (Excel, editor de texto).

Exemplo: RAIS - Tabelas de arquitetura

As tabelas de arquitetura preenchidas podem ser consultadas aqui. Seguindo nosso manual de estilo, nós renomeamos, definimos os tipos, preenchemos descrições, indicamos se há dicionário ou diretório, preenchemos campos (e.g. cobertura temporal e unidade de medida) e fizemos a compatibilização entre anos para todas as variáveis (colunas).

  • name: nome da coluna.

  • bigquery_type: tipo de dado do BigQuery (veja quais são no nosso manual de estilo).

  • description: descrição dos dados que estão nesta coluna.

  • temporal_coverage: cobertura temporal da variável nessa tabela (veja como preencher no nosso manual de estilo).

  • covered_by_dictionary: indicar se a variável é coberta por dicionário. Opções de respostas são: yes , no.

  • directory_column: se a coluna for coberta por um dicionário da BD, usar o formato [DATASET_ID].[TABLE]:[COLUNA] (e.g. br_bd_diretorios_data_tempo.ano:ano). Caso contrário, deixe em branco

  • measurement_unit: qual unidade de medida da coluna (veja as unidades de medida disponíveis para preenchimento no nosso Github.

  • has_sensitive_data: indicar se a coluna possui dados sensíveis (e.g. CPF identificado, dados de conta bancária, etc). Opções de preenchimento são: yes, no.

  • observations: observações de tratamento que precisam ser evidenciados. Indicar, por exemplo, porque determinada coluna foi criada ou modificada.

  • original_name: indicar o nome original de cada coluna para cada ano, no formato original_name_YYYY. No exemplo da RAIS, existiam colunas que deixaram de existir em determinados anos. Por isso, criamos colunas à direita em ordem descendente (e.g. 2020, 2019, 2018, ...).

Para as que foram excluídas da versão em produção, deixamos seu nome como (deletado) e não preenchemos nenhum metadado. Por exemplo, a coluna Municipio da tabela microdados_vinculos não foi adicionada pois por padrão usamos somente o código IBGE para identificar municípios (seu nome fica numa tabela de Diretórios). Logo, ela aparece com o nome (deletado) na respectiva tabela de arquitetura (penúltima linha).

Quando terminar de preencher as tabelas de arquitetura, entre em contato com a equipe da Base dos Dados ou nossa comunidade para validar tudo. É importante ter certeza que está fazendo sentido antes de começar a escrever código.

4. Escrever código de captura e limpeza de dados

Após validadas as tabelas de arquitetura, podemos escrever os códigos de captura e limpeza dos dados.

  • Captura: Código que baixa automaticamente todos os dados originais e os salva em /input. Esses dados podem estar disponíveis em portais ou links FTP, podem ser raspados de sites, entre outros.

  • Limpeza: Código que transforma os dados originais salvos em /input em dados limpos, salva na pasta /output, para, posteriormente, serem subidos na BD+.

Cada tabela limpa para produção pode ser salva como um arquivo .csv único ou, caso seja muito grande (e.g. acima de 100-200 mb), ser particionada no formato Hive em vários sub-arquivos .csv. Nossa recomendação é particionar tabelas por ano, mes, sigla_uf ou no máximo por id_municipio. A tabela microdados_vinculos da RAIS, por exemplo, é uma tabela muito grande (+250GB) por isso nós particionamos por ano e sigla_uf. O particionamento foi feito usando a estrutura de pastas /microdados_vinculos/ano=YYYY/sigla_uf=XX.

No pacote basedosdados você encontra funções úteis para limpeza dos dados

Definimos funções para particionar tabelas de forma automática, criar variáveis comuns (e.g. sigla_uf a partir de id_uf) e outras. Veja em Python e R

Padrões necessários no código

  • Devem ser escritos em Python, R ou Stata - para que a revisão possa ser realizada pela equipe.
  • Pode estar em script (.py, .R, ...) ou notebooks (Google Colab, Jupyter, Rmarkdown, etc).
  • Os caminhos de arquivos devem ser atalhos relativos à pasta raíz (<dataset_id>), ou seja, não devem depender dos caminhos do seu computador.
  • A limpeza deve seguir nosso manual de estilo e as melhores práticas de programação.

Exemplo: PNAD Contínua - Código de limpeza

O código de limpeza foi construído em R e pode ser consultado aqui.

5. (Caso necessário) Organizar arquivos auxiliares

É comum bases de dados serem disponibilizadas com arquivos auxiliares. Esses podem incluir notas técnicas, descrições de coleta e amostragem, etc. Para ajudar usuários da Base dos Dados terem mais contexto e entenderem melhor os dados, organize todos esses arquivos auxiliares em /extra/auxiliary_files.

Fique à vontade para estruturar sub-pastas como quiser lá dentro. O que importa é que fique claro o que são esses arquivos.

6. (Caso necessário) Criar tabela dicionário

Muitas vezes, especialmente com bases antigas, há múltiplos dicionários em formatos Excel ou outros. Na Base dos Dados nós unificamos tudo em um único arquivo em formato .csv - um único dicionário para todas as colunas de todas as tabelas do seu conjunto.

Detalhes importantes de como construir seu dicionário estão no nosso manual de estilo.

Exemplo: RAIS - Dicionário

O dicionário completo pode ser consultado aqui. Ele já possui a estrutura padrão que utilizamos para dicionários.

7. Configure suas credenciais localmente e prepare o ambiente

No seu terminal:

  1. Instale nosso cliente: pip install basedosdados.
  2. Rode basedosdados config init e siga o passo a passo para configurar localmente com as credenciais de seu projeto no Google Cloud.

Caso seu ambiente de produção não permita o uso interativo do nosso cliente ou apresente alguma outra dificuldade relativa a esse modo de configuração, você pode configurar o basedosdados a partir de variáveis de ambiente da seguinte forma:

 export BASEDOSDADOS_CONFIG=$(cat ~/.basedosdados/config.toml | base64)
 export BASEDOSDADOS_CREDENTIALS_PROD=$(cat ~/.basedosdados/credentials/prod.json | base64)
 export BASEDOSDADOS_CREDENTIALS_STAGING=$(cat ~/.basedosdados/credentials/staging.json | base64)
  1. Clone um fork do nosso repositório localmente.
  2. Dê um cd para a pasta local do repositório e abra uma nova branch com git checkout -b [BRANCH_ID]. Todas as adições e modificações serão incluídas nessa branch.

8. Subir tudo no Google Cloud

Tudo pronto! Agora só falta subir para o Google Cloud e enviar para revisão. Para isso, vamos usar o cliente basedosdados (disponível em linha de comando e Python) que facilita as configurações e etapas do processo.

Configure seu projeto no Google Cloud e um bucket no Google Storage

Os dados vão passar ao todo por 3 lugares no Google Cloud:

  1. Storage: local onde serão armazenados o arquivos "frios" (arquiteturas, dados, arquivos auxiliares).
  2. BigQuery: super banco de dados do Google, dividido em 2 projetos/tipos de tabela:
    • Staging: banco para teste e tratamento final do conjunto de dados.
    • Produção: banco oficial de publicação dos dados (nosso projeto basedosdados ou o seu mesmo caso queira reproduzir o ambiente)

É necessário ter uma conta Google e um projeto (gratuito) no Google Cloud. Para criar seu projeto basta:

  1. Acessar o link e aceitar o Termo de Serviços do Google Cloud.
  2. Clicar em Create Project/Criar Projeto - escolha um nome bacana para o seu projeto, ele terá também um Project ID que será utilizado para configuração local.
  3. Depois de criado o projeto, vá até a funcionalidade de Storage e crie uma pasta (bucket) para subir os dados (pode ter o mesmo nome do projeto).

Suba e configure uma tabela no seu bucket

Aqui são dois passos: primeiro publicamos uma base (conjunto) e depois publicamos tabelas. Este processo está automatizado na criação das tabelas, conforme abaixo.

Para publicar o dataset e a(s) tabela(s):

  1. Crie a tabela no bucket, indicando o caminho do arquivo no seu local, rodando o seguinte comando no seu terminal:

    basedosdados table create [DATASET_ID] [TABLE_ID] --path <caminho_para_os_dados> --force_dataset False --if_table_exists raise --if_storage_data_exists raise --if_table_config_exists raise --columns_config_url <url_da_planilha_google>

    Se preferir, você pode usar a API do Python, da seguinte forma:

    import basedosdados as bd

tb = bd.Table(dataset_id=<dataset_id>, table_id=<table_id>)
tb.create(
    path='caminho_para_os_dados',
    force_dataset=False,
    if_table_exists='raise',
    if_storage_data_exists='raise',
    if_table_config_exists='raise',
)

    Os seguintes parâmetros podem ser usados (no terminal ou no Python):

    • -- path (obrigatório): o caminho completo do arquivo no seu computador, como: /Users/<seu_usuario>/projetos/basedosdados/mais/bases/[DATASET_ID]/output/microdados.csv. Caso seus dados sejam particionados, o caminho deve apontar para a pasta onde estão as partições. No contrário, deve apontar para um arquivo .csv (por exemplo, microdados.csv).

    • --force_dataset [True|False]: comando que cria os arquivos de configuração do dataset locais e no BigQuery.

      • True: os arquivos de configuração do dataset serão criados no seu projeto e, caso ele não exista no BigQuery, será criado automaticamente. Se você já tiver criado e configurado o dataset. Se você já tiver criado e configurado o dataset, não use esta opção, pois irá sobrescrever arquivos.

      • False: o dataset não será recriado e, se não existir, será criado automaticamente.

    • --if_table_exists [raise|replace|pass]: comando utilizado quando a tabela já existe:

      • raise: retorna mensagem de erroo.
      • replace: substitui a tabela.
      • pass: não faz nada.

    • --if_storage_data_exists [raise|replace|pass]: comando utilizado quando os dados já existem no Google Cloud Storage.

      • raise: retorna mensagem de erro
      • replace: substitui os dados existentes.
      • pass: não faz nada.

    • --if_table_config_exists [raise|replace|pass]: comando utilizado quando as configurações da tabela já existem.

      • raise: retorna mensagem de erro
      • replace: substitui as configurações da tabela existentes
      • pass: não faz nada

    • --columns_config_url [google sheets url]: comando para preencher os metadados via arquitetura construída do Google Sheets. A url precisa estar no formato https://docs.google.com/spreadsheets/d/ edit#gid=. Certifique-se de que a planilha está compartilhada com a opção "qualquer pessoa com o link pode ver"

Se o projeto não existir no BigQuery, ele será autmaticamente criado, junto com os arquivos README.md e dataset_config.yaml, que deverão ser preenchidos, segundo o modelo já criado

  1. Preencha os arquivos de configuração da tabela:

  2. /[TABLE_ID]/table_config.yaml: informações específicas da tabela.

  3. /[TABLE_ID]/publish.sql: aqui você pode indicar tratamentos finais na tabela staging em SQL para publicação (e.g. modificar a query para dar um JOIN em outra tabela da BD+ e selecionar variáveis).

  4. Publique a tabela em produção:

    basedosdados table publish [DATASET_ID] [TABLE_ID]

Consulte também nossa API para mais detalhes de cada método.

Abra o console do BigQuery e rode algumas queries para testar se foi tudo publicado corretamente. Estamos desenvolvendo testes automáticos para facilitar esse processo no futuro.

9. Validar os metadados para publicação

Para validar os metadados preenchidos nos arquivos dataset_config.yaml e table_config.yaml, o processo é simples.

  1. Valide os metadados do conjunto através do comando basedosdados metadata validate [DATASET_ID]. Para validar metadados de tabelas, basta rodar basedosdados metadata validate [DATASET_ID] [TABLE_ID].
  2. Após a revisão da nossa equipe, os dados serão publicados no CKAN.

Atualizando metadados de bases ou tabelas já existentes

Através do módulo metadata é possível também trabalhar com bases e tabelas já existentes na plataforma. Elas podem ser atualizadas a partir do procedimento que descrevemos a seguir.

  1. Rode basedosdados metadata create [DATASET_ID] para puxar os metadados do conjunto disponíveis no site para o arquivo dataset_config.yaml. Para puxar metadados de tabelas, use basedosdados metadata create [DATASET_ID] [TABLE_ID], que irá atualizo arquivo table_config.yaml
  2. Preencha os novos valores de metadados nos respectivos arquivos.
  3. Rode basedosdados metadata validate [DATASET_ID]

10. Enviar tudo para revisão

Ufa, é isso! Agora só resta enviar tudo para revisão no repositório da Base dos Dados. Crie os commits necessários e rode git push origin [BRANCH_ID]. Depois é só abrir um pull request (PR) no nosso repositório.

E agora? Nossa equipe irá revisar os dados e metadados submetidos via Github. Podemos entrar em contato para tirar dúvidas ou solicitar mudanças no código. Quando tudo estiver OK, fazemos um merge do seu pull request e os dados são automaticamente publicados na nossa plataforma!