Merge pull request #1 from sdf-labs/elias/firstCommit

Added initial utility macros, initial README, and compile test

.github/workflows/compile-workspace.yml

@@ -0,0 +1,27 @@
+name: Test Workspace Compilation
+
+on:
+  workflow_dispatch:
+  pull_request:
+
+jobs:
+  compile-workspace:
+    runs-on: ubuntu-latest
+    name: Compile SDF Workspace
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Run sdf compile
+        uses: sdf-labs/sdf-action@v0
+        id: sdf
+        with:
+          command: 'sdf compile'
+
+      # Use the output from the `sdf` step
+      - name: Display the sdf output
+        run: |
+          echo "### SDF Run Logs 🪵" >> $GITHUB_STEP_SUMMARY
+          echo '```' >>$GITHUB_STEP_SUMMARY
+          echo "${{ steps.sdf.outputs.log }}" >>$GITHUB_STEP_SUMMARY
+          echo '```' >>$GITHUB_STEP_SUMMARY

.gitignore

@@ -0,0 +1,3 @@
+
+#sdf gitignore
+/.sdfcache

README.md

@@ -1,2 +1,18 @@
-# utils
-Official utilities library for SDF
+[![SDF Workspace Compiles](https://github.com/sdf-labs/utils/actions/workflows/compile-workspace.yml/badge.svg)](https://github.com/sdf-labs/utils/actions/workflows/compile-workspace.yml)
+
+# Official SDF Utils Library
+
+This SDF library contains the standard utilities available in the default namespace in any SDF workspace. As such, macros defined in this workspace do not need to be prefixed with the workspace name, they can be referenced directly. Here's an example:
+
+```sql
+SELECT 
+  date
+FROM
+  dates
+WHERE
+  date IN {{ generate_date_strings('2020-01-01', '2020-01-10') }}
+```
+
+*Note: SDF is still < v1, as such certain scenarios may result in unexpected behavior. Please follow the [contributing guidelines](./CONTRIBUTING.md) and create an issue in this repo if you find any bugs or issues.*
+
+For an in-depth guide on how to use Jinja macros in SDF, please see the Jinja section of [our official docs](https://docs.sdf.com/guide/macro-processing/jinja)

macros/generate_date_values.jinja

@@ -0,0 +1,54 @@
+{#
+    Macro: generate_date_strings(from, to)
+
+    This macro generates a SQL VALUES clause with a list of date strings. The date strings are generated for each day 
+    in the range from the 'from' date to the 'to' date, inclusive.
+
+    Parameters:
+    - from: The start date of the range, as a string in 'YYYY-MM-DD' format.
+    - to: The end date of the range, as a string in 'YYYY-MM-DD' format.
+
+    Returns:
+    A string representing a SQL VALUES clause with a list of date strings.
+
+    Example usage:
+    {{generate_date_strings('2022-01-01', '2022-01-03')}}
+
+    This will generate:
+    (VALUES '2022-01-01', '2022-01-02', '2022-01-03')
+
+#}
+
+{% macro generate_date_strings(from, to) %}
+(VALUES
+{% for i in __generate_date_strings__('2022-01-01', '2022-01-03') -%} '{{i}}' {{ "," if not loop.last else "" }}
+{%- endfor %} )
+{% endmacro %}
+
+
+{#
+    Macro: generate_date_values(from, to)
+
+    This macro generates a SQL SELECT statement that produces a single column of dates. 
+    The dates are generated for each day in the range from the 'from' date to the 'to' date, inclusive.
+
+    Parameters:
+    - from: The start date of the range, as a string in 'YYYY-MM-DD' format.
+    - to: The end date of the range, as a string in 'YYYY-MM-DD' format.
+
+    Returns:
+    A string representing a SQL SELECT statement.
+
+    Example usage:
+    {{generate_date_values('2022-01-01', '2022-01-03')}}
+
+    This will generate:
+    (SELECT cast(value as date) as "date" FROM (VALUES '2022-01-01', '2022-01-02', '2022-01-03') as dates(value))
+#}
+
+{% macro generate_date_values(from, to) %}
+(SELECT cast(value as date) as "date" FROM {{ generate_date_strings(from, to) }} as dates(value))
+{% endmacro %}
+
+
+

macros/generate_integer_values.jinja

@@ -0,0 +1,5 @@
+{% macro generate_integer_values(from, to) %}
+(VALUES
+{% for i in range(from, to + 1) -%} {{i}} {{ "," if not loop.last else "" }}
+{%- endfor %} )
+{% endmacro %}

macros/star.jinja

@@ -0,0 +1,15 @@
+{% macro quote(x) %}
+    {{ x }}
+{% endmacro %}
+
+{% macro star(from,except=[], prefix='', suffix='', quote_identifiers=False) -%}
+    {% set cols = __get_filtered_columns_in_relation__(from, except) %}
+        {%- for col in cols %}
+                {%- if quote_identifiers -%}
+                    {{ adapter.quote(col)|trim }} {%- if prefix!='' or suffix!='' %} as {{ quote(prefix ~ col ~ suffix)|trim }} {%- endif -%}
+                {%- else -%}
+                    {{ col|trim }} {%- if prefix!='' or suffix!='' %} as {{ (prefix ~ col ~ suffix)|trim }} {%- endif -%}
+                {% endif %}
+            {%- if not loop.last %},{{ '\n  ' }}{%- endif -%}
+        {%- endfor -%}
+{%- endmacro %}

macros/surrogate_key.jinja

@@ -0,0 +1,41 @@
+{# 
+  Macro: generate_surrogate_key
+  Description: This macro generates a surrogate key for a given list of fields. 
+  The surrogate key is a unique identifier for each record in a table. 
+  It is generated by concatenating the values of the given fields and applying the MD5 hash function to the result.
+  The fields are cast to varchar type before concatenation. 
+  If a field value is null, it is replaced with the string '_jinja_surrogate_key_null_'.
+  The resulting surrogate key is a varchar type.
+
+  Parameters:
+  fields - A list of field names for which the surrogate key should be generated.
+
+  Usage:
+  SELECT
+      {{ generate_surrogate_key(['column1', 'column2', 'column3']) }} AS surrogate_key,
+      column1,
+      column2,
+      column3
+  FROM
+      (Values ('a', 'b', 'c'), ('d', 'e', 'f'), ('g', 'h', 'i')) AS t(column1, column2, column3);
+
+  This will produce:
+  SELECT
+      md5(
+          coalesce(cast(column1 as varchar),'_jinja_surrogate_key_null_')
+           || coalesce(cast(column2 as varchar),'_jinja_surrogate_key_null_')
+           || coalesce(cast(column3 as varchar),'_jinja_surrogate_key_null_')) AS surrogate_key,
+      ...
+  Resulting in types like this:
+  | column_name   | data_type | classifier |
+  +---------------+-----------+------------+
+  | surrogate_key | varchar   |            |
+#}
+{%- macro generate_surrogate_key(fields) -%}    
+    md5(
+    {%- for field in fields %}
+        {% if not loop.first %}|| {% endif -%}
+        coalesce(cast({{ field }} as varchar),'_jinja_surrogate_key_null_')
+    {%- endfor -%}
+    )
+{%- endmacro -%}

workspace.sdf.yml

@@ -0,0 +1,6 @@
+workspace:
+  name: sdf_utils
+  edition: "1.2"
+  includes:
+    - path: macros/*.jinja
+      type: metadata