add README.md

README.md

@@ -1,15 +1,58 @@
-Welcome to your new dbt project!
+# What does this dbt package do?
 
-### Using the starter project
+Creates the dbt model described bellow using Facebook Ads data from [Windsor's connector](https://windsor.ai/connectors/facebook-ads/).
 
-Try running the following commands:
-- dbt run
-- dbt test
+<img src="etc/dbt_pipeline.svg">
 
+## Models
 
-### 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
+| **Model**                | **Description**                            |
+| ------------------------ | -------------------------------------------|
+| ad_report                | performance at the ad level               |
+
+<img src="etc/dbt_models.svg">
+
+
+# How do I use the dbt package?
+
+## Step 1: Create Facebook Ads source tables
+
+To use this dbt package, you must [sync Facebook Ads data to BigQuery](https://www.youtube.com/watch?v=orkvTJH5VcI).
+ - Add five destination tasks following the example below.
+
+<img src="etc/destination_task.png">
+
+ - To import the following five tables. 
+
+<img src="etc/dbt_source.svg">
+
+ - Using the following fields URL parameters in the Connector URL field.
+
+| **Table**                | **Fields parameter**                            |
+| ------------------------ | ------------------------------------------------|
+| account                  | account_id,account_name                         |
+| campaign                 | account_id,account_name,campaign_id,campaign    |
+| ad_set                   | campaign_id,adset_id,adset_name,adset_start_time,adset_end_time,adset_bid_strategy,adset_daily_budget    |
+| ad                       | adset_id,ad_id,ad_name                          |
+| report                   | ad_id,date,clicks,impressions,spend             |
+
+Details about Facebook Ad campaign structure is available [here](https://developers.facebook.com/docs/marketing-api/campaign-structure).
+
+
+## Step 2: Install the package
+
+1. Include the following dbt_facebook_ads package version in your packages.yml file.
+```yaml
+packages:
+  - git: "/~https://github.com/Oleg-Solovyev/dbt_facebook_ads.git"
+```
+2. Run `dbt deps`.
+
+## Step 3: Define the schema and tables variables
+Add the following configuration to your root `dbt_project.yml`
+```yml
+vars:
+  dbt_facebook_ads:
+    report: '<facebook ads schema>.<report table>'
+    ad: '<facebook ads schema>.<ad table>'
+```

etc/dbt_models.gv

@@ -0,0 +1,22 @@
+# cd ~/Documents/Visuals/Windsor.ai/erp
+# sfdp -Tpng -O vHub.dot
+# dot dbt_models.gv -Tsvg -o dbt_models.svg
+# convert -density 300 vHub.svg vHub.png
+digraph dbt {
+
+    #graph [pad="0.5", nodesep="0.5", ranksep="2"]
+    labelloc=t;
+    label="ad_report model"
+    node [shape=plain]
+    rankdir=LR
+
+    ad_report[label=<<table border="1" cellborder="0" cellspacing="0">
+        <tr><td colspan="2" bgcolor="lightgreen" align="left">ad_report</td></tr>
+        <tr><td port="ad_id" fixedsize="true" width="17" height="17"><img src="fk.jpeg"/></td><td port="ad_id2" align="left">ad_id</td></tr>
+        <tr><td></td><td align="left">ad_name</td></tr>
+        <tr><td></td><td align="left">date</td></tr>
+        <tr><td></td><td align="left">impressions</td></tr>
+        <tr><td></td><td align="left">clicks</td></tr>
+        <tr><td></td><td align="left">spend</td></tr>
+    </table>>]
+}

etc/dbt_pipeline.gv

@@ -0,0 +1,33 @@
+# cd ~/Documents/Visuals/Windsor.ai/erp
+# dot dbt_flow.gv -Tsvg -o dbt_flow.svg
+
+digraph {
+    labelloc=t;
+    label="Data pipeline"
+    rankdir=LR
+    node[shape=none]
+    compound=true
+
+    Windsor  [label="Windsor.ai\nconnector to\nFacebook Ads" shape=rect style="dashed"]
+
+    subgraph cluster_0 {
+        style="dashed"
+        label = "Facebook Ads\nsource tables"
+        account [fontcolor=blue]
+        campaign[fontcolor=blue]
+        ad_set  [fontcolor=blue]
+        ad      [fontcolor=blue]
+        report  [fontcolor=blue]
+    }
+
+    subgraph cluster_1 {
+        style="dashed"
+        label = "dbt model"
+        ad_report [fontcolor=green]
+    }
+
+    Windsor -> ad_set[lhead=cluster_0]
+
+    ad     -> ad_report
+    report -> ad_report
+}

etc/dbt_source.gv

@@ -0,0 +1,58 @@
+# cd ~/Documents/Visuals/Windsor.ai/erp
+# sfdp -Tpng -O vHub.dot
+# dot dbt_source.gv -Tsvg -o dbt_source.svg
+# convert -density 300 vHub.svg vHub.png
+digraph UBS {
+
+    #graph [pad="0.5", nodesep="0.5", ranksep="2"]
+    labelloc=t;
+    label="Windsor.ai connector to Facebook Ads source tables"
+    node [shape=plain]
+    rankdir=LR
+
+    account[label=<<table border="1" cellborder="0" cellspacing="0">
+        <tr><td colspan="2" bgcolor="lightblue" align="left">account</td></tr>
+        <tr><td port="account_id" fixedsize="true" width="17" height="17"><img src="pk.jpeg"/></td><td port="account_id2" align="left">account_id</td></tr>
+        <tr><td></td><td align="left">account_name</td></tr>
+    </table>>]
+
+    campaign[label=<<table border="1" cellborder="0" cellspacing="0">
+        <tr><td colspan="2" bgcolor="lightblue" align="left">campaign</td></tr>
+        <tr><td port="account_id" fixedsize="true" width="17" height="17"><img src="fk.jpeg"/></td><td port="account_id2" align="left">account_id</td></tr>
+        <tr><td port="campaign_id" fixedsize="true" width="17" height="17"><img src="pk.jpeg"/></td><td port="campaign_id2" align="left">campaign_id</td></tr>
+        <tr><td></td><td align="left">campaign</td></tr>
+    </table>>]
+
+    ad_set[label=<<table border="1" cellborder="0" cellspacing="0">
+        <tr><td colspan="2" bgcolor="lightblue" align="left">ad_set</td></tr>
+        <tr><td port="campaign_id" fixedsize="true" width="17" height="17"><img src="fk.jpeg"/></td><td port="campaign_id" align="left">campaign_id</td></tr>
+        <tr><td port="adset_id" fixedsize="true" width="17" height="17"><img src="pk.jpeg"/></td><td port="adset_id2" align="left">adset_id</td></tr>
+        <tr><td></td><td align="left">adset_name</td></tr>
+        <tr><td></td><td align="left">adset_start_time</td></tr>
+        <tr><td></td><td align="left">adset_end_time</td></tr>
+        <tr><td></td><td align="left">adset_bid_strategy</td></tr>
+        <tr><td></td><td align="left">adset_daily_budget</td></tr>
+    </table>>]
+
+    ad[label=<<table border="1" cellborder="0" cellspacing="0">
+        <tr><td colspan="2" bgcolor="lightblue" align="left">ad</td></tr>
+        <tr><td port="adset_id" fixedsize="true" width="17" height="17"><img src="fk.jpeg"/></td><td port="adset_id2" align="left">adset_id</td></tr>
+        <tr><td port="ad_id" fixedsize="true" width="17" height="17"><img src="pk.jpeg"/></td><td port="ad_id2" align="left">ad_id</td></tr>
+        <tr><td></td><td align="left">ad_name</td></tr>
+    </table>>]
+
+    report[label=<<table border="1" cellborder="0" cellspacing="0">
+        <tr><td colspan="2" bgcolor="lightblue" align="left">report</td></tr>
+        <tr><td port="ad_id" fixedsize="true" width="17" height="17"><img src="fk.jpeg"/></td><td port="ad_id2" align="left">ad_id</td></tr>
+        <tr><td></td><td align="left">date</td></tr>
+        <tr><td></td><td align="left">clicks</td></tr>
+        <tr><td></td><td align="left">impressions</td></tr>
+        <tr><td></td><td align="left">spend</td></tr>
+    </table>>]
+
+
+    account:account_id2   -> campaign:account_id[arrowhead=crow]
+    campaign:campaign_id2 -> ad_set:campaign_id [arrowhead=crow]
+    ad_set:adset_id2      -> ad:adset_id        [arrowhead=crow]
+    ad:ad_id2             -> report:ad_id       [arrowhead=crow]
+}