alterando readme e adicionando contribute.md

CONTRIBUTING.md

@@ -0,0 +1,137 @@
+# 1. Garanta que você já tem em mãos:
+- o nome do conjunto e da tabela validada pela equipe dados da BD
+- tabela de arquitetura validada pela equipe dados em um google_sheets com a permissão de edição para qualquer um com o link
+- arquivo dos dados no formato .csv ou .parquet (pode ser em hive ou não) 
+- código `download_data.py`
+- código `clean_data.py` (se necessário)
+- chave de acesso ao google cloud dos voluntários
+
+# 2. Configurações para subir os dados e rodar o modelo DBT:
+
+* Clonar o diretório `queries-basedosdados-dev` 
+
+* Acessar o diretório `queries-basedosdados-dev`
+```
+cd <path/do/seu/clone/queries-basedosdados-dev>
+```
+
+* Atualizar o `pip` 
+É muito importante garantir que a versão do pip está atualizada antes dos próximos passos.
+```bash
+python -m pip install --upgrade pip
+```
+* Instalar o poetry
+```bash
+pip install poetry
+```
+
+* Criar o ambiente virtual e instalar as dependências 
+```bash
+poetry install --with=dev && pre-commit install
+```
+* Ative o ambiente virtual
+```bash
+poetry shell
+```
+* Instalar os pacotes do dbt no ambiente local
+```bash
+dbt deps
+```
+## Alterar as credenciais em `profiles.yml`:
+Para que o teste dos modelos seja feito localmente é necessário mudar o caminho das credenciais que ficam no arquivo `profiles.yml`.
+* Criar uma cópia do arquivo `profiles.yml` original fora do repo `queries-basedosdados-dev`,
+* No campo `keyfile` altera o caminho para a credencial local (se vc já usou o pacote `basedosdados` ela deve estar em `/home/<user>/.basedosdados/credentials/prod.json`)
+
+Pronto! agora você já tem seu ambiente configurado para desenvolver e rodar os modelos no seu ambiente local.
+
+# 3. Subir os dados brutos no BigQuery e gerar aquivos DBT
+
+A gente criou um arquivo .py pra você seguir os passos ele se encontra em `queries-basedosdados-dev/gist/upload_data_and_create_dbt_files.py` mas segue aqui a explicação de cada bloco em português:
+
+Definimos as variáveis para identificar o conjunto de dados, tabela, URL da arquitetura e caminho para os dados
+```python 
+    dataset_id = '<dataset_id>'
+    table_id = '<table_id>'
+    architecture_url = '<url_from_google_sheets>' #lembre de que o link deve ser compartilhavel para qualquer pessoa na internet editar
+    path_to_data = f"/path_to_datasets/{dataset_id}/{table_id}"  
+```
+
+Criamos um objeto do tipo Table da bd: 
+```python 
+    tb = bd.Table(
+        dataset_id=dataset_id,
+        table_id=table_id
+    )
+``` 
+
+No próximo passo carregamos os dados para o Storage da BD e criamos uma tabela BigQuery que por uma conexão externa acessa esses dados diretamente do Storage
+> Deixamos os parâmetros que mais usamos visíveis aqui, mas é importante explorar outras opções de parâmetros na documentação.
+   
+```python 
+    tb.create(
+        path=path_to_data,
+        if_storage_data_exists='raise',
+        if_table_exists='replace',
+        source_format='csv'
+    )
+``` 
+Essa função cria os arquivos padrão necessários para executar um modelo dbt 
+> Atenção: ainda será necessário realizar modificações nos arquivos
+```python 
+    create_yaml_file(
+        arq_url=architecture_url,
+        table_id=table_id,
+        dataset_id=dataset_id,
+        preprocessed_staging_column_names=False) 
+        # Mude esta última variável para True se 'original_name' foi modificado para 'name' no script de limpeza
+
+```
+
+# 4. Transformação dos arquivos e verificando o resultado
+Primeiro vamos criar uma branch para subir esses novos arquivos. O nome padrão que usamos na bd para as branchs é apenas `<dataset_id>`
+
+Agora será necessário fazer as seguintes modificações:
+### no arquivo `<dataset_id>__<table_id>.sql`
+* Incluir colunas que sejam modificações das colunas originais (como por exemplo puxar o id_municipio a partir do nome)
+* Modificar colunas que sejam do tipo string que contenham códigos númericos para excluir '.0' ao final da string
+* Caso a coluna seja do tipo `date` avaliar como usar as funções do SQL para que ela fique registrada no tipo correto
+* Outras transformações necessárias para que ao final do processo a tabela gerada com o código SQL seja igual a arquitetura
+> Obs. Para realizar testes pode rodar no próprio console do BigQuery, quando tudo estiver pronto você copia e cola a querie no arquivo `.sql` 
+
+### no arquivo `schema.yaml`
+* Incluir as colunas necessárias no teste de chave única   
+* Incluir mais testes para verificar se o dado está se comportando como deveria, temos alguns testes pré prontos com o pacote de [dbt-utils](https://github.com/dbt-labs/dbt-utils?tab=readme-ov-file#generic-tests)
+
+### no arquivo `dbt_project.yml`
+* Caso seja um conjunto novo, incluir o conjunto na lista do projeto **em ordem alfabética**
+
+## Como rodar o modelo?
+Mais informações: https://docs.getdbt.com/reference/node-selection/syntax
+### Materializando o modelo no BigQuery:
+```bash
+# materializa um único modelo pelo nome
+$ dbt run --select dataset_id__table_id --profiles-dir <path/to/profiles.yml>     
+
+# materializa todos os modelos em uma pasta      
+$ dbt run --select model.dateset_id.dateset_id__table_id --profiles-dir <path/to/profiles.yml>      
+
+# materializa todos os modelos no caminho 
+$ dbt run --select /models/dataset_id --profiles-dir <path/to/profiles.yml>
+
+# materializa um único modelo pelo caminho sql
+$ dbt run --select /models/dataset/table_id.sql --profiles-dir <path/to/profiles.yml> 
+```
+
+### Testando o modelo pelas configurações do `schema.yaml` 
+```bash
+# materializa um único modelo pelo nome
+$ dbt test --select dataset_id__table_id --profiles-dir <path/to/profiles.yml>     
+
+# materializa todos os modelos em uma pasta      
+$ dbt test --select model.dateset_id.dateset_id__table_id --profiles-dir <path/to/profiles.yml>      
+
+# materializa todos os modelos no caminho 
+$ dbt test --select /models/dataset_id --profiles-dir <path/to/profiles.yml>
+
+```
+* **Obs:** Como os testes ficam no arquivo `schema.yml` não é possível passar o caminho do `.sql` para realizar testes

README.md

@@ -1,66 +1,43 @@
-# Queries template
+<p align="center">
+    <a href="https://basedosdados.org">
+        <img src="https://github.com/basedosdados/sdk/blob/master/docs/docs/pt/images/bd_minilogo.png" width="340" alt="Base dos Dados">
+    </a>
+</p>
 
-Esse é um template para um pacote DBT a ser importado no cluster do projeto `basedosdados-dev`, que irá gerar um servidor RPC para execução dos projetos específicos de cada projeto GCP. Deve-se respeitar a seguinte nomenclatura: queries-`<nome_do_projeto_gcp>`.
+<p align="center">
+    <em>Universalizando o acesso a dados de qualidade.</em>
+</p>
 
-## Como usar esse template
+# Queries-basedosdados-dev
 
-- Na criação de um novo repositório, selecione o template `queries-template` e crie um repositório com o nome `queries-<nome_do_projeto_gcp>`.
-- Configure o seguinte secret no repositório:
-  - `VAULT_TOKEN`: token de acesso ao vault.
+Esse é um template para um pacote DBT de desenvolvimento
+para o repositorio [Queries-basedosdados][queries] 
 
-> Este projeto necessita das variáveis de ambiente descritas abaixo. Tais valores são providos na action do arquivo `cd.yaml`, os valores possuem como origem o Vault.
+## 👥 Como contribuir
 
-  - `GCP_SA_KEY_BASE64`: credenciais para uma conta de serviço com pleno acesso ao GKE, GCR e GCS. Preencher com o resultado de `cat sua-credencial.json | base64`.
-  - `GCP_PROJECT_ID`: identificador do projeto no GCP.
-  - `GKE_CLUSTER_NAME`: nome do cluster no GKE.
-  - `GKE_CLUSTER_ZONE`: zona do cluster no GKE.
+Leia nosso [guia de contribuição](./CONTRIBUTING.md)
 
-Aplique as seguintes alterações no projeto:
+## 🗺️ Contatos
 
-- Corrija o arquivo `cd.yaml`, onde todos os valores que estão como `<GCP_PROJECT_NAME>` devem ser substituídos pelo nome do projeto GCP;
-- Garanta que todos os valores recuperados do Vault existam e estejam corretos;
-- Modifique o nome do pacote em `dbt_project.yml` para o nome do seu projeto. Aproveite esse momento para ler, com calma, os comentários desse arquivo de configuração.
-- [Crie contas de serviço](https://cloud.google.com/iam/docs/creating-managing-service-account-keys) para seus projetos de desenvolvimento e produção. Caso tenha somente um projeto, pode usar a mesma conta para ambos os propósitos. **Nota:** **Jamais** faça commit de suas credenciais.
-- Acesse o arquivo `profiles.yml` e se atente aos comentários, eles indicam os campos que devem ser alterados.
-- Usando os arquivos de credencial, crie os secrets `credentials-dev` e `credentials-prod` [usando a flag `--from-file`](https://cloud.google.com/kubernetes-engine/docs/concepts/secret#creating_secrets_from_files).
-- Faça o upload das alterações realizadas em seu repositório.
-- Toda vez que houver uma alteração de código na branch `master`, uma instância atualizada do servidor RPC do DBT será criada em seu cluster, no devido namespace.
+Sinta-se livre para entrar em contato com projeto por nossas redes sociais.
+<br />
+Fortemente te incetivamos a participar da nossa comunidade pelo [discord][discord-invite], onde você pode ter um gostinho de toda a [Base Dos Dados][bd]. 🫶
 
-### Resources:
+[![][img-discord]][discord-invite]
+[![][img-linke]][linkedin]
+[![][img-x]][x]
+[![][img-youtube]][youtube]
 
-- Learn more about dbt [in the docs](https://docs.getdbt.com/docs/introduction)
-- Check out [Discourse](https://discourse.getdbt.com/) for commonly asked questions and answers
-- Join the [chat](https://community.getdbt.com/) on Slack for live discussions and support
-- Find [dbt events](https://events.getdbt.com) near you
-- Check out [the blog](https://blog.getdbt.com/) for the latest news on dbt's development and best practices
+<!-- Referencias -->
 
-## Como desenvolver novos modelos
+[img-discord]: https://img.shields.io/badge/Discord-Comunidade-blue?style=for-the-badge&logo=Discord
+[img-x]: https://img.shields.io/badge/Fique%20por%20dentro-blue?style=for-the-badge&logo=x
+[img-youtube]: https://img.shields.io/badge/Youtube-Assista-red?style=for-the-badge&logo=youtube
+[img-linke]: https://img.shields.io/badge/Linkedin-Acesse-blue?style=for-the-badge&logo=linkedin
 
-1. Caso seja um `dataset-id` já existente, acesse `models/<dataset-id>` e pule para o passo 5.
-
-2. Caso seja um novo `dataset-id`, crie um novo diretório `models/<dataset-id>`.
-
-3. No arquivo `dbt_project.yml` registre o `dataset-id` junto aos já existentes, conforme exemplo abaixo:
-
-```yaml
-models:
-  emd:
-    dataset-id:
-      +materialized: view # Materialization type (view, table or incremental)
-      +schema: dataset-id # Overrides the default schema (defaults to what is set on profiles.yml)
-```
-
-4. No diretório `models/<dataset-id>`, crie um arquivo `schema.yml` para preencher metadados de suas tabelas. Exemplo abaixo:
-
-```yaml
-version: 2
-
-models:
-  - name: my_first_dbt_model
-    description: "A starter dbt model"
-    columns:
-      - name: id
-        description: "The primary key for this table"
-```
-
-5. Desenvolva seus modelos (que corresponderão a tabelas) no diretório `models/<dataset-id>`.
+[discord-invite]: https://discord.com/invite/huKWpsVYx4
+[x]: https://twitter.com/basedosdados
+[youtube]: https://www.youtube.com/c/BasedosDados
+[bd]: https://basedosdados.org
+[linkedin]: https://www.linkedin.com/company/base-dos-dados
+[queries]: https://github.com/basedosdados/queries-basedosdados