{"id":20016577,"url":"https://github.com/basedosdados/sdk","last_synced_at":"2025-05-14T16:12:56.595Z","repository":{"id":37240834,"uuid":"294702369","full_name":"basedosdados/sdk","owner":"basedosdados","description":"⚙️ Código de manutenção do datalake (metadados e pacotes de acesso) | 📖 Docs: https://basedosdados.github.io/sdk/","archived":false,"fork":false,"pushed_at":"2025-03-20T18:29:29.000Z","size":36925,"stargazers_count":402,"open_issues_count":33,"forks_count":87,"subscribers_count":15,"default_branch":"master","last_synced_at":"2025-03-23T18:01:33.738Z","etag":null,"topics":["bigquery","dados-abertos","data-science","govtech","hacktoberfest","hacktoberfest2022","open-data","python","r","sql","transparencia"],"latest_commit_sha":null,"homepage":"https://info.basedosdados.org/links","language":"SQL","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/basedosdados.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"custom":["https://apoia.se/basedosdados"]}},"created_at":"2020-09-11T13:26:45.000Z","updated_at":"2025-03-20T18:29:32.000Z","dependencies_parsed_at":"2024-12-22T03:02:30.295Z","dependency_job_id":"79c827bd-facd-465b-9c17-5af38b06258d","html_url":"https://github.com/basedosdados/sdk","commit_stats":{"total_commits":1305,"total_committers":47,"mean_commits":27.76595744680851,"dds":0.8521072796934865,"last_synced_commit":"7d69cedde675c8af56c054e4bffe3456807bc697"},"previous_names":["base-dos-dados/bases","basedosdados/sdk"],"tags_count":33,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/basedosdados%2Fsdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/basedosdados%2Fsdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/basedosdados%2Fsdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/basedosdados%2Fsdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/basedosdados","download_url":"https://codeload.github.com/basedosdados/sdk/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246243558,"owners_count":20746311,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bigquery","dados-abertos","data-science","govtech","hacktoberfest","hacktoberfest2022","open-data","python","r","sql","transparencia"],"created_at":"2024-11-13T08:11:58.914Z","updated_at":"2025-03-30T20:02:00.291Z","avatar_url":"https://github.com/basedosdados.png","language":"SQL","readme":"\u003c!-- Header --\u003e\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://basedosdados.org\"\u003e\n    \u003cimg src=\"docs/docs/pt/images/bd_minilogo.png\" width=\"340\" alt=\"Base dos Dados\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\n\u003cp align=\"center\"\u003e\n    \u003cem\u003eUniversalizando o acesso a dados de qualidade no Brasil.\u003c/em\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/basedosdados/sdk/subscription\" target=\"_blank\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/watchers/basedosdados/sdk.svg?style=social\" alt=\"Watch\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/basedosdados/sdk/stargazers\" target=\"_blank\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/stars/basedosdados/sdk.svg?style=social\" alt=\"Start\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://twitter.com/basedosdados\" target=\"_blank\"\u003e\n    \u003cimg src=\"https://img.shields.io/twitter/follow/basedosdados?style=social\" alt=\"Tweet\"\u003e\n  \u003c/a\u003e\n\u003c!--   \u003ca href=\"https://pypi.org/project/basedosdados/\" target=\"_blank\"\u003e\n    \u003cimg src=\"https://img.shields.io/pypi/dm/basedosdados\" alt=\"PyPi\"\u003e\n  \u003c/a\u003e --\u003e\n  \u003ca href=\"https://discord.gg/huKWpsVYx4\" target=\"_blank\"\u003e\n    \u003cimg src=\"https://img.shields.io/discord/787841210433536010\" alt=\"Discord\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://apoia.se/basedosdados\" target=\"_blank\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/apoie!%E2%9D%A4%EF%B8%8F-ff69b4\" alt=\"Apoiase\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\nA Base dos Dados é um datalake público no Google BigQuery com\nos principais conjuntos de dados abertos do Brasil.\nNa BD você encontra tabelas tratadas e prontas para uso de forma\ngratuita. Disponibilizamos e mantemos neste projeto pacotes de acesso à\nBD em diferentes linguagens.\n\n\u003e O projeto faz parte da [Base dos Dados](http://basedosdados.org), uma organização sem fins lucrativos com a\nmissão de universalizar o acesso a dados de qualidade para todes.\n\n### Versões atuais\n\n| **R** | **Python** | **Stata**\n|-----|-----|-----|\n| `install.packages(\"basedosdados\")` | `pip install basedosdados` | - |\n| \u003ca href=\"https://CRAN.R-project.org/package=basedosdados\" target=\"_blank\"\u003e\u003cimg src=\"https://www.r-pkg.org/badges/version/basedosdados\"\u003e\u003c/a\u003e | \u003ca href=\"https://pypi.org/project/basedosdados\" target=\"_blank\"\u003e\u003cimg src=\"https://badge.fury.io/py/basedosdados.svg\"\u003e\u003c/a\u003e | \u003ca href=\"https://github.com/basedosdados/sdk/pull/754\" target=\"_blank\"\u003e\u003cimg src=\"https://img.shields.io/badge/development-0.1.0-yellow\"\u003e\u003c/a\u003e\n| \u003ca href=\"https://CRAN.R-project.org/package=basedosdados\" target=\"_blank\"\u003e\u003cimg src=\"http://cranlogs.r-pkg.org/badges/basedosdados\"\u003e\u003c/a\u003e | \u003ca href=\"https://pypi.org/project/basedosdados\" target=\"_blank\"\u003e\u003cimg src=\"https://img.shields.io/pypi/dm/basedosdados?color=blue\"\u003e\u003c/a\u003e |\n| \u003ca href=\"https://github.com/basedosdados/sdk/labels/R\" target=\"_blank\"\u003e\u003cimg src=\"https://img.shields.io/github/issues/basedosdados/sdk/R\"\u003e\u003c/a\u003e | \u003ca href=\"https://github.com/basedosdados/sdk/labels/python\" target=\"_blank\"\u003e\u003cimg src=\"https://img.shields.io/github/issues/basedosdados/sdk/Python\"\u003e\u003c/a\u003e |\n\n## Encontre aqui\n\n- 📝 [Como citar o projeto](#como-citar-o-projeto)\n- 🐍 [Usando em Python](#usando-em-python)\n- \u003cimg src=\"https://raw.githubusercontent.com/github/explore/80688e429a7d4ef2fca1e82350fe8e3517d3494d/topics/r/r.png\" width=\"15\"\u003e [Usando em R](#usando-em-r)\n- Análises e tutoriais:\n  - \u003cimg\n    src=\"https://github.com/gauravghongde/social-icons/blob/master/PNG/Color/Github.png?raw=true\"\n    width=\"15\"\u003e [Códigos de análises publicadas nas redes, workshops e artigos ↗](http://github.com/basedosdados/analises)\n  - \u003cimg src=\"https://github.com/gauravghongde/social-icons/blob/master/PNG/Color/Youtube.png?raw=true\" width=\"15\"\u003e  [Youtube ↗](https://www.youtube.com/c/BasedosDados)\n  - \u003cimg\n    src=\"https://github.com/gauravghongde/social-icons/blob/master/PNG/Color/Medium.png?raw=true\"\n    width=\"15\"\u003e  [Medium ↗](http://dev.to/basedosdados)\n- [⚙️ Desenvolvimento](#desenvolvimento)\n- [👥 Como contribuir ↗](https://basedosdados.github.io/sdk/colab_data/)\n- [💚 Apoie o projeto! ↗](https://apoia.se/basedosdados)\n\n## Como citar o projeto\n\nO 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](LICENSE).\n\nCaso queira citar o projeto numa publicação, artigo ou na web, utilize o\nmodelo no menu ao lado conforme a imagem.\n\n**💡 Quer divulgar seu projeto nas nossas redes? Envie para contato@basedosdados.org**\n\n![image](https://user-images.githubusercontent.com/20743819/135773540-785e1e84-9d20-4f2d-9aea-512ffe65eb67.png)\n\n## Usando em Python\n\n### Instale\n\nCom pip:\n\n```bash\npip install basedosdados\n```\n\nCom poetry:\n\n```sh\npoetry add basedosdados\n```\n\n### Acesse uma tabela\n\n```python\nimport basedosdados as bd\n\ndf = bd.read_table('br_ibge_pib', 'municipio', billing_project_id=\"\u003cYOUR-PROJECT\u003e\")\n```\n\n\u003e Caso esteja acessando da primeira vez, vão aparecer alguns passos na tela para autenticar seu projeto - basta segui-los!\n\u003e\n\u003e É 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.github.io/sdk/access_data_bq/#primeiros-passos).\n\u003e\n\u003e Se possível, armazene suas credenciais em um arquivo `dotenv`: `\"billing_project_id=\u003csuas_credenciais_do_projeto\u003e\" \u003e\u003e .env`\n\n\n### Faça uma consulta\n\n```python\nimport basedosdados as bd\n\n# Bens dos candidatos de Tocantins em 2020\nquery = \"\"\"\nSELECT *\nFROM `basedosdados.br_tse_eleicoes.bens_candidato`\nWHERE ano = 2020\nAND sigla_uf = 'TO'\n\"\"\"\n\ndf = bd.read_sql(query, billing_project_id=\"\u003cYOUR-PROJECT\u003e\")\n```\n\n\u003e Caso esteja acessando da primeira vez, vão aparecer alguns passos na tela para autenticar seu projeto - basta segui-los!\n\n### Defina paramêtros utilizando as configurações do pacote\n\n```py\nimport basedosdados as bd\n\n# seta o billing_project_id global\nbd.config.billing_project_id =  '\u003cbilling-project-id\u003e'\n\nquery = \"\"\"\nSELECT\n    *\nFROM `basedosdados.br_bd_diretorios_brasil.municipio`\n\"\"\"\n\ndf = bd.read_sql(query=query)\n```\n\nPara saber mais, veja os [exemplos](https://github.com/basedosdados/analises/tree/main/artigos) ou a [documentação da API](https://basedosdados.github.io/sdk/api_reference_python/)\n\n## Criando múltiplas configurações\n\nCaso 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.\n\nPara isso, siga os seguintes passos:\n\n1. Renomeie a pasta com o comando abaixo (pode ser o nome que quiser)\n    ```bash\n    mv ~/.basedosdados ~/.basedosdados_default\n   ```\n2. Neste momento, o pacote não terá a configuração padrão. Assim, ao rodar o comando\n    ```bash\n      basedosdados config init\n    ```\n    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.\n3. 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.\n4. 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.\n5. Renomeie a pasta criada no passo 1 para o nome que desejar, como `~/.bd_minha_nova_conta`.\n6. 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`.\n7. A partir de agora, você poderá usar a nova conta (no Python), bastando utilizar o seguinte processo:\n    ```py\n    import basedosdados as bd\n    bd.config.project_config_path = f\"{home}/.bd_minha_nova_conta\"\n    ```\n    e, se quiser voltar para a configuração padrão, basta utilizar o comando\n    ```py\n    bd.config.project_config_path = f\"{home}/.basedosdados\"\n    ```\n    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.\n\n## Usando em R\n\n### Instalação\n\n```R\ninstall.packages(\"basedosdados\")\n\n# ou a versão de desenvolvimento\n\ndevtools::install_github(\"basedosdados/sdk\", subdir = \"r-package\")\n```\n\n### Consultas\n\n`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.\n\n```r\nlibrary(basedosdados)\n\nset_billing_id(\"id do seu projeto aqui\") # autenticação para acesso aos dados\n\npib_per_capita \u003c- \"\nSELECT\n    pib.id_municipio ,\n    pop.ano,\n    pib.PIB / pop.populacao as pib_per_capita\nFROM `basedosdados.br_ibge_pib.municipio` as pib\n  INNER JOIN `basedosdados.br_ibge_populacao.municipio` as pop\n  ON pib.id_municipio = pop.id_municipio AND pib.ano = pop.ano\"\n\n(data \u003c- read_sql(pib_per_capita)) # leia os dados em memória\ndownload(pib_per_capita, \"pib_per_capita.csv\") # salve os dados em disco\n```\n\nOu use o nosso backend para o `dplyr` e faça queries com código, sem SQL.\n\n```r\n  query \u003c- basedosdados::bdplyr(\"br_inep_ideb.municipio\") %\u003e%\n    dplyr::select(ano, id_municipio, sigla_uf, ideb) %\u003e%\n    dplyr::filter(sigla_uf == \"AC\", ano \u003c 2021) %\u003e%\n    dplyr::group_by(ano) %\u003e%\n    dplyr::summarise(ideb_medio = mean(ideb, na.rm = TRUE))\n\n  basedosdados::bd_collect(query) # retorne como um tibble\n  basedosdados::bd_write_csv(query, \"ideb_medio.csv\")\n  basedosdados::bd_write_rds(query, \"ideb_medio.rds\")\n```\n\n`bd_write` é uma extensão para formatos customizados.\n\n```r\n  basedosdados::bd_write(query, .write_fn = writexl::write_xlsx, \"ideb_medio.xlsx\")\n  basedosdados::bd_write(query, .write_fn = jsonlite::write_json, \"ideb_medio.json\")\n  basedosdados::bd_write(query, .write_fn = haven::write_dta, \"ideb_medio.dta\")\n```\n\nO 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.\n\nCaso encontre algum problema no pacote e queira ajudar, basta documentar o problema em um [exemplo mínimo reprodutível](https://pt.stackoverflow.com/questions/264168/quais-as-principais-fun%C3%A7%C3%B5es-para-se-criar-um-exemplo-m%C3%ADnimo-reproduz%C3%ADvel-em-r) e abrir uma issue.\n\n## Metadados e buscas\n\nVocê pode fazer buscas por tabelas usando palavras-chave ou buscar descrições de conjuntos e tabelas:\n\n```r\ndataset_search(\"educação\")\nget_dataset_description(\"br_sp_alesp\")\nget_table_description(\"br_sp_alesp\", \"deputado\")\n```\n\n## Atenção\n\n\u003e 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](https://www.tidyverse.org/google_privacy_policy/) - 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.\n\u003e É 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.github.io/sdk/access_data_bq/#primeiros-passos).\n\u003e Se possível, armazene suas credenciais em um arquivo `dotenv`, em bash o comando é `\"billing_project_id=\u003csuas_credenciais_do_projeto\u003e\" \u003e\u003e .env`. [Veja aqui como criar um arquivo dotenv](https://towardsdatascience.com/using-dotenv-to-hide-sensitive-information-in-r-8b878fa72020).\n\n## Contribua\n\nLeia nosso [guia de contribuição](./CONTRIBUTING.md)\n","funding_links":["https://apoia.se/basedosdados"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbasedosdados%2Fsdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbasedosdados%2Fsdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbasedosdados%2Fsdk/lists"}