@luquimbo/bi-superpowers 3.1.1 → 3.2.0

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

@@ -1,350 +0,0 @@
-# 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)