docs: update comments to clarify behaviour (#5506)

* docs: update comments to clarify behaviour * fix: correct sentence * chore: Update stdlib/influxdata/influxdb/influxdb.flux Co-authored-by: Martin Hilton <[email protected]> * chore: generate --------- Co-authored-by: Martin Hilton <[email protected]>
influxdata · Oct 4, 2024 · b5a2f38 · b5a2f38
1 parent da19e08
commit b5a2f38
Show file tree

Hide file tree

Showing 2 changed files with 23 additions and 5 deletions.
diff --git a/libflux/go/libflux/buildinfo.gen.go b/libflux/go/libflux/buildinfo.gen.go
@@ -235,7 +235,7 @@ var sourceHashes = map[string]string{
 	"stdlib/http/http.flux":                                                                       "b1e02153693002f80134f6bd76108afa11f7a0c4ee041bcfc17c373c1a6c1338",
 	"stdlib/http/http_path_encode_endpoint_test.flux":                                             "cb1e075f9d0f5d2a2d46b6cec6a8e34eb932f3d31b5494f48a3135c9503d4038",
 	"stdlib/http/requests/requests.flux":                                                          "f88df79b7918f5ab92860197118070bc05f9bbbd9a7261462cecd367dfeeb704",
-	"stdlib/influxdata/influxdb/influxdb.flux":                                                    "101d6ab960d5e1fed6622ccfe8adea1911c317666aa7daa5a2a29a8f96abdd8b",
+	"stdlib/influxdata/influxdb/influxdb.flux":                                                    "e6b28fcea063420a83cdbcb54e4c40d28d28aa27c4b59b012eed7ac8ea6896a4",
 	"stdlib/influxdata/influxdb/monitor/check_test.flux":                                          "9f36d19fd834a8230beaba8782a721697b2b0e1b408ee3f948387b0b8d702bfb",
 	"stdlib/influxdata/influxdb/monitor/deadman_add_test.flux":                                    "4bc5d036f028cd9aa078ed653c61be8b43992779ead1ca5bb26e554d428ffe8a",
 	"stdlib/influxdata/influxdb/monitor/deadman_sub_test.flux":                                    "c1f892d5d078a3b2cf3c3fbf68710a676cc47c82e3959f0ce6fe82af932afb6a",

diff --git a/stdlib/influxdata/influxdb/influxdb.flux b/stdlib/influxdata/influxdb/influxdb.flux
@@ -6,7 +6,14 @@
 package influxdb
 
 
-// cardinality returns the series cardinality of data stored in InfluxDB.
+// cardinality returns the series cardinality of data retrieved InfluxDB.
+//
+// Although this function is similar to InfluxQL's `SHOW SERIES CARDINALITY` it works in a slightly
+// different manner.
+//
+// Cardinality is time bounded and reports the cardinality of the data that matches the conditions
+// passed into it, rather than that of the bucket as a whole.
+//
 //
 // ## Parameters
 // - bucket: Bucket to query cardinality from.
@@ -31,6 +38,9 @@ package influxdb
 //      Use a relative duration or absolute time. For example, `-1h` or `2019-08-28T22:00:00Z`.
 //      Durations are relative to `now()`. Default is `now()`.
 //
+//      Note: because the default is `now()`, any points that have been written into the future
+//      will not be counted unless a future `stop` date is provided
+//
 // - predicate: Predicate function that filters records.
 //      Default is `(r) => true`.
 //
@@ -42,17 +52,19 @@ package influxdb
 //
 // influxdb.cardinality(
 //     bucket: "example-bucket",
-//     start: -1y,
+//     start: time(v: 1),
 // )
 // ```
+// Note: if points have been written into the future, you will need to add an appropriate `stop` date
+//
 //
 // ### Query series cardinality in a measurement//
 // ```no_run
 // import "influxdata/influxdb"
 //
 // influxdb.cardinality(
 //     bucket: "example-bucket",
-//     start: -1y,
+//     start: time(v: 1),
 //     predicate: (r) => r._measurement == "example-measurement",
 // )
 // ```
@@ -63,11 +75,17 @@ package influxdb
 //
 // influxdb.cardinality(
 //    bucket: "example-bucket",
-//    start: -1y,
+//    start: time(v: 1),
 //    predicate: (r) => r.exampleTag == "foo",
 // )
 // ```
 //
+// ### Query cardinality of data written in the last 4 hours
+// ```no_run
+// import "influxdata/influxdb"
+//
+// influxdb.cardinality(bucket: "example-bucket", start: -4h)
+// ```
 // ## Metadata
 // introduced: 0.92.0
 // tags: metadata