Add/folders (#1)

.github/workflows/dbt_docs_update.yml

@@ -0,0 +1,68 @@
+name: docs_update
+
+on:
+  push:
+    branches:
+      - "main"
+
+env:
+  DBT_PROFILES_DIR: ${{ secrets.DBT_PROFILES_DIR }}
+
+  ACCOUNT: "${{ secrets.ACCOUNT }}"
+  ROLE: "${{ secrets.ROLE }}"
+  USER: "${{ secrets.USER }}"
+  PASSWORD: "${{ secrets.PASSWORD }}"
+  REGION: "${{ secrets.REGION }}"
+  DATABASE: "${{ secrets.DATABASE }}"
+  WAREHOUSE: "${{ secrets.WAREHOUSE }}"
+  SCHEMA: "${{ secrets.SCHEMA }}"
+
+concurrency:
+  group: ${{ github.workflow }}
+
+jobs:
+  scheduled_run:
+    name: docs_update
+    runs-on: ubuntu-latest
+    environment: 
+      name: workflow_prod
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - uses: actions/setup-python@v1
+        with:
+          python-version: "3.7.x"
+
+      - name: install dependencies
+        run: |
+          pip install dbt-snowflake==${{ secrets.DBT_VERSION }}
+          dbt deps
+      - name: checkout docs branch
+        run: |
+          git checkout -b docs origin/main
+          
+      - name: generate dbt docs
+        run: dbt docs generate -t prod
+
+      - name: move files to docs directory
+        run: |
+          mkdir -p ./docs
+          cp target/{catalog.json,manifest.json,index.html} docs/
+      - name: clean up target directory
+        run: dbt clean
+
+      - name: check for changes
+        run: git status
+
+      - name: stage changed files
+        run: git add .
+
+      - name: commit changed files
+        run: |
+          git config user.email "abc@xyz"
+          git config user.name "github-actions"
+          git commit -am "Auto-update docs"
+      - name: push changes to docs
+        run: |
+          git push -f --set-upstream origin docs

.github/workflows/dbt_run_adhoc.yml

@@ -0,0 +1,52 @@
+name: dbt_run_adhoc
+run-name: dbt_run_adhoc
+
+on:
+  workflow_dispatch:
+    branches:
+      - "main"
+    inputs:
+      environment:
+        type: choice 
+        description: DBT Run Environment
+        required: true
+        options:
+          - dev
+          - prod
+        default: dev
+      warehouse:
+        type: choice 
+        description: Snowflake warehouse
+        required: true 
+        options:
+          - DBT
+          - DBT_CLOUD
+          - DBT_EMERGENCY
+        default: DBT
+      dbt_command:
+        type: string
+        description: 'DBT Run Command'
+        required: true
+    
+env:
+  DBT_PROFILES_DIR: ${{ secrets.DBT_PROFILES_DIR }}
+
+  ACCOUNT: "${{ secrets.ACCOUNT }}"
+  ROLE: "${{ secrets.ROLE }}"
+  USER: "${{ secrets.USER }}"
+  PASSWORD: "${{ secrets.PASSWORD }}"
+  REGION: "${{ secrets.REGION }}"
+  DATABASE: "${{ secrets.DATABASE }}"
+  WAREHOUSE: "${{ inputs.warehouse }}"
+  SCHEMA: "${{ secrets.SCHEMA }}"
+
+concurrency:
+  group: ${{ github.workflow }}
+
+jobs:
+  called_workflow_template:
+      uses: FlipsideCrypto/analytics-workflow-templates/.github/workflows/dbt_run_template.yml@main
+      with:
+        dbt_command: ${{ inputs.dbt_command }}
+        environment: workflow_${{ inputs.environment }}
+        warehouse: ${{ inputs.warehouse }}

.gitignore

@@ -0,0 +1,17 @@
+
+target/
+dbt_modules/
+# newer versions of dbt use this directory instead of dbt_modules for test dependencies
+dbt_packages/
+logs/
+
+.venv/
+.python-version
+
+# Visual Studio Code files
+*/.vscode
+*.code-workspace
+.history/
+**/.DS_Store
+.vscode/
+dbt-env/

README.md

@@ -1 +1,97 @@
-# external-models
+## Profile Set Up
+
+#### Use the following within profiles.yml 
+----
+
+```yml
+external:
+  target: dev
+  outputs:
+    dev:
+      type: snowflake
+      account: <ACCOUNT>
+      role: <ROLE>
+      user: <USERNAME>
+      password: <PASSWORD>
+      region: <REGION>
+      database: EXTERNAL_DEV
+      warehouse: <WAREHOUSE>
+      schema: silver
+      threads: 12
+      client_session_keep_alive: False
+      query_tag: <TAG>
+    prod:
+      type: snowflake
+      account: <ACCOUNT>
+      role: <ROLE>
+      user: <USERNAME>
+      password: <PASSWORD>
+      region: <REGION>
+      database: EXTERNAL
+      warehouse: <WAREHOUSE>
+      schema: silver
+      threads: 12
+      client_session_keep_alive: False
+      query_tag: <TAG>
+```
+
+### Variables
+
+To control the creation of UDF or SP macros with dbt run:
+* UPDATE_UDFS_AND_SPS
+When True, executes all macros included in the on-run-start hooks within dbt_project.yml on model run as normal
+When False, none of the on-run-start macros are executed on model run
+
+Default values are False
+
+* Usage:
+dbt run --var '{"UPDATE_UDFS_AND_SPS":True}'  -m ...
+
+### Resources:
+- 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
+
+## Applying Model Tags
+
+### Database / Schema level tags
+
+Database and schema tags are applied via the `add_database_or_schema_tags` macro.  These tags are inherited by their downstream objects.  To add/modify tags call the appropriate tag set function within the macro.
+
+```
+{{ set_database_tag_value('SOME_DATABASE_TAG_KEY','SOME_DATABASE_TAG_VALUE') }}
+{{ set_schema_tag_value('SOME_SCHEMA_TAG_KEY','SOME_SCHEMA_TAG_VALUE') }}
+```
+
+### Model tags
+
+To add/update a model's snowflake tags, add/modify the `meta` model property under `config`.  Only table level tags are supported at this time via DBT.
+
+```
+{{ config(
+    ...,
+    meta={
+        'database_tags':{
+            'table': {
+                'PURPOSE': 'SOME_PURPOSE'
+            }
+        }
+    },
+    ...
+) }}
+```
+
+By default, model tags are pushed to Snowflake on each load. You can disable this by setting the `UPDATE_SNOWFLAKE_TAGS` project variable to `False` during a run.
+
+```
+dbt run --var '{"UPDATE_SNOWFLAKE_TAGS":False}' -s models/core/core__fact_blocks.sql
+```
+
+### Querying for existing tags on a model in snowflake
+
+```
+select *
+from table(external.information_schema.tag_references('external.core.fact_blocks', 'table'));
+```

dbt_project.yml

@@ -0,0 +1,47 @@
+# Name your project! Project names should contain only lowercase characters
+# and underscores. A good package name should reflect your organization's
+# name or the intended use of these models
+name: "external_models"
+version: "1.0.0"
+config-version: 2
+
+# This setting configures which "profile" dbt uses for this project.
+profile: "external"
+
+# These configurations specify where dbt should look for different types of files.
+# The `source-paths` config, for example, states that models in this project can be
+# found in the "models/" directory. You probably won't need to change these!
+model-paths: ["models"]
+analysis-paths: ["analysis"]
+test-paths: ["tests"]
+seed-paths: ["data"]
+macro-paths: ["macros"]
+snapshot-paths: ["snapshots"]
+
+target-path: "target" # directory which will store compiled SQL files
+clean-targets: # directories to be removed by `dbt clean`
+  - "target"
+  - "dbt_modules"
+  - "dbt_packages"
+
+tests:
+  +store_failures: true # all tests
+
+on-run-start:
+  - "{{ create_sps() }}"
+  - "{{ create_udfs() }}"
+
+on-run-end:
+  - '{{ apply_meta_as_tags(results) }}'
+
+# Configuring models
+# Full documentation: https://docs.getdbt.com/docs/configuring-models
+
+# In this example config, we tell dbt to build all models in the example/ directory
+# as tables. These settings can be overridden in the individual model files
+# using the `{{ config(...) }}` macro.
+
+vars:
+  "dbt_date:time_zone": GMT
+  UPDATE_UDFS_AND_SPS: False
+  UPDATE_SNOWFLAKE_TAGS: True

macros/create_sps.sql

@@ -0,0 +1,8 @@
+{% macro create_sps() %}
+    {% if var("UPDATE_UDFS_AND_SPS") %}
+        {% if target.database == 'EXTERNAL' %}
+            CREATE schema IF NOT EXISTS _internal;
+    {{ sp_create_prod_clone('_internal') }};
+        {% endif %}
+    {% endif %}
+{% endmacro %}

macros/create_udfs.sql

@@ -0,0 +1,12 @@
+{% macro create_udfs() %}
+    {% if var("UPDATE_UDFS_AND_SPS") %}
+        {% set sql %}
+        CREATE schema if NOT EXISTS silver;
+    {{ create_udf_hex_to_int(
+            schema = "public"
+        ) }}
+
+        {% endset %}
+        {% do run_query(sql) %}
+    {% endif %}
+{% endmacro %}

macros/custom_naming_macros.sql

@@ -0,0 +1,11 @@
+{% macro generate_schema_name(custom_schema_name=none, node=none) -%}
+    {% set node_name = node.name %}
+    {% set split_name = node_name.split('__') %}
+    {{ split_name[0] | trim }}
+{%- endmacro %}
+
+{% macro generate_alias_name(custom_alias_name=none, node=none) -%}
+    {% set node_name = node.name %}
+    {% set split_name = node_name.split('__') %}
+    {{ split_name[1] | trim }}
+{%- endmacro %}

macros/custom_query_tag.sql

@@ -0,0 +1,11 @@
+{% macro set_query_tag() -%}
+ {% set new_json = {"repo":project_name, "object":this.table, "profile":target.profile_name, "env":target.name, "existing_tag":get_current_query_tag()  } %}
+{% set new_query_tag = tojson(new_json) | as_text %}
+  {% if new_query_tag %}
+    {% set original_query_tag = get_current_query_tag() %}
+    {{ log("Setting query_tag to '" ~ new_query_tag ~ "'. Will reset to '" ~ original_query_tag ~ "' after materialization.") }}
+    {% do run_query("alter session set query_tag = '{}'".format(new_query_tag)) %}
+    {{ return(original_query_tag)}}
+  {% endif %}
+  {{ return(none)}}
+{% endmacro %}

macros/python/udfs.sql

@@ -0,0 +1,21 @@
+{% macro create_udf_hex_to_int(schema) %}
+create or replace function {{ schema }}.udf_hex_to_int(hex string)
+returns string
+language python
+runtime_version = '3.8'
+handler = 'hex_to_int'
+as
+$$
+def hex_to_int(hex) -> str:
+  """
+  Converts hex (of any size) to int (as a string). Snowflake and java script can only handle up to 64-bit (38 digits of precision)
+  select hex_to_int('200000000000000000000000000000211');
+  >> 680564733841876926926749214863536423441
+  select hex_to_int('0x200000000000000000000000000000211');
+  >> 680564733841876926926749214863536423441
+  select hex_to_int(NULL);
+  >> NULL
+  """
+  return str(int(hex, 16)) if hex else None
+$$;
+{% endmacro %}

macros/run_sp_create_prod_clone.sql

@@ -0,0 +1,10 @@
+{% macro run_sp_create_prod_clone() %}
+    {% set clone_query %}
+    call external._internal.create_prod_clone(
+        'external',
+        'external_dev',
+        'internal_dev'
+    );
+{% endset %}
+    {% do run_query(clone_query) %}
+{% endmacro %}

macros/sp_create_prod_clone.sql

@@ -0,0 +1,37 @@
+{% macro sp_create_prod_clone(target_schema) -%}
+
+create or replace procedure {{ target_schema }}.create_prod_clone(source_db_name string, destination_db_name string, role_name string)
+returns boolean 
+language javascript
+execute as caller
+as
+$$
+    snowflake.execute({sqlText: `BEGIN TRANSACTION;`});
+    try {
+        snowflake.execute({sqlText: `CREATE OR REPLACE DATABASE ${DESTINATION_DB_NAME} CLONE ${SOURCE_DB_NAME}`});
+        snowflake.execute({sqlText: `DROP SCHEMA IF EXISTS ${DESTINATION_DB_NAME}._INTERNAL`}); /* this only needs to be in prod */
+
+        snowflake.execute({sqlText: `GRANT OWNERSHIP ON ALL SCHEMAS IN DATABASE ${DESTINATION_DB_NAME} TO ROLE ${ROLE_NAME} COPY CURRENT GRANTS;`}); 
+        snowflake.execute({sqlText: `GRANT OWNERSHIP ON ALL FUNCTIONS IN DATABASE ${DESTINATION_DB_NAME} TO ROLE ${ROLE_NAME} COPY CURRENT GRANTS;`}); 
+        snowflake.execute({sqlText: `GRANT OWNERSHIP ON ALL PROCEDURES IN DATABASE ${DESTINATION_DB_NAME} TO ROLE ${ROLE_NAME} COPY CURRENT GRANTS;`}); 
+        snowflake.execute({sqlText: `GRANT OWNERSHIP ON ALL VIEWS IN DATABASE ${DESTINATION_DB_NAME} TO ROLE ${ROLE_NAME} COPY CURRENT GRANTS;`}); 
+        snowflake.execute({sqlText: `GRANT OWNERSHIP ON ALL STAGES IN DATABASE ${DESTINATION_DB_NAME} TO ROLE ${ROLE_NAME} COPY CURRENT GRANTS;`}); 
+        snowflake.execute({sqlText: `GRANT OWNERSHIP ON ALL TABLES IN DATABASE ${DESTINATION_DB_NAME} TO ROLE ${ROLE_NAME} COPY CURRENT GRANTS;`}); 
+        snowflake.execute({sqlText: `GRANT OWNERSHIP ON FUTURE FUNCTIONS IN DATABASE ${DESTINATION_DB_NAME} TO ROLE ${ROLE_NAME};`}); 
+        snowflake.execute({sqlText: `GRANT OWNERSHIP ON FUTURE PROCEDURES IN DATABASE ${DESTINATION_DB_NAME} TO ROLE ${ROLE_NAME};`}); 
+        snowflake.execute({sqlText: `GRANT OWNERSHIP ON FUTURE VIEWS IN DATABASE ${DESTINATION_DB_NAME} TO ROLE ${ROLE_NAME};`}); 
+        snowflake.execute({sqlText: `GRANT OWNERSHIP ON FUTURE STAGES IN DATABASE ${DESTINATION_DB_NAME} TO ROLE ${ROLE_NAME};`}); 
+        snowflake.execute({sqlText: `GRANT OWNERSHIP ON FUTURE TABLES IN DATABASE ${DESTINATION_DB_NAME} TO ROLE ${ROLE_NAME};`}); 
+
+        snowflake.execute({sqlText: `GRANT OWNERSHIP ON DATABASE ${DESTINATION_DB_NAME} TO ROLE ${ROLE_NAME} COPY CURRENT GRANTS;`})
+
+        snowflake.execute({sqlText: `COMMIT;`});
+    } catch (err) {
+        snowflake.execute({sqlText: `ROLLBACK;`});
+        throw(err);
+    }
+
+    return true
+$$
+
+{%- endmacro %}

macros/tags/add_database_or_schema_tags.sql

@@ -0,0 +1,3 @@
+{% macro add_database_or_schema_tags() %}
+    {{ set_database_tag_value('BLOCKCHAIN_NAME','EXTERNAL') }}
+{% endmacro %}

macros/tags/snowflake_tagging.sql

@@ -0,0 +1,127 @@
+{% macro apply_meta_as_tags(results) %}
+    {% if var("UPDATE_SNOWFLAKE_TAGS") %}
+        {{ log('apply_meta_as_tags', info=False) }}
+        {{ log(results, info=False) }}
+        {% if execute %}
+
+            {%- set tags_by_schema = {} -%}
+            {% for res in results -%}
+                {% if res.node.meta.database_tags %}
+
+                    {%- set model_database = res.node.database -%}
+                    {%- set model_schema = res.node.schema -%}
+                    {%- set model_schema_full = model_database+'.'+model_schema -%}
+                    {%- set model_alias = res.node.alias -%}
+
+                    {% if model_schema_full not in tags_by_schema.keys() %}
+                        {{ log('need to fetch tags for schema '+model_schema_full, info=False) }}
+                        {%- call statement('main', fetch_result=True) -%}
+                            show tags in {{model_database}}.{{model_schema}}
+                        {%- endcall -%}
+                        {%- set _ = tags_by_schema.update({model_schema_full: load_result('main')['table'].columns.get('name').values()|list}) -%}
+                        {{ log('Added tags to cache', info=False) }}
+                    {% else %}
+                        {{ log('already have tag info for schema', info=False) }}
+                    {% endif %}
+
+                    {%- set current_tags_in_schema = tags_by_schema[model_schema_full] -%}
+                    {{ log('current_tags_in_schema:', info=False) }}
+                    {{ log(current_tags_in_schema, info=False) }}
+                    {{ log("========== Processing tags for "+model_schema_full+"."+model_alias+" ==========", info=False) }}
+
+                    {% set line -%}
+                        node: {{ res.node.unique_id }}; status: {{ res.status }} (message: {{ res.message }})
+                        node full: {{ res.node}}
+                        meta: {{ res.node.meta}}
+                        materialized: {{ res.node.config.materialized }}
+                    {%- endset %}
+                    {{ log(line, info=False) }}
+
+                    {%- call statement('main', fetch_result=True) -%}
+                        select LEVEL,UPPER(TAG_NAME) as TAG_NAME,TAG_VALUE from table(information_schema.tag_references_all_columns('{{model_schema}}.{{model_alias}}', 'table'))
+                    {%- endcall -%}
+                    {%- set existing_tags_for_table = load_result('main')['data'] -%}
+                    {{ log('Existing tags for table:', info=False) }}
+                    {{ log(existing_tags_for_table, info=False) }}
+
+                    {{ log('--', info=False) }}
+                    {% for table_tag in res.node.meta.database_tags.table %}
+
+                        {{ create_tag_if_missing(current_tags_in_schema,table_tag|upper) }}
+                        {% set desired_tag_value = res.node.meta.database_tags.table[table_tag] %}
+
+                        {{set_table_tag_value_if_different(model_schema,model_alias,table_tag,desired_tag_value,existing_tags_for_table)}}
+                    {% endfor %}
+                    {{ log("========== Finished processing tags for "+model_alias+" ==========", info=False) }}
+                {% endif %}
+            {% endfor %}
+        {% endif %}
+    {% endif %}
+{% endmacro %}
+
+
+{% macro create_tag_if_missing(all_tag_names,table_tag) %}
+	{% if table_tag not in all_tag_names %}
+		{{ log('Creating missing tag '+table_tag, info=False) }}
+        {%- call statement('main', fetch_result=True) -%}
+            create tag if not exists silver.{{table_tag}}
+        {%- endcall -%}
+		{{ log(load_result('main').data, info=False) }}
+	{% else %}
+		{{ log('Tag already exists: '+table_tag, info=False) }}
+	{% endif %}
+{% endmacro %}
+
+{% macro set_table_tag_value_if_different(model_schema,table_name,tag_name,desired_tag_value,existing_tags) %}
+    {{ log('Ensuring tag '+tag_name+' has value '+desired_tag_value+' at table level', info=False) }}
+    {%- set existing_tag_for_table = existing_tags|selectattr('0','equalto','TABLE')|selectattr('1','equalto',tag_name|upper)|list -%}
+    {{ log('Filtered tags for table:', info=False) }}
+    {{ log(existing_tag_for_table[0], info=False) }}
+    {% if existing_tag_for_table|length > 0 and existing_tag_for_table[0][2]==desired_tag_value %}
+        {{ log('Correct tag value already exists', info=False) }}
+    {% else %}
+        {{ log('Setting tag value for '+tag_name+' to value '+desired_tag_value, info=False) }}
+        {%- call statement('main', fetch_result=True) -%}
+            alter table {{model_schema}}.{{table_name}} set tag {{tag_name}} = '{{desired_tag_value}}'
+        {%- endcall -%}
+        {{ log(load_result('main').data, info=False) }}
+    {% endif %}
+{% endmacro %}
+
+{% macro set_column_tag_value_if_different(table_name,column_name,tag_name,desired_tag_value,existing_tags) %}
+    {{ log('Ensuring tag '+tag_name+' has value '+desired_tag_value+' at column level', info=False) }}
+    {%- set existing_tag_for_column = existing_tags|selectattr('0','equalto','COLUMN')|selectattr('1','equalto',tag_name|upper)|list -%}
+    {{ log('Filtered tags for column:', info=False) }}
+    {{ log(existing_tag_for_column[0], info=False) }}
+    {% if existing_tag_for_column|length > 0 and existing_tag_for_column[0][2]==desired_tag_value %}
+        {{ log('Correct tag value already exists', info=False) }}
+    {% else %}
+        {{ log('Setting tag value for '+tag_name+' to value '+desired_tag_value, info=False) }}
+        {%- call statement('main', fetch_result=True) -%}
+            alter table {{table_name}} modify column {{column_name}} set tag {{tag_name}} = '{{desired_tag_value}}'
+        {%- endcall -%}
+        {{ log(load_result('main').data, info=False) }}
+    {% endif %}
+{% endmacro %}
+
+{% macro set_database_tag_value(tag_name,tag_value) %}
+    {% set query %}
+        create tag if not exists silver.{{tag_name}}
+    {% endset %}
+    {% do run_query(query) %}
+    {% set query %}
+        alter database {{target.database}} set tag {{target.database}}.silver.{{tag_name}} = '{{tag_value}}'
+    {% endset %}
+    {% do run_query(query) %}
+{% endmacro %}
+
+{% macro set_schema_tag_value(target_schema,tag_name,tag_value) %}
+    {% set query %}
+        create tag if not exists silver.{{tag_name}}
+    {% endset %}
+    {% do run_query(query) %}
+    {% set query %}
+        alter schema {{target.database}}.{{target_schema}} set tag {{target.database}}.silver.{{tag_name}} = '{{tag_value}}'
+    {% endset %}
+    {% do run_query(query) %}
+{% endmacro %}

models/sources.yml

@@ -0,0 +1,21 @@
+version: 2
+
+sources:
+  - name: tokenflow_starknet_l1_data
+    database: tokenflow_starknet
+    schema: l1_data
+    tables:
+      - name: blocks
+      - name: contracts
+      - name: messages
+      - name: storage_diffs
+  - name: tokenflow_starknet_decoded
+    database: tokenflow_starknet
+    schema: decoded
+    tables:
+      - name: blocks
+      - name: events
+      - name: messages
+      - name: traces
+      - name: transactions
+  

packages.yml

@@ -0,0 +1,7 @@
+packages:
+  - package: calogica/dbt_expectations
+    version: 0.8.0
+  - package: dbt-labs/dbt_external_tables
+    version: 0.8.0
+  - package: dbt-labs/dbt_utils
+    version: 0.9.2

profiles.yml

@@ -0,0 +1,29 @@
+external:
+  target: prod
+  outputs:
+    dev:
+      type: snowflake
+      account: "{{ env_var('ACCOUNT') }}"
+      role: "{{ env_var('ROLE') }}"
+      user: "{{ env_var('USER') }}"
+      password: "{{ env_var('PASSWORD') }}"
+      region: "{{ env_var('REGION') }}"
+      database: "{{ env_var('DATABASE') }}"
+      warehouse: "{{ env_var('WAREHOUSE') }}"
+      schema: SILVER
+      threads: 4
+      client_session_keep_alive: False
+      query_tag: external_curator
+    prod:
+      type: snowflake
+      account: "{{ env_var('ACCOUNT') }}"
+      role: "{{ env_var('ROLE') }}"
+      user: "{{ env_var('USER') }}"
+      password: "{{ env_var('PASSWORD') }}"
+      region: "{{ env_var('REGION') }}"
+      database: "{{ env_var('DATABASE') }}"
+      warehouse: "{{ env_var('WAREHOUSE') }}"
+      schema: SILVER
+      threads: 4
+      client_session_keep_alive: False
+      query_tag: external_curator