feat(iox): add iox.sqlInterval to convert flux durations to SQL interval strings (#5356)

* feat(iox): add iox.sqlInterval to convert flux durations to SQL interval strings

* chore(iox): rename and fix iox_sql_interval test

* chore(iox): fixed typo

Author: sanderson

.hugo_build.lock

@@ -193,7 +193,8 @@ var sourceHashes = map[string]string{
 	"stdlib/experimental/http/requests/requests.flux":                                             "579f5d578722a425f350db50dc2697a8bce7bcddc3737d094ae96126b6f96c56",
 	"stdlib/experimental/influxdb/influxdb.flux":                                                  "503f68779c9d8a4c307d371cce8071826d0462a00e486190b3dfa681f9b620dc",
 	"stdlib/experimental/integral_test.flux":                                                      "4c9b6c866884839027946e93793689b8b3d328e2e777f8ee2f8973ffd72be036",
-	"stdlib/experimental/iox/iox.flux":                                                            "a543270b0163c0d23b005aa71aa7c1474b691e4845e857a514adab7e537f4621",
+	"stdlib/experimental/iox/iox.flux":                                                            "1e7dc17722b99c26ea455c0eee4047282604ee62c69d44e066a27631d86d36e8",
+	"stdlib/experimental/iox/iox_test.flux":                                                       "04624caf7807128826564e18bafde5ad8033eaf0f8c6edfe0c9300c03c88aac0",
 	"stdlib/experimental/join_right_side_more_cols_test.flux":                                     "788bd7fe3dc6d324453484bdee64f1e408c291a43ffa3744e930c7ae5e533db7",
 	"stdlib/experimental/join_test.flux":                                                          "a48f78765b34d8011e45e0333cdc10ed578076f9a34443e50c6f7633978ea549",
 	"stdlib/experimental/json/json.flux":                                                          "50479ced0a3ae185164cbecd5f071f849ea30b727385afec8d525ff98c7460be",

libflux/go/libflux/buildinfo.gen.go

@@ -5,6 +5,9 @@
 package iox
 
 
+import "regexp"
+import "strings"
+
 // from reads from the selected bucket and measurement in an IOx storage node.
 //
 // This function creates a source that reads data from IOx. Output data is
@@ -15,6 +18,17 @@ package iox
 // - bucket: IOx bucket to read data from.
 // - measurement: Measurement to read data from.
 //
+// ## Examples
+//
+// ### Use Flux to query data from IOx
+// ```no_run
+// import "experimental/iox"
+//
+// iox.from(bucket: "example-bucket", measurement: "example-measurement")
+//     |> range(start: -1d)
+//     |> filter(fn: (r) => r._field == "example-field")
+// ```
+//
 // ## Metadata
 // tags: inputs
 builtin from : (bucket: string, measurement: string) => stream[{A with _time: time}] where A: Record
@@ -25,9 +39,79 @@ builtin from : (bucket: string, measurement: string) => stream[{A with _time: ti
 //
 // ## Parameters
 // - bucket: IOx bucket to read data from.
-// - query: Query to execute.
+// - query: SQL query to execute.
+//
+// ## Examples
+//
+// ### Use SQL to query data from IOx
+// ```no_run
+// import "experimental/iox"
+//
+// iox.sql(bucket: "example-bucket", query: "SELECT * FROM measurement")
+// ```
 //
 // ## Metadata
 // introduced: 0.186.0
 // tags: inputs
 builtin sql : (bucket: string, query: string) => stream[A] where A: Record
+
+// sqlInterval converts a duration value to a SQL interval string.
+//
+// SQL interval strings support down to millisecond precision.
+// Any microsecond or nanosecond duration units are dropped from the duration value.
+// If the duration only consists of microseconds or nanosecond units,
+// `iox.sqlInterval()` returns `1 millisecond`.
+// Duration values must be positive to work as a SQL interval string.
+//
+// ## Parameters
+// - d: Duration value to convert to SQL interval string.
+//
+// ## Examples
+//
+// ### Convert a duration to a SQL interval
+// ```no_run
+// import "experimental/iox"
+//
+// iox.sqlInterval(d: 1y2mo3w4d5h6m7s8ms)
+// // Returns 1 years 2 months 3 weeks 4 days 5 hours 6 minutes 7 seconds 8 milliseconds
+// ```
+//
+// ### Use a Flux duration to define a SQL interval
+// ```no_run
+// import "experimental/iox"
+//
+// windowInterval = 1d12h
+// sqlQuery = "
+// SELECT
+//   DATE_BIN(INTERVAL '${iox.sqlInterval(d: windowInterval)}', time, TIMESTAMP '2023-01-01T00:00:00Z')
+//   COUNT(field1)
+// FROM
+//   measurement
+// GROUP BY
+//   time
+// "
+//
+// iox.sql(bucket: "example-bucket", query: sqlQuery)
+// ```
+//
+// ## Metadata
+// introduced: NEXT
+// tags: sql, type-conversions
+sqlInterval = (d) => {
+    _durationString = string(v: d)
+    _pipeRegex = (v=<-, r, t) => regexp.replaceAllString(v: v, r: r, t: t)
+    _intervalString =
+        _pipeRegex(v: _durationString, r: /[\d]+(us|ns)/, t: "")
+            |> _pipeRegex(r: /([^\d]+)/, t: " $1 ")
+            |> _pipeRegex(r: / ms /, t: " milliseconds ")
+            |> _pipeRegex(r: / s /, t: " seconds ")
+            |> _pipeRegex(r: / m /, t: " minutes ")
+            |> _pipeRegex(r: / h /, t: " hours ")
+            |> _pipeRegex(r: / d /, t: " days ")
+            |> _pipeRegex(r: / w /, t: " weeks ")
+            |> _pipeRegex(r: / mo /, t: " months ")
+            |> _pipeRegex(r: / y /, t: " years ")
+    _output = if _intervalString == "" then "1 millisecond" else _intervalString
+
+    return strings.trimSpace(v: _output)
+}

stdlib/experimental/iox/iox.flux

@@ -0,0 +1,31 @@
+package iox_test
+
+
+import "array"
+import "testing"
+import "experimental/iox"
+
+testcase iox_sql_interval_testcase {
+    got =
+        array.from(
+            rows: [
+                {_value: "12y3mo4w"},
+                {_value: "12d34h5m"},
+                {_value: "123s56ms"},
+                {_value: "123us56ns"},
+            ],
+        )
+            |> map(fn: (r) => ({_value: iox.sqlInterval(d: duration(v: r._value))}))
+
+    want =
+        array.from(
+            rows: [
+                {_value: "12 years 3 months 4 weeks"},
+                {_value: "1 weeks 6 days 10 hours 5 minutes"},
+                {_value: "2 minutes 3 seconds 56 milliseconds"},
+                {_value: "1 millisecond"},
+            ],
+        )
+
+    testing.diff(got: got, want: want)
+}