Ir para o conteúdo

Manual de estilo

Nessa seção listamos todos os padrões do manual de estilo e diretrizes de dados que propomos para o Datahub. Seguir estes padrões é de grande importância para garantir a qualidade dos metadados e, em última instância, dos dados.

Nomeação de bases e tabelas

Conjuntos de dados (dataset_id)

Um conjunto de dados (ou dataset em inglês) é uma unidade organizacional dentro do BigQuery que agrupa tabelas relacionadas por tema, fonte ou propósito. Funciona como uma "pasta" ou "esquema" que contém múltiplas tabelas com características similares, facilitando a organização, governança e controle de acesso aos dados.

No contexto do DataHub do Instituto Igarapé, os conjuntos de dados servem para categorizar e organizar as tabelas conforme sua fase de processamento e domínio temático.

Padrão de Prefixos

Temos 4 prefixos que indicam o tipo de conjunto de dados

No projeto igarape-datahub-dev

  • Todos os conjuntos de dados tem um sufixo que indica se foram ou não validadas.

1.1 Prefixo bruto_ - São conjuntos de dados cujas tabelas ainda não passaram pelo procedimento de padronização e validação dos dados com DBT

1.2 Prefixo tratada_ - São conjuntos de dados cujas tabelas já passaram pelo procedimento de padronização e validação dos dados com DBT e estão prontas para irem para o projeto de produção, onde serão consumidas para realizar análises.

1.3 Padrão de nomenclatura para conjuntos de dados com prefixo bruto_, tratada_ e validada_ (veremos o significado do prefixo validada_ na seção seguinte)

<prefixo>_<organization_id\>_<descrição\>, onde organization_id segue por padrão a abrangência geográfica da organização que publica o conjunto:

organization_id
Mundial mundo_<organizacao>
Federal <sigla_pais>_<organizacao>
Estadual <sigla_pais>_<sigla_uf>_<organizacao>
Municipal <sigla_pais>_<sigla_uf>_<cidade>_<organizacao>
  • sigla_pais e sigla_uf são sempre 2 letras minúsculas;
  • organizacao é o nome ou sigla (de preferência) da organização que publicou os dados orginais (ex: ibge, tse, inep).

Não sabe como nomear a organização?

Sugerimos que vá no site da mesma e veja como ela se autodenomina (ex: DETRAN-RJ seria bruto_br_rj_detran)

No projeto igarape-datahub

1.1 Prefixo validada_ - São replicas dos conjuntos de dados com prefixo tratada_ extraidas do projeto datahub-igarape-dev. Estes conjuntos passaram pelo processo de validação dos dados #TODO adicionar referecencia para o processo de validação# e estão prontas para serem utilizadas na construção de indicadores, dashboards e demais produtos de dados.

O que significa validação?

A validação significa que as tabelas passaram pelas etapas de padronização e tratamento acordadas e estão prontas para serem utilizadas nos mais diversos produtos de dados.

1.2 Prefixo analise_

  • São conjuntos de dados que possuem tabelas construídas a partir de tabelas validadas (prefixo validada_) presentes nos conjuntos de dados do projeto igarape-datahub.

1.2.1 Padrão para conjuntos de dados com prefixos analise_

analise_<escopo>_<tema>_<descrição>

escopo - Abrangência geográfica da análise:

  • br - Nacional (Brasil)
  • br_<uf> - Estadual (ex: br_rj, br_sp)
  • br_<uf>_<cidade> - Municipal (ex: br_rj_rio, br_sp_saopaulo)
  • mundo - Global/Internacional

tema - Categoria temática da análise:

  • seguranca
  • economia
  • educacao
  • saude
  • social
  • urbano
  • justica
  • drogas
  • tecnologia

descrição - Descrição específica da análise (máximo 3 palavras, separadas por underscore)

exemplos

  • analise_br_seguranca_homicidios_tendencias
  • analise_br_rj_urbano_densidade_populacional
  • analise_mundo_economia_pib_comparativo
  • analise_br_sp_educacao_evasao_escolar
  • analise_br_seguranca_feminicidios_perfil

1.3 Prefixo projeto_

  • São conjuntos de dados relacionados a um projeto específico do Instituto Igarapé. Estas tabelas podem ser construidas com tabelas que possuam prefixos de analise_ e validada_

1.3.1 Padrão para conjuntos de dados com prefixos projeto_

projeto_<nome_projeto>_<tipo_dados>_<descrição>

nome_projeto - Nome identificador do projeto (máximo 2 palavras):

  • Usar nome curto e descritivo do projeto
  • Substituir espaços por underscore
  • Usar apenas letras minúsculas
  • Exemplos: observatorio_seguranca, mapa_violencia, agenda_2030

tipo_dados - Tipo de dados ou finalidade:

  • indicadores - Indicadores principais do projeto
  • dashboard - Dados específicos para dashboard
  • relatorio - Dados para relatórios
  • metodologia - Dados metodológicos
  • monitoramento - Dados de monitoramento
  • baseline - Dados de linha de base
  • resultados - Dados de resultados/impactos

descrição - Descrição específica dos dados (máximo 2 palavras)

exemplos

  • projeto_observatorio_seguranca_indicadores_homicidios
  • projeto_mapa_violencia_dashboard_regional
  • projeto_agenda_2030_monitoramento_ods
  • projeto_igarape_digital_metodologia_ia
  • projeto_mulheres_paz_baseline_violencia
  • projeto_cidades_seguras_resultados_intervencoes

Tabelas (table_id)

Nomear tabelas é algo menos estruturado e, por isso, requer bom senso. Mas temos algumas regras:

  • Se houver tabelas para diferentes entidades, incluir a entidade no começo do nome. Exemplo: municipio_valor, uf_valor.
  • Não incluir a unidade temporal no nome. Exemplo: nomear municipio, e não municipio_ano.
  • Deixar nomes no singular. Exemplo: escola, e não escolas.
  • Nomear de microdados as tabelas mais desagregadas. Em geral essas tem dados a nível de pessoa ou transação.

Exemplos de <prefixo>_dataset_id.table_id

Exemplos 

tratada_br_ms_cnes
validada_br_correio_agencia

Formatos de tabelas

Tabelas que pertencem a conjuntos de dados com prefixos bruto_, validada_,tratada_ devem na medida do possível, estar no formato long, ao invés de wide.

Tabelas que pertencem a conjuntos de dados com prefixos analise_, projeto_ podem estar em ambos formatos wide ou long.

Nomeação de variáveis

Nomes de variáveis devem respeitar algumas regras:

  • Usar ao máximo nomes já presentes no repositório. Exemplos: ano, mes, id_municipio, sigla_uf, idade, cargo, resultado, votos, receita, despesa, preco, etc.
  • Respeitar padrões das tabelas de diretórios.
  • Ser o mais intuitivo, claro e extenso possível.
  • Ter todas letras minúsculas (inclusive siglas), sem acentos, conectados por _.
  • Não incluir conectores como de, da, dos, e, a, em, etc.
  • Só ter o prefixo id_ quando a variável representar chaves primárias de entidades (que eventualmente teriam uma tabela de diretório).
    • Exemplos que tem: id_municipio, id_uf, id_escola, id_pessoa.
    • Exemplos que não tem: rede, localizacao.
    • Importante: quando a base está em inglês id vira um sufixo
  • Só ter sufixos de entidade quando a entidade da coluna for diferente da entidade da tabela.
    • Exemplos que tem: numa tabela com entidade pessoa, uma coluna sobre PIB municipal se chamaria pib_municipio.
    • Exemplos que não tem: numa tabela com entidade pessoa, características da pessoa se chamariam nome, idade, sexo, etc.
  • Lista de prefixos permitidos
    • nome_,
    • data_,
    • quantidade_,
    • proporcao_ (variáveis de porcentagem 0-100%),
    • taxa_,
    • razao_,
    • indice_,
    • indicador_ (variáveis do tipo booleano),
    • tipo_,
    • sigla_,
    • sequencial_.
  • Lista de sufixos comuns
    • _pc (per capita)

Ordenamento de variáveis

A ordem de variáveis em tabelas é padronizada para manter uma consistência no repositório. Nossas regras são:

  • Chaves primárias à esquerda, em ordem descendente de abrangência;
  • No meio devem estar variáveis qualitativas da linha;
  • As últimas variáveis devem ser os valores quantitativos em ordem crescente de relevância;
  • Exemplo de ordem: ano, sigla_uf, id_municipio, id_escola, rede, nota_ideb;
  • Dependendo da tabela, pode ser recomendado agrupar e ordenar variáveis por temas.

Tipos de variáveis

Nós utilizamos algumas das opções de tipos do BigQuery: string, int64, float64, date, time, geography.

Quando escolher:

  • string:
    • Variáveis de texto
    • Chaves de variáveis categóricas com dicionário ou diretório
  • int64:
    • Variáveis de números inteiros com as quais é possível fazer contas (adição, subtração)
    • Variáveis do tipo booleanas que preenchemos com 0 ou 1
  • float64:
    • Variáveis de números com casas decimais com as quais é possível fazer contas (adição, subtração)
  • date:
    • Variáveis de data no formato YYYY-MM-DD
  • time:
    • Variáveis de tempo no formato HH:MM:SS
  • geography:
    • Variáveis de geografia

Unidades de medida

  1. registro das unidades na coluna nas tabelas no BQ
  2. Colunas que tem unidades de medida devem ter o registro da unidade na descrição da coluna

  3. |

  4. tabelas de arquitetura ficarao disp em arquivs csv no repositório datalake-2025

Dicionário

  • Falar que pela característica das tabelas os valores das chaves já estão nas tabelas

Quais variáveis manter, quais adicionar e quais remover

Mantemos nossas tabelas parcialmente normalizadas, e temos regras para quais variáveis incluirmos em produção. Elas são:

  • Remover variáveis de nomes de entidades que já estão em diretórios. Exemplo: retirar municipio da tabela que já inclui id_municipio.
  • Remover variáveis servindo de partição. Exemplo: remover ano e sigla_uf se a tabela é particionada nessas duas dimensões.
  • Adicionar chaves primárias principais para cada entidade já existente. Exemplo: adicionar id_municipio a tabelas que só incluem id_municipio_tse.
  • Manter todas as chaves primárias que já vem com a tabela, mas (1) adicionar chaves relevantes (e.g. sigla_uf, id_municipio) e (2) retirar chaves irrelevantes (e.g. regiao).

Limpando STRINGs

  • Variáveis categóricas: inicial maiúscula e resto minúsculo, com acentos.
  • STRINGs não-estruturadas: manter igual aos dados originais.

Formatos de valores

  • Decimal: formato americano, i.e. sempre . (ponto) ao invés de , (vírgula).
  • Data: YYYY-MM-DD
  • Horário (24h): HH:MM:SS
  • Datetime (ISO-8601): YYYY-MM-DDTHH:MM:SS.sssZ
  • Valor nulo: "" (csv), NULL (Python), NA (R), . ou "" (Stata)
  • Proporção/porcentagem: entre 0-100

Particionamento de tabelas

O que é particionamento e qual seu objetivo ?

De forma resumida, particionar uma tabela é dividi-la em vários blocos/partes. O objetivo central é diminuir os custos financeiros e aumentar a perfomance, visto que, quanto maior o volume de dados, consequentemente será maior o custo de armazenamento e consulta.

A redução de custos e o aumento de perfomance acontece, principalmente, porque a partição permite a reorganização do conjunto de dados em pequenos blocos agrupados. Na prática, realizando o particionamento, é possível evitar que uma consulta percorra toda a tabela só para trazer um pequeno recorte de dados.

Um exemplo prático da nossa querida RAIS:

  • Sem utilizar filtro de partição:

Para esse caso o Bigquery varreu todas (*) as colunas e linhas do conjunto. Vale salientar que esse custo ainda não é tão grande, visto que a base já foi particionada. Caso esse conjunto não tivesse passado pelo processo de particionamento, essa consulta custaria muito mais dinheiro e tempo, já que se trata de um volume considerável de dados.

image

  • Com filtro de partição:

Aqui, filtramos pelas colunas particionadas ano e sigla_uf. Dessa forma, o Bigquery só consulta e retorna os valores da pasta ano e da subpasta sigla_uf.

image

Quando particionar uma tabela?

A primeira pergunta que surge quando se trata de particionamento é: a partir de qual quantidade de linhas uma tabela deve ser particionada? A documentação do GCP não define uma quantidade x ou y de linhas que deve ser particionada. O ideal é que as tabelas sejam particionadas, com poucas exceções. Por exemplo, tabelas com menos de 10.000 linhas, que não receberão mais ingestão de dados, não tem um custo de armazenamento e processamento altos e, portanto, não há necessidade de serem particionadas.

Como particionar uma tabela?

Se os dados estão guardados localmente, é necessário:

  1. Criar as pastas particionadas na sua pasta de /output, na linguagem que você estiver utilizando.

Exemplo de uma tabela particionada por ano e mes, utilizando python:

for ano in [*range(2005, 2020)]:
  for mes in [*range(1, 13)]:
    particao = output + f'table_id/ano={ano}/mes={mes}'
    if not os.path.exists(particao):
      os.makedirs(particao)
2. Salvar os arquivos particionados. 
for ano in [*range(2005, 2020)]:
  for mes in [*range(1, 13)]:
    df_particao = df[df['ano'] == ano].copy() # O .copy não é necessário é apenas uma boa prática
    df_particao = df_particao[df_particao['mes'] == mes]
    df_particao.drop(['ano', 'mes'], axis=1, inplace=True) # É preciso excluir as colunas utilizadas para partição
    particao = output + f'table_id/ano={ano}/mes={mes}/tabela.csv'
    df_particao.to_csv(particao, index=False, encoding='utf-8', na_rep='')

Exemplos de tabelas particionadas em R:

Exemplo de como particionar uma tabela em SQL:

CREATE TABLE `dataset_id.table_id` as (
    ano  INT64,
    mes  INT64,
    col1 STRING,
    col1 STRING
) PARTITION BY ano, mes
OPTIONS (Description='Descrição da tabela')

Regras importantes de particionamento.

  • Os tipos de colunas que o BigQuery aceita como partição são:

  • Coluna de unidade de tempo: as tabelas são particionadas com base em uma coluna de TIMESTAMP, DATE ou DATETIME.

  • Tempo de processamento: as tabelas são particionadas com base no carimbo de data/hora quando o BigQuery processa os dados.

  • Intervalo de números inteiros: as tabelas são particionadas com base em uma coluna de números inteiros.

  • Os tipos de colunas que o BigQuery não aceita como partição são: BOOL, FLOAT64, BYTES, etc.

  • O BigQuery aceita no máximo 4.000 partições por tabela.

  • Aqui na BD as tabelas geralmente são particionadas por: ano, mes, trimestre e sigla_uf.

  • Note que ao particionar uma tabela é preciso excluir a coluna correspondente. Exemplo: é preciso excluir a coluna ano ao particionar por ano.

Diretórios

Diretórios são as pedras importantes da estrutura do Datahub. As regras para gerenciar diretórios são:

  • Diretórios representam entidades do repositório que tenham chaves primárias (e.g. uf, município, escola) e unidades de data-tempo (e.g. data, tempo, dia, mes, ano).
  • Cada tabela de diretório tem ao menos uma chave primária com valores únicos e sem nulos. Exemplos: municipio:id_municipio, uf:sigla_uf.
  • Nomes de variáveis com prefixo id_ são reservadas para chaves primárias de entidades.