From 2b6142d7e1f94689d4e9ae2bfa42ef5a121b93a8 Mon Sep 17 00:00:00 2001
From: Raghav Narang <raxyte@raxyte.dev>
Date: Thu, 2 Jul 2026 16:18:57 +0530
Subject: [PATCH] Document map_keys function

---
 src/content/docs/reference/functions.mdx      | 12 ++++
 .../docs/reference/functions/map_keys.mdx     | 64 +++++++++++++++++++
 2 files changed, 76 insertions(+)
 create mode 100644 src/content/docs/reference/functions/map_keys.mdx

diff --git a/src/content/docs/reference/functions.mdx b/src/content/docs/reference/functions.mdx
index 247003c91..1f7196288 100644
--- a/src/content/docs/reference/functions.mdx
+++ b/src/content/docs/reference/functions.mdx
@@ -571,6 +571,10 @@ functions:
     description: 'Retrieves a list of field names from a record.'
     example: 'record.keys()'
     path: 'reference/functions/keys'
+  - name: 'map_keys'
+    description: 'Renames top-level fields in a record.'
+    example: 'record.map_keys(key => key.to_lower())'
+    path: 'reference/functions/map_keys'
   - name: 'merge'
     description: 'Combines two records into a single record by merging their fields.'
     example: 'merge(foo, bar)'
@@ -1763,6 +1767,14 @@ record.keys()
 
 </ReferenceCard>
 
+<ReferenceCard title="map_keys" description="Renames top-level fields in a record." href="/reference/functions/map_keys">
+
+```tql
+record.map_keys(key => key.to_lower())
+```
+
+</ReferenceCard>
+
 <ReferenceCard title="merge" description="Combines two records into a single record by merging their fields." href="/reference/functions/merge">
 
 ```tql
diff --git a/src/content/docs/reference/functions/map_keys.mdx b/src/content/docs/reference/functions/map_keys.mdx
new file mode 100644
index 000000000..2ecd62a91
--- /dev/null
+++ b/src/content/docs/reference/functions/map_keys.mdx
@@ -0,0 +1,64 @@
+---
+title: map_keys
+category: Record
+example: 'record.map_keys(key => key.to_lower())'
+---
+
+Renames the top-level fields of a record by applying a lambda to each field name.
+
+```tql
+map_keys(x:record, function:string => string) -> record
+```
+
+## Description
+
+The `map_keys` function returns a record with the same field values as `x`, but
+with field names produced by `function`.
+
+The function applies only to top-level fields. To rename fields in a nested
+record, call `map_keys` on that nested record.
+
+The lambda receives each field name as a string. If the lambda returns `null` or
+a non-string value for a field, `map_keys` emits a warning and keeps that field's
+original name. If the mapped field names conflict, `map_keys` emits a warning and
+leaves the record unchanged.
+
+### `x: record`
+
+The record whose field names you want to rename.
+
+### `function: string => string`
+
+A unary lambda that maps each field name to a new field name.
+
+## Examples
+
+### Lowercase record field names
+
+```tql
+from {
+  request: {
+    "Cache-Control": "no-cache, no-store",
+    Pragma: "no-cache",
+    Host: "domain.gent",
+  },
+}
+request = request.map_keys(key => key.to_lower())
+```
+
+```tql
+{
+  request: {
+    "cache-control": "no-cache, no-store",
+    pragma: "no-cache",
+    host: "domain.gent",
+  },
+}
+```
+
+## See Also
+
+- <Fn>drop_matching</Fn>
+- <Fn>keys</Fn>
+- <Fn>select_matching</Fn>
+- <Guide>transformation/shape-records</Guide>