From a8371dd06b35f61a8afeb8b745287c2dfeef4f1a Mon Sep 17 00:00:00 2001
From: Bruce Guenter <bruce.guenter@datadoghq.com>
Date: Tue, 3 Dec 2024 17:11:55 -0600
Subject: [PATCH] docs(vrl): Add documentation for new `zip` function (#21941)

* docs(vrl): Add documentation for new `zip` function

* Fix spelling
---
 website/cue/reference/remap/functions/zip.cue | 55 +++++++++++++++++++
 1 file changed, 55 insertions(+)
 create mode 100644 website/cue/reference/remap/functions/zip.cue

diff --git a/website/cue/reference/remap/functions/zip.cue b/website/cue/reference/remap/functions/zip.cue
new file mode 100644
index 0000000000000..90f5e7927596f
--- /dev/null
+++ b/website/cue/reference/remap/functions/zip.cue
@@ -0,0 +1,55 @@
+package metadata
+
+remap: functions: zip: {
+	category: "Array"
+	description: """
+		Iterate over several arrays in parallel, producing a new array containing arrays of items from each source.
+		The resulting array will be as long as the shortest input array, with all the remaining elements dropped.
+		This function is modeled from the `zip` function [in Python](https://docs.python.org/3/library/functions.html#zip),
+		but similar methods can be found in [Ruby](https://docs.ruby-lang.org/en/master/Array.html#method-i-zip)
+		and [Rust](https://doc.rust-lang.org/stable/std/iter/trait.Iterator.html#method.zip).
+
+		If a single parameter is given, it must contain an array of all the input arrays.
+		"""
+
+	arguments: [
+		{
+			name:        "array_0"
+			description: "The first array of elements, or the array of input arrays if no other parameter is present."
+			required:    true
+			type: ["array"]
+		},
+		{
+			name:        "array_1"
+			description: "The second array of elements. If not present, the first parameter contains all the arrays."
+			required:    false
+			type: ["array"]
+		},
+	]
+	internal_failure_reasons: [
+		"`array_0` and `array_1` must be arrays.",
+	]
+	return: {
+		types: ["array"]
+		rules: [
+			"`zip` is considered fallible if any of the parameters is not an array, or if only the first parameter is present and it is not an array of arrays.",
+		]
+	}
+
+	examples: [
+		{
+			title: "Merge two arrays"
+			source: #"""
+				zip([1, 2, 3], [4, 5, 6, 7])
+				"""#
+			return: [[1, 4], [2, 5], [3, 6]]
+		},
+		{
+			title: "Merge three arrays"
+			source: #"""
+				zip([[1, 2], [3, 4], [5, 6]])
+				"""#
+			return: [[1, 3, 5], [2, 4, 6]]
+		},
+	]
+}