@luquimbo/bi-superpowers 1.0.0

package/library/snippets/power-query/parameters.md

@@ -0,0 +1,350 @@
+# Query Parameters
+
+## Overview
+Power Query patterns for using parameters to create dynamic, reusable queries that can be easily configured for different environments and scenarios.
+
+---
+
+## Creating Parameters
+
+### In Power Query Editor
+1. Home → Manage Parameters → New Parameter
+2. Configure: Name, Type, Current Value, Allowed Values
+
+### Parameter Types
+| Type | Use Case | Example |
+|------|----------|---------|
+| Text | Server names, file paths, API keys | `param_ServerName` |
+| Number | Limits, thresholds, IDs | `param_TopN` |
+| Date | Start/end dates, cutoff dates | `param_StartDate` |
+| DateTime | Timestamps with time | `param_LastRefresh` |
+| True/False | Feature flags | `param_IncludeArchived` |
+| List | Multiple allowed values | Environment options |
+
+---
+
+## Common Parameter Patterns
+
+### Server/Database Parameters
+```m
+// Parameters (create in Manage Parameters)
+// param_ServerName: Text, e.g., "prod-sql-01.database.windows.net"
+// param_DatabaseName: Text, e.g., "SalesDB"
+
+let
+    Source = Sql.Database(param_ServerName, param_DatabaseName),
+    Sales = Source{[Schema="dbo", Item="Sales"]}[Data]
+in
+    Sales
+```
+
+### File Path Parameter
+```m
+// param_FilePath: Text, e.g., "C:\Data\SalesData.xlsx"
+
+let
+    Source = Excel.Workbook(File.Contents(param_FilePath), true, true),
+    Sheet1 = Source{[Item="Sheet1", Kind="Sheet"]}[Data]
+in
+    Sheet1
+```
+
+### Folder Path Parameter
+```m
+// param_FolderPath: Text, e.g., "C:\Data\Monthly Reports\"
+
+let
+    Source = Folder.Files(param_FolderPath),
+    FilteredFiles = Table.SelectRows(Source, each Text.EndsWith([Name], ".csv"))
+in
+    FilteredFiles
+```
+
+### Date Range Parameters
+```m
+// param_StartDate: Date, e.g., #date(2024, 1, 1)
+// param_EndDate: Date, e.g., #date(2024, 12, 31)
+
+let
+    Source = Sql.Database(param_ServerName, param_DatabaseName),
+    Sales = Source{[Schema="dbo", Item="Sales"]}[Data],
+    FilteredByDate = Table.SelectRows(Sales, each
+        [OrderDate] >= param_StartDate and [OrderDate] <= param_EndDate
+    )
+in
+    FilteredByDate
+```
+
+### API Token Parameter
+```m
+// param_APIToken: Text (mark as sensitive if supported)
+
+let
+    Source = Json.Document(
+        Web.Contents(
+            "https://api.example.com/data",
+            [
+                Headers = [
+                    #"Authorization" = "Bearer " & param_APIToken
+                ]
+            ]
+        )
+    )
+in
+    Source
+```
+
+---
+
+## Dynamic Parameters
+
+### Relative Date Parameters
+```m
+// Calculate dates dynamically
+let
+    Today = Date.From(DateTime.LocalNow()),
+    StartOfMonth = Date.StartOfMonth(Today),
+    StartOfYear = Date.StartOfYear(Today),
+    Last30Days = Date.AddDays(Today, -30),
+    LastMonthStart = Date.StartOfMonth(Date.AddMonths(Today, -1)),
+    LastMonthEnd = Date.EndOfMonth(Date.AddMonths(Today, -1))
+in
+    // Use in queries
+    Last30Days
+```
+
+### Rolling Period Query
+```m
+// No parameter needed - always last 12 months
+let
+    EndDate = Date.From(DateTime.LocalNow()),
+    StartDate = Date.AddMonths(EndDate, -12),
+
+    Source = Sql.Database(param_ServerName, param_DatabaseName),
+    Sales = Source{[Schema="dbo", Item="Sales"]}[Data],
+    Filtered = Table.SelectRows(Sales, each
+        [OrderDate] >= StartDate and [OrderDate] <= EndDate
+    )
+in
+    Filtered
+```
+
+---
+
+## Environment Configuration
+
+### Environment Parameter Pattern
+```m
+// param_Environment: Text, Allowed Values: "Development", "Staging", "Production"
+
+let
+    // Configuration table
+    Config = #table(
+        {"Environment", "Server", "Database"},
+        {
+            {"Development", "dev-sql-01", "SalesDB_Dev"},
+            {"Staging", "stg-sql-01", "SalesDB_Stg"},
+            {"Production", "prod-sql-01", "SalesDB"}
+        }
+    ),
+
+    // Get current environment config
+    CurrentConfig = Table.SelectRows(Config, each [Environment] = param_Environment){0},
+
+    // Connect using config values
+    Source = Sql.Database(CurrentConfig[Server], CurrentConfig[Database])
+in
+    Source
+```
+
+### Configuration Table Query
+```m
+// Create a query called "Config" with environment settings
+let
+    Source = #table(
+        type table [
+            Setting = text,
+            Development = text,
+            Staging = text,
+            Production = text
+        ],
+        {
+            {"ServerName", "dev-sql-01", "stg-sql-01", "prod-sql-01"},
+            {"DatabaseName", "SalesDB_Dev", "SalesDB_Stg", "SalesDB"},
+            {"APIEndpoint", "https://dev-api.example.com", "https://stg-api.example.com", "https://api.example.com"},
+            {"RefreshDays", "7", "30", "365"}
+        }
+    )
+in
+    Source
+
+// Usage in other queries:
+let
+    ServerName = Config{[Setting="ServerName"]}[param_Environment],
+    DatabaseName = Config{[Setting="DatabaseName"]}[param_Environment],
+    Source = Sql.Database(ServerName, DatabaseName)
+in
+    Source
+```
+
+---
+
+## Parameter in Native SQL
+
+### Date in SQL Query
+```m
+// param_StartDate: Date
+
+let
+    FormattedDate = Date.ToText(param_StartDate, "yyyy-MM-dd"),
+    Query = "SELECT * FROM dbo.Sales WHERE OrderDate >= '" & FormattedDate & "'",
+    Source = Sql.Database(param_ServerName, param_DatabaseName, [Query = Query])
+in
+    Source
+```
+
+### Multiple Parameters in SQL
+```m
+let
+    StartDateText = Date.ToText(param_StartDate, "yyyy-MM-dd"),
+    EndDateText = Date.ToText(param_EndDate, "yyyy-MM-dd"),
+
+    Query = "
+        SELECT *
+        FROM dbo.Sales
+        WHERE OrderDate BETWEEN '" & StartDateText & "' AND '" & EndDateText & "'
+        AND Region = '" & param_Region & "'
+    ",
+
+    Source = Sql.Database(param_ServerName, param_DatabaseName, [Query = Query])
+in
+    Source
+```
+
+### Parameterized Stored Procedure
+```m
+let
+    Source = Sql.Database(param_ServerName, param_DatabaseName),
+    Result = Source{[Schema="dbo", Item="usp_GetSalesByRegion"]}[Data]({param_Region, param_StartDate, param_EndDate})
+in
+    Result
+```
+
+---
+
+## Parameter Validation
+
+### Validate Before Use
+```m
+let
+    // Validate required parameters
+    ValidServer = if param_ServerName = null or param_ServerName = ""
+        then error "Server name is required"
+        else param_ServerName,
+
+    ValidDatabase = if param_DatabaseName = null or param_DatabaseName = ""
+        then error "Database name is required"
+        else param_DatabaseName,
+
+    Source = Sql.Database(ValidServer, ValidDatabase)
+in
+    Source
+```
+
+### Default Values
+```m
+let
+    // Use default if parameter is empty
+    ServerName = if param_ServerName = null or param_ServerName = ""
+        then "default-server"
+        else param_ServerName,
+
+    StartDate = if param_StartDate = null
+        then Date.AddMonths(Date.From(DateTime.LocalNow()), -12)
+        else param_StartDate,
+
+    Source = Sql.Database(ServerName, param_DatabaseName)
+in
+    Source
+```
+
+---
+
+## Parameter Functions
+
+### Create Reusable Connection Function
+```m
+// Query name: fn_GetSqlConnection
+(serverName as text, databaseName as text) as table =>
+let
+    Source = Sql.Database(serverName, databaseName)
+in
+    Source
+
+// Usage:
+let
+    DB = fn_GetSqlConnection(param_ServerName, param_DatabaseName),
+    Sales = DB{[Schema="dbo", Item="Sales"]}[Data]
+in
+    Sales
+```
+
+### Parameterized Data Function
+```m
+// Query name: fn_GetSalesByDateRange
+(startDate as date, endDate as date) as table =>
+let
+    Source = Sql.Database(param_ServerName, param_DatabaseName),
+    Sales = Source{[Schema="dbo", Item="Sales"]}[Data],
+    Filtered = Table.SelectRows(Sales, each
+        [OrderDate] >= startDate and [OrderDate] <= endDate
+    )
+in
+    Filtered
+
+// Usage:
+let
+    Q1Sales = fn_GetSalesByDateRange(#date(2024,1,1), #date(2024,3,31)),
+    Q2Sales = fn_GetSalesByDateRange(#date(2024,4,1), #date(2024,6,30))
+in
+    Table.Combine({Q1Sales, Q2Sales})
+```
+
+---
+
+## Best Practices
+
+### Naming Conventions
+| Pattern | Example | Use |
+|---------|---------|-----|
+| `param_` prefix | `param_ServerName` | All parameters |
+| PascalCase | `param_StartDate` | Multi-word names |
+| Descriptive | `param_SalesRegion` | Clear purpose |
+
+### Security Considerations
+1. **Never hardcode credentials** - Use parameters or environment variables
+2. **Mark sensitive parameters** - Power Query supports sensitive parameter marking
+3. **Don't log sensitive values** - Avoid exposing tokens in error messages
+4. **Use connection strings from data gateway** when possible
+
+### Documentation
+```m
+// Document parameter usage at top of query
+// Required Parameters:
+//   param_ServerName: SQL Server hostname
+//   param_DatabaseName: Target database name
+//   param_StartDate: Beginning of date range (inclusive)
+//   param_EndDate: End of date range (inclusive)
+
+let
+    Source = ...
+in
+    Source
+```
+
+---
+
+## Related Resources
+
+- [Connections](./connections.md)
+- [Power Query Skill](../../skills/power-query/SKILL.md)