[Fix] colab_docs

next/content/docs/pt/colab_data.md

@@ -29,12 +29,11 @@ order: 0
 Quer subir dados na BD e nos ajudar a construir esse repositório?
 *Maravilha!* Organizamos tudo o que você precisa no manual abaixo em 8 passos
 
-Para facilitar a explicação, vamos seguir um exemplo já pronto com dados da [RAIS](https://basedosdados.org/dataset/br-me-rais).
+Para facilitar a explicação, vamos seguir um exemplo já pronto com dados da [RAIS](/dataset/3e7c4d58-96ba-448e-b053-d385a829ef00?table=86b69f96-0bfe-45da-833b-6edc9a0af213).
 
-<Tip caption="Você pode navegar pelas etapas no menu à esquerda.">
-    Sugerimos fortemente que entre em nosso [canal no
-    Discord](https://discord.gg/huKWpsVYx4) para tirar dúvidas e
-    interagir com a equipe e outros(as) colaboradores(as)! 😉
+<Tip caption="Você pode navegar pelas etapas no menu à esquerda">
+
+ Sugerimos fortemente que entre em nosso [canal no Discord](https://discord.gg/huKWpsVYx4) para tirar dúvidas e interagir com a equipe e outros(as) colaboradores(as)! 😉
 </Tip>
 
 ### Antes de começar
@@ -48,8 +47,8 @@ Alguns conhecimentos são necessárias para realizar esse processo:
   nossa equipe.
 
 <Tip caption="Não tem alguma dessas habilidades, mas quer colaborar?">
-    Temos um time de dados que pode te ajudar, basta entrar no [nosso
-    Discord](https://discord.gg/huKWpsVYx4) e mandar uma mensagem em #quero-contribuir.
+
+Temos um time de dados que pode te ajudar, basta entrar no [nosso Discord](https://discord.gg/huKWpsVYx4) e mandar uma mensagem em #quero-contribuir.
 </Tip>
 
 ### Como funciona o processo?
@@ -67,7 +66,7 @@ Alguns conhecimentos são necessárias para realizar esse processo:
 ### 1. Escolher a base e entender mais dos dados
 
 
-Mantemos a lista de conjuntos para voluntários no nosso [Github](https://github.com/orgs/basedosdados/projects/17/views/10). Para começar a subir uma base do seu interesse, basta abrir uma [nova issue](https://github.com/basedosdados/queries-basedosdados/issues/new?assignees=&labels=&projects=&template=issue--novos-dados.md&title=%5Bdados%5D+%3Cdataset_id%3E) de dados. Caso sua base (conjunto) já esteja listada, basta marcar seu usuário do Github como `assignee`
+Mantemos a lista de conjuntos para voluntários no nosso [Github](https://github.com/orgs/basedosdados/projects/17/views/9). Para começar a subir uma base do seu interesse, basta abrir uma [nova issue](https://github.com/basedosdados/pipelines/issues/new?template=new-data.yml) de dados. Caso sua base (conjunto) já esteja listada, basta marcar seu usuário do Github como `assignee`
 
 Seu primeiro trabalho é preencher as informações na issue. Essas informações vão te ajudar a entender melhor os dados e serão muito úteis para o tratamento e o preenchimento de metadados.
 
@@ -114,7 +113,7 @@ As tabelas de arquitetura da RAIS [podem ser consultadas aqui](https://docs.goog
 
 #### Para o preenchimento de cada tabela do seu conjunto siga esse passo a passo:
 
-<Tip caption="A cada início e final de etapa consulte nosso [manual de estilo](style_data) para garantir que você está seguindo a padronização da BD"/>
+>A cada início e final de etapa consulte nosso [manual de estilo](style_data) para garantir que você está seguindo a padronização da BD
 
 1. Listar todas as variáveis dos dados na coluna `original_name`
     - Obs: Caso a base mude o nome das variáveis ao longo dos anos (como a RAIS), é necessário fazer a compatibilização entre anos para todas as variáveis preenchendo a coluna de `original_name_YYYY` para cada ano ou mês disponível
@@ -124,11 +123,13 @@ As tabelas de arquitetura da RAIS [podem ser consultadas aqui](https://docs.goog
 5. A partir da compatibilização entre anos e/ou consultas aos dados brutos, preencher a cobertura temporal em `temporal_coverage` de cada variável
     - Obs: Caso as variáveis tenham a mesma cobertura temporal da tabela preencher apenas com '(1)'
 6. Indicar com 'yes' ou 'no' se há dicionário para as variáveis em `covered_by_dictionary`
-7. Verificar se as variáveis representam alguma entidade presente nos [diretórios](https://basedosdados.org/dataset?q=diret%C3%B3rio&datasets_with=open_tables&organization=bd&page=1) para preencher o `directory_column`
+7. Verificar se as variáveis representam alguma entidade presente nos [diretórios](/dataset/33b49786-fb5f-496f-bb7c-9811c985af8e?table=0a2d8187-f936-437d-89db-b4eb3a7e1735) para preencher o `directory_column`
 8. Para as variáveis do tipo `int64` ou `float64` verificar se é necessário incluir uma [unidade de medida](https://github.com/basedosdados/website/blob/master/ckanext-basedosdados/ckanext/basedosdados/validator/available_options/measurement_unit.py)
 9. Reordernar as variáveis conforme o [manual](style_data)
 
-<Tip caption="Quando terminar de preencher as tabelas de arquitetura, entre em contato com a equipe da Base dos Dados para validar tudo. É necessário que esteja claro o formato final que os dados devem ficar _antes_ de começar a escrever o código. Assim a gente evita o retrabalho."/>
+>Quando terminar de preencher as tabelas de arquitetura, entre em contato com a equipe da Base dos Dados para validar tudo. 
+
+>É necessário que esteja claro o formato final que os dados devem ficar _antes_ de começar a escrever o código. Assim a gente evita o retrabalho.
 
 ### 4. Escrever codigo de captura e limpeza de dados
 
@@ -142,7 +143,8 @@ Após validadas as tabelas de arquitetura, podemos escrever os códigos de
 Cada tabela limpa para produção pode ser salva como um arquivo único ou, caso seja muito grande (e.g. acima de 200 mb), ser particionada no formato [Hive](https://cloud.google.com/bigquery/docs/hive-partitioned-loads-gcs) em vários sub-arquivos. Os formatos aceitos são `.csv` ou `.parquet`. Nossa recomendação é particionar tabelas por `ano`, `mes` e `sigla_uf`. O particionamento é feito através da estrutura de pastas, veja o exemplo a baixo para visualizar como.
 
 #### Exemplo: RAIS - Particionamento
-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` .
+
+A tabela `microdados_vinculos` da RAIS Vinculos, por exemplo, é uma tabela muito grande (+400GB) 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` .
 
 #### Padrões necessários no código
 
@@ -174,7 +176,7 @@ Fique à vontade para estruturar sub-pastas como quiser lá dentro. O que import
 
 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](../style_data/#dicionarios).
+> Detalhes importantes de como construir seu dicionário estão no nosso [manual de estilo](style_data).
 
 #### Exemplo: RAIS - Dicionário
 
@@ -187,10 +189,11 @@ Ele já possui a estrutura padrão que utilizamos para dicionários.
 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 Python) que facilita as configurações e etapas do processo.
 
-> Como existe um custo para o armazenamento no storage, para finalizar essa etapa vamos precisar te disponibilizar uma api_key especifica para voluntários para subir os dados em nosso ambiente de desenvolvimento. Assim, entre em nosso [canal no Discord](https://discord.gg/huKWpsVYx4) e nos chame em 'quero-contribuir'
+> Como existe um custo para o armazenamento no storage, para finalizar essa etapa vamos precisar te disponibilizar uma api_key especifica para voluntários para subir os dados em nosso ambiente de desenvolvimento. Assim, entre em nosso [canal no Discord](https://discord.gg/huKWpsVYx4), nos chame em 'quero-contribuir' e marque a `@equipe_dados`
 
 #### Configure suas credenciais localmente
   **7.1** No seu terminal instale nosso cliente: `pip install basedosdados`.
+
   **7.2** Rode `import basedosdados as bd` no python e siga o passo a passo para configurar localmente com as credenciais de seu projeto no Google Cloud. Preencha as informações conforme a seguir:
 ```
     * STEP 1: y
@@ -208,77 +211,132 @@ Os dados vão passar por 3 lugares no Google Cloud:
 
 **7.3** Crie a tabela no *bucket do GCS* e *BigQuey-DEV-staging*, usando a API do Python, da seguinte forma:
 
-    ```python
-    import basedosdados as bd
+```python
+import basedosdados as bd
 
-    tb = bd.Table(
-      dataset_id='<dataset_id>',
-      table_id='<table_id>')
+DATASET_ID = "dataset_id"  # Nome do dataset
+TABLE_ID = "table_id"  # Nome da tabela
 
-    tb.create(
-        path='<caminho_para_os_dados>',
-        if_table_exists='raise',
-        if_storage_data_exists='raise',
-    )
-    ```
+tb = bd.Table(dataset_id=DATASET_ID, table_id=TABLE_ID)
+``` 
 
-    Os seguintes parâmetros podem ser usados:
 
+```python
+tb.create(
+path=path_to_data,  # Caminho para o arquivo csv ou parquet
+if_storage_data_exists="raise",
+if_table_exists="replace",
+source_format="csv",
+)
+```
 
-    - `path` (obrigatório): o caminho completo do arquivo no seu computador, como: `/Users/<seu_usuario>/projetos/basedosdados/sdk/bases/[DATASET_ID]/output/microdados.csv`.
 
 
-<Tip caption="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)."/>
+> 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`: comando que cria os arquivos de configuração do dataset 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, 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` : comando utilizado caso a **tabela já exista no BQ**:
-        - _raise_: retorna mensagem de erro.
-        - _replace_: substitui a tabela.
-        - _pass_: não faz nada.
 
-    - `if_storage_data_exists`: comando utilizado caso os **dados já existam no Google Cloud Storage**:
-        - _raise_: retorna mensagem de erro
-        - _replace_: substitui os dados existentes.
-        - _pass_: não faz nada.
 
 > Se o projeto não existir no BigQuery, ele será automaticamente criado
 
-  Consulte também nossa [API](../api_reference_cli) para mais detalhes de cada método.
+  Consulte também nossa [API](https://basedosdados.org/docs/api_reference_python) para mais detalhes de cada método.
+
+**7.4** Crie os arquivos .sql e schema.yml a partir da tabela de arquitetura para rodar a materialização e os testes no dbt (data build-tool):
+
+  ```python
+from databasers_utils import TableArchitecture
+
+arch = TableArchitecture(
+    dataset_id="<dataset-id>",
+    tables={
+        "<table-id>": "URL da arquiterura do Google Sheet",  # Exemplo https://docs.google.com/spreadsheets/d/1K1svie4Gyqe6NnRjBgJbapU5sTsLqXWTQUmTRVIRwQc/edit?usp=drive_link
+    },
+)
+
+# Cria o yaml file
+arch.create_yaml_file()
+
+# Cria os arquivos sql
+arch.create_sql_files()
 
-**7.4** Crie os arquivos .sql e schema.yml a partir da tabela de arquitetura seguindo essa [documentação](https://github.com/basedosdados/pipelines/wiki/Fun%C3%A7%C3%A3o-%60create_yaml_file()%60)
-<Tip caption="Caso você precise, nesse momento você pode alterar a consulta em SQL para realizar tratamentos finais a partir da tabela `staging`, pode incluir coluna, remover coluna, fazer operações algébricas, substituir strings, etc. O SQL é o limite!"/>
+# Atualiza o dbt_project.yml
+arch.update_dbt_project()
 
-**7.5** Rode e teste os modelos localmente seguindo essa [documentação](https://github.com/basedosdados/pipelines/wiki/Testar-modelos-dbt-localmente)
+  ```
+> Caso você precise, nesse momento você pode alterar a consulta em SQL para realizar tratamentos finais a partir da tabela `staging`, pode incluir coluna, remover coluna, fazer operações algébricas, substituir strings, etc. O SQL é o limite!
+
+
+## 8. Usando o DBT
+#### Macro `set_datalake_project`
+
+Os arquivos sql do dbt usam a macro `set_datalake_project` que indica de qual projeto (basedosdados-staging ou basedosdados-dev) serão consumidos os dados. Ao criar os arquivos usando a função `create_sql_files` a macro será inserida.
+
+```sql
+select
+    col_name
+from {{ set_datalake_project("<DATASET_ID>_staging.<TABLE_ID>") }}
+```
+
+
+### Materializando o modelo no BigQuery
+
+Materializa um único modelo pelo nome em basedosdados-dev consumindo os dados de `basedosdados-dev.{table_id}_staging`
+
+```sh
+dbt run --select dataset_id__table_id
+```
+
+Materializa todos os modelos em uma pasta em basedosdados-dev consumindo os dados de `basedosdados-dev.{table_id}_staging`
+
+```sh
+dbt run --select model.dateset_id.dateset_id__table_id
+```
+
+Materializa todos os modelos no caminho em basedosdados-dev consumindo os dados de `basedosdados-dev.{table_id}_staging`
+
+```sh
+dbt run --select models/dataset_id
+```
+
+Materializa um único modelo pelo caminho do arquivo sql em basedosdados-dev consumindo os dados de `basedosdados-dev.{table_id}_staging`
+
+```sh
+dbt run --select models/dataset/table_id.sql
+```
+
+### Testando o modelo no BigQuery
+
+Testa um único modelo
+
+```sh
+dbt test --select dataset_id__table_id
+```
+
+Testa todos os modelos em uma pasta
+
+```sh
+dbt test --select model.dateset_id.dateset_id__table_id
+```
+
+Testa todos os modelos no caminho
+
+```sh
+dbt test --select models/dataset_id
+```
 
 **7.6** Suba os metadados da tabela no site:
 > Por enquanto apenas a equipe dados tem permissões de subir os metadados da tabela no site, por isso será necessário entrar em contato conosco. Já estamos trabalhando para que, num futuro próximo, os voluntários também possam atualizar dados no site.
 
-**7.7** Suba os arquivos auxiliares:
-    ```python
-    st = bd.Storage(
-      dataset_id = <dataset_id>,
-      table_id = <table_id>)
-
-    st.upload(
-      path='caminho_para_os_arquivos_auxiliares',
-      mode = 'auxiliary_files',
-      if_exists = 'raise')
-    ```
 
 ### 8. Enviar tudo para revisão
 
 Ufa, é isso! Agora só resta enviar tudo para revisão no
-[repositório](https://github.com/basedosdados/queries-basedosdados) da Base dos Dados.
+[repositório](https://github.com/basedosdados/pipelines) da Base dos Dados.
 
-1. Clone o nosso [repositório](https://github.com/basedosdados/queries-basedosdados) localmente.
+1. Clone o nosso [repositório](https://github.com/basedosdados/pipelines) localmente.
 2. Dê um `cd` para a pasta local do repositório e abra uma nova branch com `git checkout -b [dataset_id]`. Todas as adições e modificações serão incluídas nessa _branch_.
-3. Para cada tabela nova incluir o arquivo com nome `table_id.sql` na pasta `queries-basedosdados/models/dataset_id/` copiando as queries que você desenvolveu no passo 7.
-4. Incluir o arquivo schema.yaml desenvolvido no passo 7
-5. Caso seja um dataset novo, incluir o dataset conforme as instruções do arquivo `queries-basedosdados/dbt_project.yaml` (não se esqueça de seguir a ordem alfabética pra não bagunçar a organização)
-6. Inclua o seu código de captura e limpeza em na pasta `queries-basedosdados/models/dataset_id/code`
-7. Agora é só publicar a branch, abrir o PR com as labels 'table-approve' e marcar a equipe dados para correção
+3. Para cada tabela nova incluir o arquivo com nome `dataset__table_id.sql` na pasta `pipelines/models/dataset_id/` copiando as queries e o schema que você criou no passo 7.
+4. Inclua o seu código de captura e limpeza em na pasta `pipelines/models/dataset_id/code`
+5. Agora é só publicar a branch, abrir o PR com as labels 'table-approve' e marcar a equipe dados para correção
 
 **E agora?** Nossa equipe irá revisar os dados e metadados submetidos
 via Github. Podemos entrar em contato para tirar dúvidas ou solicitar