TL;DR InfluxDB Tech Tips: Functions in InfluxDB v2

If you’re familiar with InfluxDB v2, then you’re probably familiar with Flux already. Flux enables you to transform your data in any way you need and write custom tasks, checks, and notification rules. But what you might not know is that InfluxDB Cloud v2 now supports named functions in Flux. Named functions are parameterized queries that are hosted and invoked by the InfluxDB Cloud server so that application developers can add custom functionality to their time series solution without having to introduce query resources into their client-side services and code. By supporting runtime parameters, it is possible to generalize these functions so that custom results may be returned for each user. Named functions can only be used with the InfluxDB v2 API right now, but will be landing in the InfluxDB User Interface soon.

Creating your first Flux named function in InfluxDB v2

You can create a function and an associated function resource with the InfluxDB v2 API. An associated function resource contains the following: name, id, description, orgID, script, language, url, createdAt, and updatedAt. These features help the developer identify their named function and its associated metadata. The function id is used to manually invoke the function upon request.

To create a function with an associated function resource, use the api/v2/functions endpoint. In this example, our parameterized query returns the last two data points from the bucket of our choice.

curl -X 'POST' \
  'https://us-west-2-1.aws.cloud2.influxdata.com/api/v2/functions' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "myFirstNamedFunc",
  "description": "a named function that gathers the last point from a bucket",
  "orgID": “<myOrgID>”,
  "script": "from(bucket:params.mybucket) \
|> range(start: -7d) \
|> limit(n:2)",
  "language": "flux"
}'

The function id is returned in the body of the response when you create a function. Alternatively, you can also retrieve the function id and all the other associated function resources by listing the function. Then you can use list the function with:

curl -X 'GET' \
  'https://us-west-2-1.aws.cloud2.influxdata.com/api/v2/functions?orgID=<myOrgID>' \
  -H 'accept: application/json'

Invoking a named Flux function with parameterized queries in InfluxDB v2

Once you have the function id, you can manually invoke the function and supply the parameters. In this case, we’ll supply the bucket name to the mybucket parameter. Our request looks like this:

curl -X 'POST' \
  'https://us-west-2-1.aws.cloud2.influxdata.com/api/v2/functions/<functionID>/invoke' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "params": {“telegraf”}
}'

Final thoughts on Named Flux Functions with InfluxDB

I hope this InfluxDB Tech Tips post inspires you to take advantage of named Flux functions with InfluxDB v2. If you’re new to parameterized queries, please make sure to take a look at TL;DR InfluxDB Tech Tips: Parameterized Flux Queries with InfluxDB. If you are using Flux and need help, please ask for some in our community site or Slack channel. If you’re developing a cool IoT application on top of InfluxDB, we’d love to hear about it, so make sure to share your story! Additionally, please share your thoughts, concerns, or questions in the comments section. We’d love to get your feedback and help you with any problems you run into!