Schema Queries in Flux (formerly IFQL)

By Stuart Carnie / Use Cases, Developer, Product
May 31, 2018

Navigate to:

InfluxQL facilitates schema exploration via a number of meta queries, which include SHOW MEASUREMENTS, SHOW TAG KEYS, SHOW TAG VALUES and SHOW FIELD KEYS. Flux (formerly IFQL) has united these concepts, such that schema is made up of tags keys and values. This unification provides greater flexibility with which a user may explore a schema, as we will show in the remainder of this post.

InfluxQL ? Flux (formerly IFQL)

This section demonstrates translations of InfluxQL meta queries to their Flux equivalents.

SHOW MEASUREMENTS

Measurement names are aggregated within the _measurement tag key. Therefore, we want to ask Flux to give us the distinct values for _measurement.

from(db:"foo")
  |> range(start:-24h)
  |> group(by:["_measurement"])
  |> distinct(column:"_measurement")
  |> group(none:true)

Typing this all the time may become tedious, so we can write a helper function that queries a specified database for the last 24 hours as follows:

showMeasurements = (db) => from(db:db) 
  |> range(start:-24h)
  |> group(by:["_measurement"])
  |> distinct(column:"_measurement")
  |> group(none:true)

Resulting in a greatly simplified query to show measurements:

showMeasurements(db:"foo")

We plan to formalize a number of helper functions for querying metadata in the near future.

InfluxQL meta queries cannot be restricted by time, so it is worth calling out the use of range to restrict the results to only those measurements with data in the last 24 hours.

SHOW TAG KEYS FROM cpu

List all the tag keys for the measurement cpu.

from(db:"foo")
    |> range(start:-24h)
    |> filter(fn:(r) => r._measurement == "cpu")
    |> keys()

SHOW TAG VALUES FROM cpu WITH KEY = "host"

List all the distinct values for a specific tag (host) in measurement cpu.

from(db:"foo")
    |> range(start:-24h)
    |> filter(fn:(r) => r._measurement == "cpu")
    |> group(by:["host"])
    |> distinct(column:"host")
    |> group(none:true)

SHOW FIELD KEYS FROM cpu

List all the fields for measurement cpu, which are aggregated under the _field tag key.

from(db:"foo")
    |> range(start:-24h)
    |> filter(fn:(r) => r._measurement == "cpu")
    |> group(by:["_field"])
    |> distinct(column:"_field")
    |> group(none:true)

The astute reader will notice this is the same query as 3., with the exception of using the _field tag key.

Exploring Schema

In this section, we walk through a series of queries a user might perform as they explore their schema.

1. Show the available tag keys

This query uses the keys function to list the distinct tag keys.

from(db:"foo")
    |> range(start:-1h)
    |> group(none:true)
    |> keys(except:["_time","_value","_start","_stop"])

Example Output:

_value:string
-------------
_field
_measurement
bank
dir
host
id
interface
tag0
tag1
tag2
tag3

2. Expand the host tag to see available values

This query groups the data by the host tag and outputs the distinct values for the host column.

from(db:"foo")
    |> range(start:-1h)
    |> group(by:["host"])
    |> distinct(column:"host")
    |> group(none:true)

Example Output:

_value:string
-------------
host2
host1

3. Expand host1 tag to see available keys

This query filters by host == "host1" and shows the subset of available keys.

from(db:"foo")
    |> range(start:-1h)
    |> filter(fn:(r) => r.host == "host1")
    |> group(none:true)
    |> keys(except:["_time","_value","_start","_stop", "host"]) // <- note host is added here, since we're already querying it

Example Output:

_value:string
-------------
_field
_measurement
bank
dir
id
interface