Universalizando o acesso a dados de qualidade no Brasil.

A Base dos Dados é um datalake público no Google BigQuery com os principais conjuntos de dados abertos do Brasil. Na BD você encontra tabelas tratadas e prontas para uso de forma gratuita. Disponibilizamos e mantemos neste projeto pacotes de acesso à BD em diferentes linguagens.

O projeto faz parte da Base dos Dados, uma organização sem fins lucrativos com a missão de universalizar o acesso a dados de qualidade para todes.

Versões atuais

| R | Python | Stata |-----|-----|-----| | install.packages("basedosdados") | pip install basedosdados | - | | | | | | | | | |

Encontre aqui

• 📝 Como citar o projeto
• 🐍 Usando em Python
• Usando em R
• Análises e tutoriais:
  • Códigos de análises publicadas nas redes, workshops e artigos ↗
  • Youtube ↗
  • Blog ↗
• 👥 Como contribuir ↗
• 💚 Apoie o projeto! ↗

Como citar o projeto

O projeto (software) está sob licenca MIT - logo, pode ser utilizado e modificado sem restrições desde que sejam remetidos os direitos autorais originais - veja o texto de referência aqui.

Caso queira citar o projeto numa publicação, artigo ou na web, utilize o modelo no menu ao lado conforme a imagem.

💡 Quer divulgar seu projeto nas nossas redes? Envie para contato@basedosdados.org

Usando em Python

Instale

Com pip:

bash pip install basedosdados

Com uv:

sh uv add basedosdados

Com poetry:

sh poetry add basedosdados

Acesse uma tabela

```python import basedosdados as bd

df = bd.readtable('bribgepib', 'municipio', billingproject_id="") ```

Caso esteja acessando da primeira vez, vão aparecer alguns passos na tela para autenticar seu projeto - basta segui-los!

É necessário criar um projeto para que você possa fazer as queries no nosso repositório. Ter um projeto é de graça e basta ter uma conta Google (seu gmail por exemplo). Veja aqui como criar um projeto no Google Cloud.

Se possível, armazene suas credenciais em um arquivo dotenv: "billing_project_id=<suas_credenciais_do_projeto>" >> .env

Faça uma consulta

```python import basedosdados as bd

Bens dos candidatos de Tocantins em 2020

query = """ SELECT * FROM basedosdados.br_tse_eleicoes.bens_candidato WHERE ano = 2020 AND sigla_uf = 'TO' """

df = bd.readsql(query, billingproject_id="") ```

Caso esteja acessando da primeira vez, vão aparecer alguns passos na tela para autenticar seu projeto - basta segui-los!

Defina paramêtros utilizando as configurações do pacote

```py import basedosdados as bd

seta o billingprojectid global

bd.config.billingprojectid = ''

query = """ SELECT * FROM basedosdados.br_bd_diretorios_brasil.municipio """

df = bd.read_sql(query=query) ```

Para saber mais, veja os exemplos ou a documentação da API

Criando múltiplas configurações

Caso você precise ter uma configuração adicional, com uma service account diferente, você pode criar uma configuração e utilizá-la em conjunto com a default, apenas alterando um atributo. Você deverá fazer o processo abaixo usando o terminal, mas esta forma só funcionará no Python.

Para isso, siga os seguintes passos:

1. Renomeie a pasta com o comando abaixo (pode ser o nome que quiser) bash mv ~/.basedosdados ~/.basedosdados_default
2. Neste momento, o pacote não terá a configuração padrão. Assim, ao rodar o comando bash basedosdados config init ele irá criar uma nova configuração padrão, que será salva na pasta ~/.basedosdados (que será recriada). Lembre-se de, no passo em que é oferecido um link do Google Cloud Platform (GCP) para criar a nova service account, observar que seu navegador esteja logado com a conta que você deseja utilizar.
3. Faça todo o processo como anteriormete, passando os parâmetros que deseja utilizar com esta nova conta, como o path dos metadados, o nome do bucket do Google Cloud Storage, etc.
4. Ao salvar as novas service accounts (prod e staging), certifique-se de salvar na pasta .basedosdados criada no passo 1. Na verdade, esta é apenas a repetição do processo de criação de uma nova configuração.
5. Renomeie a pasta criada no passo 1 para o nome que desejar, como ~/.bd_minha_nova_conta.
6. Caso você queira que a primeira configuração seja a padrão, retorne o nome da pasta modificada anterioremnte (.basedosdados_default) para o valor utilizado como padrão pelo pacote basedosdados, usando o comando mv ~/.basedosdados_default ~/.basedosdados.
7. A partir de agora, você poderá usar a nova conta (no Python), bastando utilizar o seguinte processo: py import basedosdados as bd bd.config.project_config_path = f"{home}/.bd_minha_nova_conta" e, se quiser voltar para a configuração padrão, basta utilizar o comando py bd.config.project_config_path = f"{home}/.basedosdados" Importante observar que, ao alterar o path de configuração do Python ele valerá para a sessão. Então é recomendável que ele seja usado com cuidado, evitanto trocas numa mesma sessão - especialmente quando estiver usando Jupyter Notebook onde é comum a reutilização de células anteriores, sem redefinição de variáveis e atributos anteriormente setados.

Usando em R

Instalação

```R install.packages("basedosdados")

ou a versão de desenvolvimento

devtools::install_github("basedosdados/sdk", subdir = "r-package") ```

Consultas

read_sql executa queries no banco e as devolve em dataframes (sempre na classe tibble), download escreve o resultado da query em um arquivo .csv no disco.

```r library(basedosdados)

setbillingid("id do seu projeto aqui") # autenticação para acesso aos dados

pibpercapita <- " SELECT pib.idmunicipio , pop.ano, pib.PIB / pop.populacao as pibpercapita FROM `basedosdados.bribgepib.municipioas pib INNER JOINbasedosdados.bribgepopulacao.municipio` as pop ON pib.idmunicipio = pop.id_municipio AND pib.ano = pop.ano"

(data <- readsql(pibpercapita)) # leia os dados em memória download(pibpercapita, "pibper_capita.csv") # salve os dados em disco ```

Ou use o nosso backend para o dplyr e faça queries com código, sem SQL.

```r query <- basedosdados::bdplyr("brinepideb.municipio") %>% dplyr::select(ano, idmunicipio, siglauf, ideb) %>% dplyr::filter(siglauf == "AC", ano < 2021) %>% dplyr::groupby(ano) %>% dplyr::summarise(ideb_medio = mean(ideb, na.rm = TRUE))

basedosdados::bdcollect(query) # retorne como um tibble basedosdados::bdwritecsv(query, "idebmedio.csv") basedosdados::bdwriterds(query, "ideb_medio.rds") ```

bd_write é uma extensão para formatos customizados.

r basedosdados::bd_write(query, .write_fn = writexl::write_xlsx, "ideb_medio.xlsx") basedosdados::bd_write(query, .write_fn = jsonlite::write_json, "ideb_medio.json") basedosdados::bd_write(query, .write_fn = haven::write_dta, "ideb_medio.dta")

O argumento .write_fn espera uma função que receba como argumento um tibble e um endereço de escrita, compatível com a interface convencional da língua para escrever arquivos em disco. A princípio, toda função write_* disponível no CRAN deve funcionar.

Caso encontre algum problema no pacote e queira ajudar, basta documentar o problema em um exemplo mínimo reprodutível e abrir uma issue.

Metadados e buscas

Você pode fazer buscas por tabelas usando palavras-chave ou buscar descrições de conjuntos e tabelas:

r dataset_search("educação") get_dataset_description("br_sp_alesp") get_table_description("br_sp_alesp", "deputado")

Atenção

Caso esteja acessando da primeira vez, vão aparecer alguns passos na tela para autenticar seu projeto com sua conta google e possivelmente na Tidyverse API - basta segui-los! As credenciais ficam armazenadas no computador então usuários com mais de uma máquina talvez precisem autenticar mais de uma vez. É necessário criar um projeto para que você possa fazer as queries no nosso repositório. Ter um projeto é de graça e basta ter uma conta Google (seu gmail por exemplo). [Veja aqui como criar um projeto no Google Cloud]https://basedosdados.org/docs/accessdatabq#bigquery). Se possível, armazene suas credenciais em um arquivo dotenv, em bash o comando é "billing_project_id=<suas_credenciais_do_projeto>" >> .env. Veja aqui como criar um arquivo dotenv.

Contribua

Leia nosso guia de contribuição