From 6acf9857c8d0ee1ee549b86f987011a0ff77936c Mon Sep 17 00:00:00 2001 From: Scott Anderson Date: Fri, 11 Dec 2020 13:37:00 -0700 Subject: [PATCH 1/7] documented flux dict types, closes #1796 --- .../query-data/get-started/query-influxdb.md | 122 +------- .../query-data/get-started/syntax-basics.md | 223 +-------------- .../query-data/get-started/transform-data.md | 174 +---------- .../reference/flux/language/expressions.md | 269 +---------------- .../cloud/reference/flux/language/types.md | 270 +----------------- .../query-data/get-started/query-influxdb.md | 4 +- .../query-data/get-started/syntax-basics.md | 31 +- .../query-data/get-started/transform-data.md | 4 +- .../reference/flux/language/expressions.md | 23 ++ .../v2.0/reference/flux/language/types.md | 11 +- 10 files changed, 67 insertions(+), 1064 deletions(-) diff --git a/content/influxdb/cloud/query-data/get-started/query-influxdb.md b/content/influxdb/cloud/query-data/get-started/query-influxdb.md index 07b7b60d9..28cab1c8e 100644 --- a/content/influxdb/cloud/query-data/get-started/query-influxdb.md +++ b/content/influxdb/cloud/query-data/get-started/query-influxdb.md @@ -14,124 +14,4 @@ related: - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/filter --- -This guide walks through the basics of using Flux to query data from InfluxDB. -Every Flux query needs the following: - -1. [A data source](#1-define-your-data-source) -2. [A time range](#2-specify-a-time-range) -3. [Data filters](#3-filter-your-data) - - -## 1. Define your data source -Flux's [`from()`](/influxdb/cloud/reference/flux/stdlib/built-in/inputs/from) function defines an InfluxDB data source. -It requires a [`bucket`](/influxdb/cloud/reference/flux/stdlib/built-in/inputs/from#bucket) parameter. -The following examples use `example-bucket` as the bucket name. - -```js -from(bucket:"example-bucket") -``` - -## 2. Specify a time range -Flux requires a time range when querying time series data. -"Unbounded" queries are very resource-intensive and as a protective measure, -Flux will not query the database without a specified range. - -Use the pipe-forward operator (`|>`) to pipe data from your data source into the [`range()`](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/range) -function, which specifies a time range for your query. -It accepts two parameters: `start` and `stop`. -Ranges can be **relative** using negative [durations](/influxdb/cloud/reference/flux/language/lexical-elements#duration-literals) -or **absolute** using [timestamps](/influxdb/cloud/reference/flux/language/lexical-elements#date-and-time-literals). - -###### Example relative time ranges -```js -// Relative time range with start only. Stop defaults to now. -from(bucket:"example-bucket") - |> range(start: -1h) - -// Relative time range with start and stop -from(bucket:"example-bucket") - |> range(start: -1h, stop: -10m) -``` - -{{% note %}} -Relative ranges are relative to "now." -{{% /note %}} - -###### Example absolute time range -```js -from(bucket:"example-bucket") - |> range(start: 2018-11-05T23:30:00Z, stop: 2018-11-06T00:00:00Z) -``` - -#### Use the following: -For this guide, use the relative time range, `-15m`, to limit query results to data from the last 15 minutes: - -```js -from(bucket:"example-bucket") - |> range(start: -15m) -``` - -## 3. Filter your data -Pass your ranged data into the `filter()` function to narrow results based on data attributes or columns. -The `filter()` function has one parameter, `fn`, which expects an anonymous function -with logic that filters data based on columns or attributes. - -Flux's anonymous function syntax is similar to Javascript's. -Records or rows are passed into the `filter()` function as a record (`r`). -The anonymous function takes the record and evaluates it to see if it matches the defined filters. -Use the `and` relational operator to chain multiple filters. - -```js -// Pattern -(r) => (r.recordProperty comparisonOperator comparisonExpression) - -// Example with single filter -(r) => (r._measurement == "cpu") - -// Example with multiple filters -(r) => (r._measurement == "cpu") and (r._field != "usage_system" ) -``` - -#### Use the following: -For this example, filter by the `cpu` measurement, the `usage_system` field, and the `cpu-total` tag value: - -```js -from(bucket:"example-bucket") - |> range(start: -15m) - |> filter(fn: (r) => - r._measurement == "cpu" and - r._field == "usage_system" and - r.cpu == "cpu-total" - ) -``` - -## 4. Yield your queried data -Flux's `yield()` function outputs the filtered tables as the result of the query. - -```js -from(bucket:"example-bucket") - |> range(start: -15m) - |> filter(fn: (r) => - r._measurement == "cpu" and - r._field == "usage_system" and - r.cpu == "cpu-total" - ) - |> yield() -``` - -Flux automatically assumes a `yield()` function at -the end of each script in order to output and visualize the data. -Explicitly calling `yield()` is only necessary when including multiple queries in the same Flux query. -Each set of returned data needs to be named using the `yield()` function. - -## Congratulations! -You have now queried data from InfluxDB using Flux. - -The query shown here is a barebones example. -Flux queries can be extended in many ways to form powerful scripts. - - - +{{< duplicate-oss >}} \ No newline at end of file diff --git a/content/influxdb/cloud/query-data/get-started/syntax-basics.md b/content/influxdb/cloud/query-data/get-started/syntax-basics.md index af809b203..b9674e69e 100644 --- a/content/influxdb/cloud/query-data/get-started/syntax-basics.md +++ b/content/influxdb/cloud/query-data/get-started/syntax-basics.md @@ -12,225 +12,4 @@ related: --- -Flux, at its core, is a scripting language designed specifically for working with data. -This guide walks through a handful of simple expressions and how they are handled in Flux. - -## Use the Flux REPL -Use the [Flux REPL](/influxdb/cloud/tools/repl/) to open the interactive Read-Eval-Print Loop (REPL). -Run the commands provided in this guide in the REPL. - -##### Start the Flux REPL -```bash -./flux repl -``` - -## Basic Flux syntax -The code blocks below provide commands that illustrate the basic syntax of Flux. -Run these commands in the REPL. - -### Simple expressions -Flux is a scripting language that supports basic expressions. -For example, simple addition: - -```js -> 1 + 1 -2 -``` - -### Variables -Assign an expression to a variable using the assignment operator, `=`. - -```js -> s = "this is a string" -> i = 1 // an integer -> f = 2.0 // a floating point number -``` - -Type the name of a variable to print its value: - -```js -> s -this is a string -> i -1 -> f -2 -``` - -### Records -Flux also supports records. Each value in a record can be a different data type. - -```js -> o = {name:"Jim", age: 42, "favorite color": "red"} -``` - -Use **dot notation** to access a properties of a record: - -```js -> o.name -Jim -> o.age -42 -``` - -Or **bracket notation**: - -```js -> o["name"] -Jim -> o["age"] -42 -> o["favorite color"] -red -``` - -{{% note %}} -Use bracket notation to reference record properties with special or -white space characters in the property key. -{{% /note %}} - -### Arrays -Flux supports arrays. All values in an array must be the same type. - -```js -> n = 4 -> l = [1,2,3,n] -> l -[1, 2, 3, 4] -``` - -### Functions -Flux uses functions for most of its heavy lifting. -Below is a simple function that squares a number, `n`. - -```js -> square = (n) => n * n -> square(n:3) -9 -``` - -{{% note %}} -Flux does not support positional arguments or parameters. -Parameters must always be named when calling a function. -{{% /note %}} - -### Pipe-forward operator -Flux uses the pipe-forward operator (`|>`) extensively to chain operations together. -After each function or operation, Flux returns a table or collection of tables containing data. -The pipe-forward operator pipes those tables into the next function where they are further processed or manipulated. - -```js -data |> someFunction() |> anotherFunction() -``` - -## Real-world application of basic syntax -This likely seems familiar if you've already been through through the other -[getting started guides](/influxdb/cloud/query-data/get-started). -Flux's syntax is inspired by Javascript and other functional scripting languages. -As you begin to apply these basic principles in real-world use cases such as creating data stream variables, -custom functions, etc., the power of Flux and its ability to query and process data will become apparent. - -The examples below provide both multi-line and single-line versions of each input command. -Carriage returns in Flux aren't necessary, but do help with readability. -Both single- and multi-line commands can be copied and pasted into the `influx` CLI running in Flux mode. - -### Define data stream variables -A common use case for variable assignments in Flux is creating variables for one -or more input data streams. - -{{< code-tabs-wrapper >}} - {{% code-tabs %}} - [Multi-line](#) - [Single-line](#) - {{% /code-tabs %}} -{{% code-tab-content %}} -```js -timeRange = -1h - -cpuUsageUser = - from(bucket:"example-bucket") - |> range(start: timeRange) - |> filter(fn: (r) => - r._measurement == "cpu" and - r._field == "usage_user" and - r.cpu == "cpu-total" - ) - -memUsagePercent = - from(bucket:"example-bucket") - |> range(start: timeRange) - |> filter(fn: (r) => - r._measurement == "mem" and - r._field == "used_percent" - ) -``` -{{% /code-tab-content %}} - -{{% code-tab-content %}} -```js -timeRange = -1h -cpuUsageUser = from(bucket:"example-bucket") |> range(start: timeRange) |> filter(fn: (r) => r._measurement == "cpu" and r._field == "usage_user" and r.cpu == "cpu-total") -memUsagePercent = from(bucket:"example-bucket") |> range(start: timeRange) |> filter(fn: (r) => r._measurement == "mem" and r._field == "used_percent") -``` -{{% /code-tab-content %}} -{{< /code-tabs-wrapper>}} - -These variables can be used in other functions, such as `join()`, while keeping the syntax minimal and flexible. - -### Define custom functions -Create a function that returns the `N` number rows in the input stream with the highest `_value`s. -To do this, pass the input stream (`tables`) and the number of results to return (`n`) into a custom function. -Then using Flux's `sort()` and `limit()` functions to find the top `n` results in the data set. - -{{< code-tabs-wrapper >}} - {{% code-tabs %}} - [Multi-line](#) - [Single-line](#) - {{% /code-tabs %}} -{{% code-tab-content %}} -```js -topN = (tables=<-, n) => - tables - |> sort(desc: true) - |> limit(n: n) -``` -{{% /code-tab-content %}} -{{% code-tab-content %}} -```js -topN = (tables=<-, n) => tables |> sort(desc: true) |> limit(n: n) -``` -{{% /code-tab-content %}} -{{< /code-tabs-wrapper >}} - -Using this new custom function `topN` and the `cpuUsageUser` data stream variable defined above, -we can find the top five data points and yield the results. - -{{< code-tabs-wrapper >}} -{{% code-tabs %}} -[Multi-line](#) -[Single-line](#) -{{% /code-tabs %}} - -{{% code-tab-content %}} -```js -cpuUsageUser - |> topN(n:5) - |> yield() -``` -{{% /code-tab-content %}} - -{{% code-tab-content %}} -```js -cpuUsageUser |> topN(n:5) |> yield() -``` -{{% /code-tab-content %}} - -{{< /code-tabs-wrapper>}} - -This query will return the five data points with the highest user CPU usage over the last hour. - -_More information about creating custom functions is available in the [Custom functions](/influxdb/cloud/query-data/flux/custom-functions) documentation._ - - +{{< duplicate-oss >}} \ No newline at end of file diff --git a/content/influxdb/cloud/query-data/get-started/transform-data.md b/content/influxdb/cloud/query-data/get-started/transform-data.md index b458fbdc2..98e74fb43 100644 --- a/content/influxdb/cloud/query-data/get-started/transform-data.md +++ b/content/influxdb/cloud/query-data/get-started/transform-data.md @@ -12,176 +12,4 @@ related: - /influxdb/cloud/reference/flux/stdlib/built-in/transformations/window --- -When [querying data from InfluxDB](/influxdb/cloud/query-data/get-started/query-influxdb), -you often need to transform that data in some way. -Common examples are aggregating data into averages, downsampling data, etc. - -This guide demonstrates using [Flux functions](/influxdb/cloud/reference/flux/stdlib) to transform your data. -It walks through creating a Flux script that partitions data into windows of time, -averages the `_value`s in each window, and outputs the averages as a new table. -(Remember, Flux structures all data in [tables](/influxdb/cloud/query-data/get-started/#tables).) - -It's important to understand how the "shape" of your data changes through each of these operations. - -## Query data -Use the query built in the previous [Query data from InfluxDB](/influxdb/cloud/query-data/get-started/query-influxdb) -guide, but update the range to pull data from the last hour: - -```js -from(bucket:"example-bucket") - |> range(start: -1h) - |> filter(fn: (r) => - r._measurement == "cpu" and - r._field == "usage_system" and - r.cpu == "cpu-total" - ) -``` - -## Flux functions -Flux provides a number of functions that perform specific operations, transformations, and tasks. -You can also [create custom functions](/influxdb/cloud/query-data/flux/custom-functions) in your Flux queries. -_Functions are covered in detail in the [Flux functions](/influxdb/cloud/reference/flux/stdlib) documentation._ - -A common type of function used when transforming data queried from InfluxDB is an aggregate function. -Aggregate functions take a set of `_value`s in a table, aggregate them, and transform -them into a new value. - -This example uses the [`mean()` function](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/mean) -to average values within each time window. - -{{% note %}} -The following example walks through the steps required to window and aggregate data, -but there is a [`aggregateWindow()` helper function](#helper-functions) that does it for you. -It's just good to understand the steps in the process. -{{% /note %}} - -## Window your data -Flux's [`window()` function](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/window) partitions records based on a time value. -Use the `every` parameter to define a duration of each window. - -{{% note %}} -#### Calendar months and years -`every` supports all [valid duration units](/influxdb/cloud/reference/flux/language/types/#duration-types), -including **calendar months (`1mo`)** and **years (`1y`)**. -{{% /note %}} - -For this example, window data in five minute intervals (`5m`). - -```js -from(bucket:"example-bucket") - |> range(start: -1h) - |> filter(fn: (r) => - r._measurement == "cpu" and - r._field == "usage_system" and - r.cpu == "cpu-total" - ) - |> window(every: 5m) -``` - -As data is gathered into windows of time, each window is output as its own table. -When visualized, each table is assigned a unique color. - -![Windowed data tables](/img/flux/windowed-data.png) - -## Aggregate windowed data -Flux aggregate functions take the `_value`s in each table and aggregate them in some way. -Use the [`mean()` function](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/mean) to average the `_value`s of each table. - -```js -from(bucket:"example-bucket") - |> range(start: -1h) - |> filter(fn: (r) => - r._measurement == "cpu" and - r._field == "usage_system" and - r.cpu == "cpu-total" - ) - |> window(every: 5m) - |> mean() -``` - -As rows in each window are aggregated, their output table contains only a single row with the aggregate value. -Windowed tables are all still separate and, when visualized, will appear as single, unconnected points. - -![Windowed aggregate data](/img/flux/windowed-aggregates.png) - -## Add times to your aggregates -As values are aggregated, the resulting tables do not have a `_time` column because -the records used for the aggregation all have different timestamps. -Aggregate functions don't infer what time should be used for the aggregate value. -Therefore the `_time` column is dropped. - -A `_time` column is required in the [next operation](#unwindow-aggregate-tables). -To add one, use the [`duplicate()` function](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/duplicate) -to duplicate the `_stop` column as the `_time` column for each windowed table. - -```js -from(bucket:"example-bucket") - |> range(start: -1h) - |> filter(fn: (r) => - r._measurement == "cpu" and - r._field == "usage_system" and - r.cpu == "cpu-total" - ) - |> window(every: 5m) - |> mean() - |> duplicate(column: "_stop", as: "_time") -``` - -## Unwindow aggregate tables - -Use the `window()` function with the `every: inf` parameter to gather all points -into a single, infinite window. - -```js -from(bucket:"example-bucket") - |> range(start: -1h) - |> filter(fn: (r) => - r._measurement == "cpu" and - r._field == "usage_system" and - r.cpu == "cpu-total" - ) - |> window(every: 5m) - |> mean() - |> duplicate(column: "_stop", as: "_time") - |> window(every: inf) -``` - -Once ungrouped and combined into a single table, the aggregate data points will appear connected in your visualization. - -![Unwindowed aggregate data](/img/flux/windowed-aggregates-ungrouped.png) - -## Helper functions -This may seem like a lot of coding just to build a query that aggregates data, however going through the -process helps to understand how data changes "shape" as it is passed through each function. - -Flux provides (and allows you to create) "helper" functions that abstract many of these steps. -The same operation performed in this guide can be accomplished using the -[`aggregateWindow()` function](/influxdb/cloud/reference/flux/stdlib/built-in/transformations/aggregates/aggregatewindow). - -```js -from(bucket:"example-bucket") - |> range(start: -1h) - |> filter(fn: (r) => - r._measurement == "cpu" and - r._field == "usage_system" and - r.cpu == "cpu-total" - ) - |> aggregateWindow(every: 5m, fn: mean) -``` - -## Congratulations! -You have now constructed a Flux query that uses Flux functions to transform your data. -There are many more ways to manipulate your data using both Flux's primitive functions -and your own custom functions, but this is a good introduction into the basic syntax and query structure. - ---- - -_For a deeper dive into windowing and aggregating data with example data output for each transformation, -view the [Window and aggregate data](/influxdb/cloud/query-data/flux/window-aggregate) guide._ - ---- - - +{{< duplicate-oss >}} \ No newline at end of file diff --git a/content/influxdb/cloud/reference/flux/language/expressions.md b/content/influxdb/cloud/reference/flux/language/expressions.md index ad37dae08..eef410de3 100644 --- a/content/influxdb/cloud/reference/flux/language/expressions.md +++ b/content/influxdb/cloud/reference/flux/language/expressions.md @@ -8,271 +8,4 @@ menu: weight: 204 --- -An _expression_ specifies the computation of a value by applying the operators and functions to operands. - -## Operands and primary expressions - -Operands denote the elementary values in an expression. - -Primary expressions are the operands for unary and binary expressions. -A primary expressions may be a literal, an identifier denoting a variable, or a parenthesized expression. - -```js -PrimaryExpression = identifier | Literal | "(" Expression ")" . -``` - -## Literals - -Literals construct a value. - -```js -Literal = int_lit - | float_lit - | string_lit - | regex_lit - | duration_lit - | date_time_lit - | pipe_receive_lit - | RecordLiteral - | ArrayLiteral - | FunctionLiteral . -``` - -### Record literals - -Record literals construct a value with the record type. - -```js -RecordLiteral = "{" RecordBody "}" . -RecordBody = WithProperties | PropertyList . -WithProperties = identifier "with" PropertyList . -PropertyList = [ Property { "," Property } ] . -Property = identifier [ ":" Expression ] - | string_lit ":" Expression . -``` - -**Examples** -```js -{a: 1, b: 2, c: 3} -{a, b, c} -{o with x: 5, y: 5} -{o with a, b} -``` - -### Array literals - -Array literals construct a value with the array type. - -```js -ArrayLiteral = "[" ExpressionList "]" . -ExpressionList = [ Expression { "," Expression } ] . -``` - -### Function literals - -A _function literal_ defines a new function with a body and parameters. -The function body may be a block or a single expression. -The function body must have a return statement if it is an explicit block, otherwise the expression is the return value. - -```js -FunctionLiteral = FunctionParameters "=>" FunctionBody . -FunctionParameters = "(" [ ParameterList [ "," ] ] ")" . -ParameterList = Parameter { "," Parameter } . -Parameter = identifier [ "=" Expression ] . -FunctionBody = Expression | Block . -``` - -##### Examples of function literals - -```js -() => 1 // function returns the value 1 -(a, b) => a + b // function returns the sum of a and b -(x=1, y=1) => x * y // function with default values -(a, b, c) => { // function with a block body - d = a + b - return d / c -} - -``` -All function literals are anonymous. -A function may be given a name using a variable assignment. - -``` -add = (a,b) => a + b -mul = (a,b) => a * b -``` - -Function literals are _closures_ and may refer to variables defined in a surrounding block. -Those variables are shared between the function literal and the surrounding block. - -## Call expressions - -A _call expression_ invokes a function with the provided arguments. -Arguments must be specified using the argument name. -Positional arguments are not supported. -Argument order does not matter. -When an argument has a default value, it is not required to be specified. - -```js -CallExpression = "(" PropertyList ")" . -``` - -##### Examples of call expressions - -```js -f(a:1, b:9.6) -float(v:1) -``` - -Use short notation in a call expression when the name of every argument matches the name of every parameter. - -##### Examples of short notation in call expressions - -```js -add(a: a, b: b) //long notation -add(a, b) // short notation equivalent - -add = (a,b) => a + b -a = 1 -b = 2 - -// Don't mix short and long notation. -add(a: a, b) -add(a, b: b) -``` - -## Pipe expressions - -A _pipe expression_ is a call expression with an implicit piped argument. -Pipe expressions simplify creating long nested call chains. - -Pipe expressions pass the result of the left hand expression as the _pipe argument_ to the right hand call expression. -Function literals specify which if any argument is the pipe argument using the _pipe literal_ as the argument's default value. -It is an error to use a pipe expression if the function does not declare a pipe argument. - -```js -pipe_receive_lit = "<-" . -``` - -##### Examples of pipe expressions - -```js -foo = () => // function body elided -bar = (x=<-) => // function body elided -baz = (y=<-) => // function body elided -foo() |> bar() |> baz() // equivalent to baz(x:bar(y:foo())) -``` - -## Index expressions -Index expressions access a value from an array based on a numeric index. - -```js -IndexExpression = "[" Expression "]" . -``` - -## Member expressions -Member expressions access a property of a record. -They are specified using an expression in one of the following forms: - -```js -rec.k -// or -rec["k"] -``` - -The property being accessed must be either an identifier or a string literal. -In either case the literal value is the name of the property being accessed, the identifier is not evaluated. -It is not possible to access a record's property using an arbitrary expression. - -If `rec` contains an entry with property `k`, both `rec.k` and `rec["k"]` return the value associated with `k`. -If `rec` does **not** contain an entry with property `k`, both `rec.k` and `rec["k"]` return _null_. - -```js -MemberExpression = DotExpression | MemberBracketExpression . -DotExpression = "." identifier . -MemberBracketExpression = "[" string_lit "]" . -``` - -## Conditional expressions -Conditional expressions evaluate a boolean-valued condition. -If the result is _true_, the expression that follows the `then` keyword is evaluated and returned. -If the result is _false_, the expression that follows the `else` keyword is evaluated and returned. -In either case, only the branch taken is evaluated and only side effects associated this branch will occur. - -```js -ConditionalExpression = "if" Expression "then" Expression "else" Expression . -``` - -##### Conditional expression example -```js -color = if code == 0 then "green" else if code == 1 then "yellow" else "red" -``` - -{{% note %}} -According to the definition above, if a condition evaluates to a _null_ or unknown value, -the _else_ branch is evaluated. -{{% /note %}} - -## Operators -Operators combine operands into expressions. -The precedence of the operators is given in the table below. -Operators with a lower number have higher precedence. - -| Precedence | Operator | Description | -|:----------:|:--------: |:-------------------------- | -| 1 | `a()` | Function call | -| | `a[]` | Member or index access | -| | `.` | Member access | -| 2 | \|> | Pipe forward | -| 3 | `^` | Exponentiation | -| 4 | `*` `/` `%` | Multiplication, division, and modulo | -| 5 | `+` `-` | Addition and subtraction | -| 6 |`==` `!=` | Comparison operators | -| | `<` `<=` | | -| | `>` `>=` | | -| |`=~` `!~` | | -| 7 | `not` | Unary logical operator | -| | `exists` | Null check operator | -| 8 | `and` | Logical AND | -| 9 | `or` | Logical OR | -| 10 | `if` `then` `else` | Conditional | - -The operator precedence is encoded directly into the grammar as the following. - -```js -Expression = ConditionalExpression . -ConditionalExpression = LogicalExpression - | "if" Expression "then" Expression "else" Expression . -LogicalExpression = UnaryLogicalExpression - | LogicalExpression LogicalOperator UnaryLogicalExpression . -LogicalOperator = "and" | "or" . -UnaryLogicalExpression = ComparisonExpression - | UnaryLogicalOperator UnaryLogicalExpression . -UnaryLogicalOperator = "not" | "exists" . -ComparisonExpression = AdditiveExpression - | ComparisonExpression ComparisonOperator AdditiveExpression . -ComparisonOperator = "==" | "!=" | "<" | "<=" | ">" | ">=" | "=~" | "!~" . -AdditiveExpression = MultiplicativeExpression - | AdditiveExpression AdditiveOperator MultiplicativeExpression . -AdditiveOperator = "+" | "-" . -MultiplicativeExpression = PipeExpression - | MultiplicativeExpression MultiplicativeOperator PipeExpression . -MultiplicativeOperator = "*" | "/" | "%" | "^" . -PipeExpression = PostfixExpression - | PipeExpression PipeOperator UnaryExpression . -PipeOperator = "|>" . -UnaryExpression = PostfixExpression - | PrefixOperator UnaryExpression . -PrefixOperator = "+" | "-" . -PostfixExpression = PrimaryExpression - | PostfixExpression PostfixOperator . -PostfixOperator = MemberExpression - | CallExpression - | IndexExpression . -``` - -{{% warn %}} -Dividing by 0 or using the mod operator with a divisor of 0 will result in an error. -{{% /warn %}} - -_Also see [Flux Operators](/influxdb/cloud/reference/flux/language/operators)._ +{{< duplicate-oss >}} \ No newline at end of file diff --git a/content/influxdb/cloud/reference/flux/language/types.md b/content/influxdb/cloud/reference/flux/language/types.md index d492eaf80..e2e05391f 100644 --- a/content/influxdb/cloud/reference/flux/language/types.md +++ b/content/influxdb/cloud/reference/flux/language/types.md @@ -8,272 +8,4 @@ menu: weight: 213 --- -{{% note %}} -This document is a living document and may not represent the current implementation of Flux. -Any section that is not currently implemented is commented with a **[IMPL#XXX]** where -**XXX** is an issue number tracking discussion and progress towards implementation. -{{% /note %}} - -A **type** defines the set of values and operations on those values. -Types are never explicitly declared as part of the syntax except as part of a [builtin statement](/influxdb/cloud/reference/flux/language/system-built-ins/). -Types are always inferred from the usage of the value. -Type inference follows a Hindley-Milner style inference system. - -## Union types -A union type defines a set of types. -In the examples below, a union type is specified as follows: - -```js -T = t1 | t2 | ... | tn -``` - -where `t1`, `t2`, ..., and `tn` are types. - -In the example above a value of type `T` is either of type `t1`, type `t2`, ..., or type `tn`. - -## Basic types -All Flux data types are constructed from the following types: - -### Null types -The **null type** represents a missing or unknown value. -The **null type** name is `null`. -There is only one value that comprises the _null type_ and that is the _null_ value. -A type `t` is nullable if it can be expressed as follows: - -```js -t = {s} | null -``` - -where `{s}` defines a set of values. - -### Boolean types -A _boolean type_ represents a truth value, corresponding to the preassigned variables `true` and `false`. -The boolean type name is `bool`. -The boolean type is nullable and can be formally specified as follows: - -```js -bool = {true, false} | null -``` - -### Numeric types -A _numeric type_ represents sets of integer or floating-point values. - -The following numeric types exist: - -``` -uint the set of all unsigned 64-bit integers | null -int the set of all signed 64-bit integers | null -float the set of all IEEE-754 64-bit floating-point numbers | null -``` - -{{% note %}} -All numeric types are nullable. -{{% /note %}} - -### Time types -A _time type_ represents a single point in time with nanosecond precision. -The time type name is `time`. -The time type is nullable. - -#### Timestamp format -Flux supports [RFC3339 timestamps](/influxdb/cloud/reference/glossary/#rfc3339-timestamp): - -- `YYYY-MM-DD` -- `YYYY-MM-DDT00:00:00Z` -- `YYYY-MM-DDT00:00:00.000Z` - -### Duration types -A _duration type_ represents a length of time with nanosecond precision. -The duration type name is `duration`. -The duration type is nullable - -Durations can be added to times to produce a new time. - -##### Examples of duration types -```js -1ns // 1 nanosecond -1us // 1 microsecond -1ms // 1 millisecond -1s // 1 second -1m // 1 minute -1h // 1 hour -1d // 1 day -1w // 1 week -1mo // 1 calendar month -1y // 1 calendar year - -3d12h4m25s // 3 days, 12 hours, 4 minutes, and 25 seconds -``` - -### String types -A _string type_ represents a possibly empty sequence of characters. -Strings are immutable and cannot be modified once created. -The string type name is `string`. -The string type is nullable. - -{{% note %}} -An empty string is **not** a _null_ value. -{{% /note %}} - -The length of a string is its size in bytes, not the number of characters, -since a single character may be multiple bytes. - -### Bytes types -A _bytes type_ represents a sequence of byte values. -The bytes type name is `bytes`. - -## Regular expression types -A _regular expression type_ represents the set of all patterns for regular expressions. -The regular expression type name is `regexp`. -The regular expression type is **not** nullable. - -## Composite types -These are types constructed from basic types. -Composite types are not nullable. - -### Array types -An _array type_ represents a sequence of values of any other type. -All values in the array must be of the same type. -The length of an array is the number of elements in the array. - -### Record types -A _record type_ represents a set of unordered key and value pairs. -The key must always be a string. -The value may be any other type, and need not be the same as other values within the record. - -Keys in a record may only be referenced statically. - -Type inference determines the properties that are present in a record. -If type inference determines all the properties in a record, it is said to be "bounded." -Not all keys may be known in the type of a record, in which case the record is said to be "unbounded." -An unbounded record may contain any property in addition to the properties it is known to contain. - -### Function types -A _function type_ represents a set of all functions with the same argument and result types. - -{{% note %}} -[IMPL#249](https://github.com/influxdata/platform/issues/249) Specify type inference rules. -{{% /note %}} - -### Generator types -A _generator type_ represents a value that produces an unknown number of other values. -The generated values may be of any other type, but must all be the same type. - -{{% note %}} -[IMPL#658](https://github.com/influxdata/platform/query/issues/658) Implement Generators types. -{{% /note %}} - -## Polymorphism -Flux functions can be polymorphic, meaning a function can be applied to arguments of different types. -Flux supports parametric, record, and ad hoc polymorphism. - -### Parametric polymorphism -Parametric polymorphism is the notion that a function can be applied uniformly to arguments of any type. -For example: - -```js -f = (x) => x -f(x: 1) -f(x: 1.1) -f(x: "1") -f(x: true) -f(x: f) -``` - -The identifiers, `a` and `b`, in the body of the `add` function are used as both `int` and `float` types. - -### Record polymorphism -Record polymorphism is the notion that a function can be applied to different types of records. -For example: - -```js -john = {name:"John", lastName:"Smith"} -jane = {name:"Jane", age:44} - -// John and Jane are records with different types. -// We can still define a function that can operate on both records safely. - -// name returns the name of a person -name = (person) => person.name - -name(person:john) // John -name(person:jane) // Jane - -device = {id: 125325, lat: 15.6163, lon: 62.6623} - -name(person:device) // Type error, "device" does not have a property name. -``` - -Records of differing types can be passed to the same function as long as they contain the necessary properties. -The necessary properties are determined by the use of the record. - -### Ad hoc polymorphism -Ad hoc polymorphism is the notion that a function can be applied to arguments of -different types with different behavior depending on the type. - -```js -add = (a, b) => a + b - -// Integer addition -add(a: 1, b: 1) - -// String concatenation -add(a: "str", b: "ing") - -// Addition not defined for boolean data types -add(a: true, b: false) -``` - -## Type constraints -Type constraints are to implement static ad hoc polymorphism. -For example, the following function is defined only for `Addable` types: - -```js -add = (a, b) => a + b -``` - -Passing a record to `add()` results in compile-time type error because records are not addable. - -```js -// Records are not Addable and will result in an error. -add(a: {}, b: {}) -``` - -Constraints are never explicitly declared but rather inferred from the context. - -### Addable constraint -Addable types are those the binary arithmetic operator `+` accepts. -Integer, Uinteger, Float, and String types are `Addable`. - -### Subtractable constraint -Subtractable types are those the binary arithmetic operator `-` accepts. -Integer, Uinteger, and Float types are `Subtractable`. - -### Divisible constraint -Divisible types are those the binary arithmetic operator `\` accepts. -Integer, Uinteger, and Float types are `Divisible`. - -### Numeric Constraint -Integer, Uinteger, and Float types are `Numeric`. - -### Comparable Constraint -Comparable types are those the binary comparison operators `<`, `<=`, `>`, or `>=` accept. -Integer, Uinteger, Float, String, Duration, and Time types are `Comparable`. - -### Equatable Constraint -Equatable types are those that can be compared for equality using the `==` or `!=` operators. -Boolean, Integer, Uinteger, Float, String, Duration, Time, Bytes, Array, and Record types are `Equatable`. - -### Nullable Constraint -Nullable types are those that can be _null_. -Boolean, Integer, Uinteger, Float, String, Duration, and Time types are `Nullable`. - -### Record Constraint -Records are the only types that fall under this constraint. - -### Negatable Constraint -Negatable types ore those the unary arithmetic operator `-` accepts. -Integer, Uinteger, Float, and Duration types are `Negatable`. - -### Timeable Constraint -Duration and Time types are `Timeable`. +{{< duplicate-oss >}} \ No newline at end of file diff --git a/content/influxdb/v2.0/query-data/get-started/query-influxdb.md b/content/influxdb/v2.0/query-data/get-started/query-influxdb.md index 43ce1d635..9d7293e9e 100644 --- a/content/influxdb/v2.0/query-data/get-started/query-influxdb.md +++ b/content/influxdb/v2.0/query-data/get-started/query-influxdb.md @@ -132,6 +132,6 @@ Flux queries can be extended in many ways to form powerful scripts. diff --git a/content/influxdb/v2.0/query-data/get-started/syntax-basics.md b/content/influxdb/v2.0/query-data/get-started/syntax-basics.md index 29023de44..582b61ab1 100644 --- a/content/influxdb/v2.0/query-data/get-started/syntax-basics.md +++ b/content/influxdb/v2.0/query-data/get-started/syntax-basics.md @@ -58,7 +58,9 @@ this is a string ``` ### Records -Flux also supports records. Each value in a record can be a different data type. +Flux also supports records, collections of key-value pairs. +Each key must be a string. +Values can be a different data types. ```js > o = {name:"Jim", age: 42, "favorite color": "red"} @@ -99,6 +101,31 @@ Flux supports arrays. All values in an array must be the same type. [1, 2, 3, 4] ``` +Use **bracket notation** to access a value at a specific index in an array: + +```js +> a = ["foo","bar","baz","quz"] +> a[0] +foo +``` + +### Dictionaries +Flux supports dictionaries, collections of key value pairs where keys can be any type, +but all keys must be the same type. +All values in a dictionary must be the same type. + +```js +> d = [1: "foo", 2: "bar"] +``` + +Use the `dict.get()` function to access properties in a dictionary: + +```js +> import "dict" +> dict.get(dict: d, key: "1", default: "") +foo +``` + ### Functions Flux uses functions for most of its heavy lifting. Below is a simple function that squares a number, `n`. @@ -232,5 +259,5 @@ This query will return the five data points with the highest user CPU usage over _More information about creating custom functions is available in the [Custom functions](/influxdb/v2.0/query-data/flux/custom-functions) documentation._ diff --git a/content/influxdb/v2.0/query-data/get-started/transform-data.md b/content/influxdb/v2.0/query-data/get-started/transform-data.md index c9b0dcbd3..f3b18bfce 100644 --- a/content/influxdb/v2.0/query-data/get-started/transform-data.md +++ b/content/influxdb/v2.0/query-data/get-started/transform-data.md @@ -182,6 +182,6 @@ view the [Window and aggregate data](/influxdb/v2.0/query-data/flux/window-aggre --- diff --git a/content/influxdb/v2.0/reference/flux/language/expressions.md b/content/influxdb/v2.0/reference/flux/language/expressions.md index b589e9d12..e16e084d1 100644 --- a/content/influxdb/v2.0/reference/flux/language/expressions.md +++ b/content/influxdb/v2.0/reference/flux/language/expressions.md @@ -35,6 +35,7 @@ Literal = int_lit | pipe_receive_lit | RecordLiteral | ArrayLiteral + | DictLiteral | FunctionLiteral . ``` @@ -68,6 +69,28 @@ ArrayLiteral = "[" ExpressionList "]" . ExpressionList = [ Expression { "," Expression } ] . ``` +### Dictionary literals + +Dictionary literals construct a value with the dict type. + +```js +DictLiteral = EmptyDict | "[" AssociativeList "]" . +EmptyDict = "[" ":" "]" . +AssociativeList = Association { "," AssociativeList } . +Association = Expression ":" Expression . +``` + +Keys can be arbitrary expressions. +The type system enforces that all keys are of the same type. + +**Examples** +```js +a = "a" +b = [:] // empty dictionary +c = [a: 1, "b": 2] // dictionary mapping string values to integers +d = [a: 1, 2: 3] // type error: cannot mix string and integer keys +``` + ### Function literals A _function literal_ defines a new function with a body and parameters. diff --git a/content/influxdb/v2.0/reference/flux/language/types.md b/content/influxdb/v2.0/reference/flux/language/types.md index f442334fa..f3cef4bcd 100644 --- a/content/influxdb/v2.0/reference/flux/language/types.md +++ b/content/influxdb/v2.0/reference/flux/language/types.md @@ -148,19 +148,20 @@ If type inference determines all the properties in a record, it is said to be "b Not all keys may be known in the type of a record, in which case the record is said to be "unbounded." An unbounded record may contain any property in addition to the properties it is known to contain. +### Dictionary types +A _dictionary type_ is a collection that associates keys to values. +Keys must be comparable and of the same type. +Values must also be of the same type. + ### Function types A _function type_ represents a set of all functions with the same argument and result types. -{{% note %}} -[IMPL#249](https://github.com/influxdata/platform/issues/249) Specify type inference rules. -{{% /note %}} - ### Generator types A _generator type_ represents a value that produces an unknown number of other values. The generated values may be of any other type, but must all be the same type. {{% note %}} -[IMPL#658](https://github.com/influxdata/platform/query/issues/658) Implement Generators types. +[IMPL#412](https://github.com/influxdata/flux/issues/412) Implement Generators types. {{% /note %}} ## Polymorphism From 194aed989ca40294feceb283328cd58c3d7f5ff0 Mon Sep 17 00:00:00 2001 From: Scott Anderson Date: Fri, 11 Dec 2020 14:45:13 -0700 Subject: [PATCH 2/7] added the dict package --- .../reference/flux/stdlib/dict/_index.md | 15 ++++ .../reference/flux/stdlib/dict/fromlist.md | 13 +++ .../cloud/reference/flux/stdlib/dict/get.md | 13 +++ .../reference/flux/stdlib/dict/insert.md | 14 +++ .../reference/flux/stdlib/dict/remove.md | 13 +++ .../v2.0/reference/flux/stdlib/dict/_index.md | 22 +++++ .../reference/flux/stdlib/dict/fromlist.md | 48 +++++++++++ .../v2.0/reference/flux/stdlib/dict/get.md | 62 ++++++++++++++ .../v2.0/reference/flux/stdlib/dict/insert.md | 85 +++++++++++++++++++ .../v2.0/reference/flux/stdlib/dict/remove.md | 59 +++++++++++++ 10 files changed, 344 insertions(+) create mode 100644 content/influxdb/cloud/reference/flux/stdlib/dict/_index.md create mode 100644 content/influxdb/cloud/reference/flux/stdlib/dict/fromlist.md create mode 100644 content/influxdb/cloud/reference/flux/stdlib/dict/get.md create mode 100644 content/influxdb/cloud/reference/flux/stdlib/dict/insert.md create mode 100644 content/influxdb/cloud/reference/flux/stdlib/dict/remove.md create mode 100644 content/influxdb/v2.0/reference/flux/stdlib/dict/_index.md create mode 100644 content/influxdb/v2.0/reference/flux/stdlib/dict/fromlist.md create mode 100644 content/influxdb/v2.0/reference/flux/stdlib/dict/get.md create mode 100644 content/influxdb/v2.0/reference/flux/stdlib/dict/insert.md create mode 100644 content/influxdb/v2.0/reference/flux/stdlib/dict/remove.md diff --git a/content/influxdb/cloud/reference/flux/stdlib/dict/_index.md b/content/influxdb/cloud/reference/flux/stdlib/dict/_index.md new file mode 100644 index 000000000..9cfe4e55c --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/dict/_index.md @@ -0,0 +1,15 @@ +--- +title: Flux Dictionary package +list_title: Dictionary package +description: > + The Flux dictionary package provides functions for interacting with dictionary types. + Import the `dict` package. +menu: + influxdb_cloud_ref: + name: Dictionary + parent: Flux standard library +weight: 202 +influxdb/v2.0/tags: [package, functions] +--- + +{{< duplicate-oss >}} \ No newline at end of file diff --git a/content/influxdb/cloud/reference/flux/stdlib/dict/fromlist.md b/content/influxdb/cloud/reference/flux/stdlib/dict/fromlist.md new file mode 100644 index 000000000..e31b9a6aa --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/dict/fromlist.md @@ -0,0 +1,13 @@ +--- +title: dict.fromList() function +description: > + The `dict.fromList()` function creates a dictionary from a list of records with + `key` and `value` properties. +menu: + influxdb_cloud_ref: + name: dict.fromList + parent: Dictionary +weight: 301 +--- + +{{< duplicate-oss >}} \ No newline at end of file diff --git a/content/influxdb/cloud/reference/flux/stdlib/dict/get.md b/content/influxdb/cloud/reference/flux/stdlib/dict/get.md new file mode 100644 index 000000000..2d3c306e3 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/dict/get.md @@ -0,0 +1,13 @@ +--- +title: dict.get() function +description: > + The `dict.get()` function returns the value of a specified key in a dictionary + or a default value if the key does not exist. +menu: + influxdb_cloud_ref: + name: dict.get + parent: Dictionary +weight: 301 +--- + +{{< duplicate-oss >}} \ No newline at end of file diff --git a/content/influxdb/cloud/reference/flux/stdlib/dict/insert.md b/content/influxdb/cloud/reference/flux/stdlib/dict/insert.md new file mode 100644 index 000000000..e25177cbd --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/dict/insert.md @@ -0,0 +1,14 @@ +--- +title: dict.insert() function +description: > + The `dict.insert()` function inserts a key value pair into a dictionary and + returns a new, updated dictionary. + If the key already exists in the dictionary, the function overwrites the existing value. +menu: + influxdb_cloud_ref: + name: dict.insert + parent: Dictionary +weight: 301 +--- + +{{< duplicate-oss >}} \ No newline at end of file diff --git a/content/influxdb/cloud/reference/flux/stdlib/dict/remove.md b/content/influxdb/cloud/reference/flux/stdlib/dict/remove.md new file mode 100644 index 000000000..97b0d0b69 --- /dev/null +++ b/content/influxdb/cloud/reference/flux/stdlib/dict/remove.md @@ -0,0 +1,13 @@ +--- +title: dict.remove() function +description: > + The `dict.remove()` function removes a key value pair from a dictionary and returns + and updated dictionary. +menu: + influxdb_cloud_ref: + name: dict.remove + parent: Dictionary +weight: 301 +--- + +{{< duplicate-oss >}} \ No newline at end of file diff --git a/content/influxdb/v2.0/reference/flux/stdlib/dict/_index.md b/content/influxdb/v2.0/reference/flux/stdlib/dict/_index.md new file mode 100644 index 000000000..92e3e2656 --- /dev/null +++ b/content/influxdb/v2.0/reference/flux/stdlib/dict/_index.md @@ -0,0 +1,22 @@ +--- +title: Flux Dictionary package +list_title: Dictionary package +description: > + The Flux dictionary package provides functions for interacting with dictionary types. + Import the `dict` package. +menu: + influxdb_2_0_ref: + name: Dictionary + parent: Flux standard library +weight: 202 +influxdb/v2.0/tags: [package, functions] +--- + +The Flux dictionary package provides functions for interacting with [dictionary types](/influxdb/v2.0/reference/flux/language/types/#dictionary-types). +Import the `dict` package. + +```js +import "dict" +``` + +{{< children type="functions" show="pages" >}} diff --git a/content/influxdb/v2.0/reference/flux/stdlib/dict/fromlist.md b/content/influxdb/v2.0/reference/flux/stdlib/dict/fromlist.md new file mode 100644 index 000000000..1c687891c --- /dev/null +++ b/content/influxdb/v2.0/reference/flux/stdlib/dict/fromlist.md @@ -0,0 +1,48 @@ +--- +title: dict.fromList() function +description: > + The `dict.fromList()` function creates a dictionary from a list of records with + `key` and `value` properties. +menu: + influxdb_2_0_ref: + name: dict.fromList + parent: Dictionary +weight: 301 +--- + +The `dict.fromList()` function creates a dictionary from a list of records with +`key` and `value` properties. + +```js +import "dict" + +dict.fromList( + pairs: [ + {key: 1, value: "foo"}, + {key: 2, value: "bar"} + ] +) +``` + +## Parameters + +### pairs +List of records, each containing `key` and `value` properties. + +_**Data type:** Array of records_ + +## Examples +```js +import "dict" + +d = dict.fromList( + pairs: [ + {key: 1, value: "foo"}, + {key: 2, value: "bar"} + ] +) + +dict.get(dict: d, key: 1, default: "") + +// Returns foo +```` \ No newline at end of file diff --git a/content/influxdb/v2.0/reference/flux/stdlib/dict/get.md b/content/influxdb/v2.0/reference/flux/stdlib/dict/get.md new file mode 100644 index 000000000..5d0714c69 --- /dev/null +++ b/content/influxdb/v2.0/reference/flux/stdlib/dict/get.md @@ -0,0 +1,62 @@ +--- +title: dict.get() function +description: > + The `dict.get()` function returns the value of a specified key in a dictionary + or a default value if the key does not exist. +menu: + influxdb_2_0_ref: + name: dict.get + parent: Dictionary +weight: 301 +--- + +The `dict.get()` function returns the value of a specified key in a dictionary +or a default value if the key does not exist. + +```js +import "dict" + +dict.get( + dict: [1: "foo", 2: "bar"], + key: 1, + default: "" +) +``` + +## Parameters + +

+ {{< req "All paremeters are required" >}} +

+ +### dict +Dictionary to return a value from. + +_**Data type:** Dictionary_ + +### key +Key to return from the dictionary. + +_**Data type:** String | Boolean | Integer | Uinteger | Float | Time | Bytes_ + +### default +Default value to return if the `key` does not exist in the dictionary. +Must be the same type as values in the dictionary. + +_**Data type:** String | Boolean | Integer | Uinteger | Float | Time | Bytes_ + +## Examples + +```js +import "dict" + +d = [1: "foo", 2: "bar"] + +dict.get( + dict: d, + key: 1, + default: "" +) + +// Returns foo +``` \ No newline at end of file diff --git a/content/influxdb/v2.0/reference/flux/stdlib/dict/insert.md b/content/influxdb/v2.0/reference/flux/stdlib/dict/insert.md new file mode 100644 index 000000000..7ec8f9aa9 --- /dev/null +++ b/content/influxdb/v2.0/reference/flux/stdlib/dict/insert.md @@ -0,0 +1,85 @@ +--- +title: dict.insert() function +description: > + The `dict.insert()` function inserts a key value pair into a dictionary and + returns a new, updated dictionary. + If the key already exists in the dictionary, the function overwrites the existing value. +menu: + influxdb_2_0_ref: + name: dict.insert + parent: Dictionary +weight: 301 +--- + +The `dict.insert()` function inserts a key value pair into a dictionary and returns +a new, updated dictionary. +If the key already exists in the dictionary, the function overwrites the existing value. + +```js +import "dict" + +dict.insert( + dict: [1: "foo", 2: "bar"], + key: 3, + value: "baz" +) +``` + +## Parameters + +

+ {{< req "All paremeters are required" >}} +

+ +### dict +Dictionary to update. + +_**Data type:** Dictionary_ + +### key +Key to insert into the dictionary. +Must be the same type as existing keys in the dictionary. + +_**Data type:** String | Boolean | Integer | Uinteger | Float | Time | Bytes_ + +### default +Value to insert into the dictionary. +Must be the same type as existing values in the dictionary. + +_**Data type:** String | Boolean | Integer | Uinteger | Float | Time | Bytes_ + +## Examples + +##### Insert a new key-value pair into a dictionary +```js +import "dict" + +d = [1: "foo", 2: "bar"] + +dNew = dict.insert( + dict: d, + key: 3, + value: "baz" +) + +dict.get(dict: dNew, key: 3, default: "") + +// Returns baz +``` + +##### Overwrite an existing key-value pair in a dictionary +```js +import "dict" + +d = [1: "foo", 2: "bar"] + +dNew = dict.insert( + dict: d, + key: 2, + value: "baz" +) + +dict.get(dict: dNew, key: 2, default: "") + +// Returns baz +``` \ No newline at end of file diff --git a/content/influxdb/v2.0/reference/flux/stdlib/dict/remove.md b/content/influxdb/v2.0/reference/flux/stdlib/dict/remove.md new file mode 100644 index 000000000..0330e993a --- /dev/null +++ b/content/influxdb/v2.0/reference/flux/stdlib/dict/remove.md @@ -0,0 +1,59 @@ +--- +title: dict.remove() function +description: > + The `dict.remove()` function removes a key value pair from a dictionary and returns + and updated dictionary. +menu: + influxdb_2_0_ref: + name: dict.remove + parent: Dictionary +weight: 301 +--- + +The `dict.remove()` function removes a key value pair from a dictionary and returns +and updated dictionary. + +```js +import "dict" + +dict.remove( + dict: [1: "foo", 2: "bar"], + key: 1 +) +``` + +## Parameters + +

+ {{< req "All paremeters are required" >}} +

+ +### dict +Dictionary to remove a key-value pair from. + +_**Data type:** Dictionary_ + +### key +Key to remove from the dictionary. +Must be the same type as existing keys in the dictionary. + +_**Data type:** String | Boolean | Integer | Uinteger | Float | Time | Bytes_ + +## Examples + +```js +import "dict" + +d = [1: "foo", 2: "bar"] + +dNew = dict.remove( + dict: d, + key: 1 +) + +dict.get(dict: dNew, key: 1, default: "") +// Returns an empty string + +dict.get(dict: dNew, key: 2, default: "") +// Returns bar +``` From f52e224188ffb94ec047e876cabc9113c710d0f8 Mon Sep 17 00:00:00 2001 From: Scott Anderson Date: Fri, 11 Dec 2020 14:49:40 -0700 Subject: [PATCH 3/7] added link to dict.get --- content/influxdb/v2.0/query-data/get-started/syntax-basics.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/content/influxdb/v2.0/query-data/get-started/syntax-basics.md b/content/influxdb/v2.0/query-data/get-started/syntax-basics.md index 582b61ab1..a2eb30b38 100644 --- a/content/influxdb/v2.0/query-data/get-started/syntax-basics.md +++ b/content/influxdb/v2.0/query-data/get-started/syntax-basics.md @@ -118,7 +118,8 @@ All values in a dictionary must be the same type. > d = [1: "foo", 2: "bar"] ``` -Use the `dict.get()` function to access properties in a dictionary: +Use the [`dict.get()` function](/influxdb/v2.0/reference/flux/stdlib/dict/get/) +to access properties in a dictionary: ```js > import "dict" From 440fafd813e65d29f5ee15d0610e95be900ded1a Mon Sep 17 00:00:00 2001 From: Scott Anderson Date: Tue, 15 Dec 2020 11:37:42 -0700 Subject: [PATCH 4/7] updated description of monitor.check data --- .../cloud/reference/flux/stdlib/monitor/check.md | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/content/influxdb/cloud/reference/flux/stdlib/monitor/check.md b/content/influxdb/cloud/reference/flux/stdlib/monitor/check.md index 4dd932c14..4402eba48 100644 --- a/content/influxdb/cloud/reference/flux/stdlib/monitor/check.md +++ b/content/influxdb/cloud/reference/flux/stdlib/monitor/check.md @@ -66,12 +66,22 @@ The message is stored in the `_message` column. _**Data type:** Function_ ### data -Meta data used to identify this check. - -**InfluxDB populates check data.** +Meta data used to identify this check and append tags to each row. _**Data type:** Record_ +The data record should contain the following fields: + +- **_check_id**: check ID +- **_check_name**: check name +- **_type**: check type (threshold, deadman, or custom) +- **tags**: tags to append to each checked record (for example: `{foo: "bar", baz: "quz"}`) + +The InfluxDB monitoring and alerting system uses `monitor.check()` to store information +about checks and automatically assigns the `_check_id` and `_check_name` values. +If writing a custom check task, we recommend using **unique arbitrary** values +for `_check_id` and `_check_name`. + ## Examples ### Monitor disk usage From 0be93ee4cdf404a1a3fce6ae6109d19ef093ad32 Mon Sep 17 00:00:00 2001 From: Scott Anderson Date: Tue, 15 Dec 2020 11:41:01 -0700 Subject: [PATCH 5/7] fixed typo in monitor.check --- content/influxdb/cloud/reference/flux/stdlib/monitor/check.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/influxdb/cloud/reference/flux/stdlib/monitor/check.md b/content/influxdb/cloud/reference/flux/stdlib/monitor/check.md index 4402eba48..c8874bc8e 100644 --- a/content/influxdb/cloud/reference/flux/stdlib/monitor/check.md +++ b/content/influxdb/cloud/reference/flux/stdlib/monitor/check.md @@ -66,7 +66,7 @@ The message is stored in the `_message` column. _**Data type:** Function_ ### data -Meta data used to identify this check and append tags to each row. +Metadata used to identify this check and append tags to each row. _**Data type:** Record_ From 15dc5e6a94eb272991412e295fd3bbaa82e1b42c Mon Sep 17 00:00:00 2001 From: Scott Anderson Date: Tue, 15 Dec 2020 21:26:26 -0700 Subject: [PATCH 6/7] updated dict docs to address PR feedback --- .../influxdb/v2.0/reference/flux/stdlib/dict/fromlist.md | 8 ++++++-- content/influxdb/v2.0/reference/flux/stdlib/dict/get.md | 1 + .../influxdb/v2.0/reference/flux/stdlib/dict/insert.md | 2 ++ .../influxdb/v2.0/reference/flux/stdlib/dict/remove.md | 7 +++++-- 4 files changed, 14 insertions(+), 4 deletions(-) diff --git a/content/influxdb/v2.0/reference/flux/stdlib/dict/fromlist.md b/content/influxdb/v2.0/reference/flux/stdlib/dict/fromlist.md index 1c687891c..aa0e6134c 100644 --- a/content/influxdb/v2.0/reference/flux/stdlib/dict/fromlist.md +++ b/content/influxdb/v2.0/reference/flux/stdlib/dict/fromlist.md @@ -27,14 +27,17 @@ dict.fromList( ## Parameters ### pairs -List of records, each containing `key` and `value` properties. +({{< req >}}) List of records, each containing `key` and `value` properties. _**Data type:** Array of records_ ## Examples + +##### Create a dictionary from a list of records ```js import "dict" +// Define a new dictionary using an array of records d = dict.fromList( pairs: [ {key: 1, value: "foo"}, @@ -42,7 +45,8 @@ d = dict.fromList( ] ) +// Return a property of the dictionary dict.get(dict: d, key: 1, default: "") // Returns foo -```` \ No newline at end of file +``` \ No newline at end of file diff --git a/content/influxdb/v2.0/reference/flux/stdlib/dict/get.md b/content/influxdb/v2.0/reference/flux/stdlib/dict/get.md index 5d0714c69..98ecb9c3b 100644 --- a/content/influxdb/v2.0/reference/flux/stdlib/dict/get.md +++ b/content/influxdb/v2.0/reference/flux/stdlib/dict/get.md @@ -47,6 +47,7 @@ _**Data type:** String | Boolean | Integer | Uinteger | Float | Time | Bytes_ ## Examples +##### Return a property of a dictionary ```js import "dict" diff --git a/content/influxdb/v2.0/reference/flux/stdlib/dict/insert.md b/content/influxdb/v2.0/reference/flux/stdlib/dict/insert.md index 7ec8f9aa9..32c50e475 100644 --- a/content/influxdb/v2.0/reference/flux/stdlib/dict/insert.md +++ b/content/influxdb/v2.0/reference/flux/stdlib/dict/insert.md @@ -62,6 +62,7 @@ dNew = dict.insert( value: "baz" ) +// Verify the new key-value pair was inserted dict.get(dict: dNew, key: 3, default: "") // Returns baz @@ -79,6 +80,7 @@ dNew = dict.insert( value: "baz" ) +// Verify the new key-value pair was overwritten dict.get(dict: dNew, key: 2, default: "") // Returns baz diff --git a/content/influxdb/v2.0/reference/flux/stdlib/dict/remove.md b/content/influxdb/v2.0/reference/flux/stdlib/dict/remove.md index 0330e993a..471705081 100644 --- a/content/influxdb/v2.0/reference/flux/stdlib/dict/remove.md +++ b/content/influxdb/v2.0/reference/flux/stdlib/dict/remove.md @@ -2,7 +2,7 @@ title: dict.remove() function description: > The `dict.remove()` function removes a key value pair from a dictionary and returns - and updated dictionary. + an updated dictionary. menu: influxdb_2_0_ref: name: dict.remove @@ -11,7 +11,7 @@ weight: 301 --- The `dict.remove()` function removes a key value pair from a dictionary and returns -and updated dictionary. +an updated dictionary. ```js import "dict" @@ -41,6 +41,7 @@ _**Data type:** String | Boolean | Integer | Uinteger | Float | Time | Bytes_ ## Examples +##### Remove a property from a dictionary ```js import "dict" @@ -51,6 +52,8 @@ dNew = dict.remove( key: 1 ) +// Verify the key-value pairs was removed + dict.get(dict: dNew, key: 1, default: "") // Returns an empty string From 7e64ab6fd0c4f22febbf659ad8b6c295f8afeebf Mon Sep 17 00:00:00 2001 From: Scott Anderson Date: Tue, 15 Dec 2020 21:48:43 -0700 Subject: [PATCH 7/7] added flux 0.99.0 release notes --- .../v2.0/reference/release-notes/flux.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/content/influxdb/v2.0/reference/release-notes/flux.md b/content/influxdb/v2.0/reference/release-notes/flux.md index 77e6a6b4f..a42b6e400 100644 --- a/content/influxdb/v2.0/reference/release-notes/flux.md +++ b/content/influxdb/v2.0/reference/release-notes/flux.md @@ -8,6 +8,23 @@ menu: name: Flux --- +## v0.99.0 [2020-12-14] + +### Features +- Evaluate [dictionary literals](/influxdb/v2.0/reference/flux/language/expressions/#dictionary-literals). +- Infer the type of dictionary literals. +- Parse and format dictionary literals. +- Add a pure Flux test runner. + +### Bug fixes +- Ensure `csv.from()` only returns one result. +- Change `extern` parsing code to return a more descriptive error message. +- Do not allow containers within a record to be null. +- Retrieve `now` option before running a Flux script. +- Fix misspellings in the [Flux README](https://github.com/influxdata/flux/blob/master/README.md). + +--- + ## v0.98.0 [2020-12-07] ### Features