diff --git a/.github/workflows/codeql-analysis.yml b/.github/workflows/codeql-analysis.yml
index 83b013d09..5b3bc04f5 100644
--- a/.github/workflows/codeql-analysis.yml
+++ b/.github/workflows/codeql-analysis.yml
@@ -9,7 +9,13 @@ name: "CodeQL"
 on:
   push:
     branches: [ "main" ]
-  pull_request: {}
+    paths:
+      - .github/workflows/codeql-analysis.yml
+      - '**.py'  # Any Python file
+  pull_request:
+    paths:
+      - .github/workflows/codeql-analysis.yml
+      - '**.py'  # Any Python file
   schedule:
     - cron: '37 10 * * 5'
 
diff --git a/docs/stream_maps.md b/docs/stream_maps.md
index c8d1e8cc9..8d84d9ea0 100644
--- a/docs/stream_maps.md
+++ b/docs/stream_maps.md
@@ -47,6 +47,24 @@ three distinct fields:
 - `user__last_name`
 - `user__id`
 
+#### Flattening Example
+
+````{tab} meltano.yml
+```yaml
+flattening_enabled: true
+flattening_max_depth: 1   # flatten only top-level properties
+```
+````
+
+````{tab} JSON
+```json
+{
+  "flattening_enabled": true,
+  "flattening_max_depth": 1
+}
+```
+````
+
 ## Out-of-scope capabilities
 
 These capabilities are all out of scope _by design_: