This is archived documentation for InfluxData product versions that are no longer maintained. For newer documentation, see the latest InfluxData documentation.
InfluxQL is an SQL-like query language for interacting with data in InfluxDB. The following sections cover useful query syntax for exploring your schema (that is, how you set up your time series data):
- See all databases with
SHOW DATABASES
- Explore retention policies with
SHOW RETENTION POLICIES
- Explore series with
SHOW SERIES
- Explore measurements with
SHOW MEASUREMENTS
- Explore tag keys with
SHOW TAG KEYS
- Explore tag values with
SHOW TAG VALUES
- Explore field keys with
SHOW FIELD KEYS
The examples below query data using InfluxDB’s Command Line Interface (CLI). See the Querying Data guide for how to directly query data with the HTTP API.
Sample data
This document uses the same sample data as the Data Exploration page. The data is described and available for download on the Sample Data page.
See all databases with SHOW DATABASES
Get a list of all the databases in your system by entering:
SHOW DATABASES
CLI example:
> SHOW DATABASES
name: databases
---------------
name
NOAA_water_database
Explore retention policies with SHOW RETENTION POLICIES
The SHOW RETENTION POLICIES
query lists the existing retention policies on a given database, and it takes the following form:
SHOW RETENTION POLICIES ON <database_name>
CLI example:
> SHOW RETENTION POLICIES ON NOAA_water_database
CLI response:
name duration replicaN default
default 0 1 true
The first column of the output contains the names of the different retention policies in the specified database.
The second column shows the duration and the third column shows the replication factor of the retention policy.
The fourth column specifies if the retention policy is the DEFAULT
retention policy for the database.
The following example shows a hypothetical CLI response where there are four different retention policies in the database, and where the DEFAULT
retention policy is three_days_only
:
name duration replicaN default
default 0 1 false
two_days_only 48h0m0s 1 false
one_day_only 24h0m0s 1 false
three_days_only 72h0m0s 1 true
Explore series with SHOW SERIES
The SHOW SERIES
query returns the distinct series in your database and takes the following form, where the FROM
and WHERE
clauses are optional:
SHOW SERIES [FROM <measurement_name> [WHERE <tag_key>='<tag_value>']]
Return all series in the database NOAA_water_database
:
> SHOW SERIES
CLI response:
key
average_temperature,location=coyote_creek
average_temperature,location=santa_monica
h2o_feet,location=coyote_creek
h2o_feet,location=santa_monica
h2o_pH,location=coyote_creek
h2o_pH,location=santa_monica
h2o_quality,location=coyote_creek,randtag=1
h2o_quality,location=coyote_creek,randtag=2
h2o_quality,location=coyote_creek,randtag=3
h2o_quality,location=santa_monica,randtag=1
h2o_quality,location=santa_monica,randtag=2
h2o_quality,location=santa_monica,randtag=3
h2o_temperature,location=coyote_creek
h2o_temperature,location=santa_monica
SHOW SERIES
organizes its output similar to the line protocol format.
Everything before the first comma is the measurement name.
Everything after the first comma is either a tag key or a tag value.
From the output above you can see that the data in the database NOAA_water_database
have five different measurements and 14 different series.
The measurements are average_temperature
, h2o_feet
, h2o_pH
, h2o_quality
, and h2o_temperature
.
Every measurement has the tag key location
with the tag values coyote_creek
and santa_monica
- that makes 10 series.
The measurement h2o_quality
has the additional tag key randtag
with the tag values 1
,2
, and 3
- that makes 14 series.
Return series for a specific measurement:
> SHOW SERIES FROM h2o_quality
CLI response:
key
h2o_quality,location=coyote_creek,randtag=1
h2o_quality,location=coyote_creek,randtag=2
h2o_quality,location=coyote_creek,randtag=3
h2o_quality,location=santa_monica,randtag=1
h2o_quality,location=santa_monica,randtag=2
h2o_quality,location=santa_monica,randtag=3
Return series for a specific measurement and tag set:
> SHOW SERIES FROM h2o_quality WHERE location = 'coyote_creek'
CLI response:
key
h2o_quality,location=coyote_creek,randtag=1
h2o_quality,location=coyote_creek,randtag=2
h2o_quality,location=coyote_creek,randtag=3
Explore measurements with SHOW MEASUREMENTS
The SHOW MEASUREMENTS
query returns the measurements in your database and it takes the following form:
SHOW MEASUREMENTS [WITH MEASUREMENT =~ <regular_expression>] [WHERE <tag_key>=<'tag_value'>]
Return all measurements in the NOAA_water_database
database:
> SHOW MEASUREMENTS
CLI response:
name: measurements
------------------
name
average_temperature
h2o_feet
h2o_pH
h2o_quality
h2o_temperature
From the output you can see that the database NOAA_water_database
has five measurements: average_temperature
, h2o_feet
, h2o_pH
, h2o_quality
, and h2o_temperature
.
Return measurements where the tag key randtag
equals 1
:
> SHOW MEASUREMENTS WHERE randtag = '1'
CLI response:
name: measurements
------------------
name
h2o_quality
Only the measurement h2o_quality
contains the tag set randtag = 1
.
Use a regular expression to return measurements where the tag key randtag
is a digit:
SHOW MEASUREMENTS WHERE randtag =~ /\d/
CLI response:
name: measurements
------------------
name
h2o_quality
Use a regular expression with WITH MEASUREMENT
to return all measurements that start with h2o
:
> SHOW MEASUREMENTS WITH MEASUREMENT =~ /h2o.*/
CLI response:
name: measurements
------------------
name
h2o_feet
h2o_pH
h2o_quality
h2o_temperature
Explore tag keys with SHOW TAG KEYS
SHOW TAG KEYS
returns the tag keys associated with each measurement and takes the following form, where the FROM
clause is optional:
SHOW TAG KEYS [FROM <measurement_name>]
Return all tag keys that are in the database NOAA_water_database
:
> SHOW TAG KEYS
CLI response:
name: average_temperature
-------------------------
tagKey
location
name: h2o_feet
--------------
tagKey
location
name: h2o_pH
------------
tagKey
location
name: h2o_quality
-----------------
tagKey
location
randtag
name: h2o_temperature
---------------------
tagKey
location
InfluxDB organizes the output by measurement.
Notice that each of the five measurements has the tag key location
and that the measurement h2o_quality
also has the tag key randtag
.
Return the tag keys for a specific measurement:
> SHOW TAG KEYS FROM h2o_temperature
CLI response:
name: h2o_temperature
---------------------
tagKey
location
Explore tag values with SHOW TAG VALUES
The SHOW TAG VALUES
query returns the set of tag values for a specific tag key across all measurements in the database.
Syntax for specifying a single tag key:
SHOW TAG VALUES [FROM <measurement_name>] WITH KEY = "<tag_key>"
Syntax for specifying more than one tag key:
SHOW TAG VALUES [FROM <measurement_name>] WITH KEY IN ("<tag_key1>","<tag_key2")
Return the tag values for a single tag key (randtag
) across all measurements in the database NOAA_water_database
:
> SHOW TAG VALUES WITH KEY = "randtag"
CLI response:
name: h2o_quality
-----------------
key value
randtag 1
randtag 3
randtag 2
Return the tag values for two tag keys (location
and randtag
) across all measurements in the database NOAA_water_database
:
> SHOW TAG VALUES WITH KEY IN ("location","randtag")
CLI response:
name: average_temperature
-------------------------
key value
location coyote_creek
location santa_monica
name: h2o_feet
--------------
key value
location coyote_creek
location santa_monica
name: h2o_pH
------------
key value
location coyote_creek
location santa_monica
name: h2o_quality
-----------------
key value
location coyote_creek
randtag 1
randtag 3
randtag 2
location santa_monica
name: h2o_temperature
---------------------
key value
location coyote_creek
location santa_monica
Return the tag values for the tag key randtag
for a specific measurement in the NOAA_water_database
database:
> SHOW TAG VALUES FROM average_temperature WITH KEY = "randtag"
CLI response:
The measurement average_temperature
doesn’t have the tag key randtag
so InfluxDB returns nothing.
Explore field keys with SHOW FIELD KEYS
The SHOW FIELD KEYS
query returns the field keys across each measurement in the database.
It takes the following form, where the FROM
clause is optional:
SHOW FIELD KEYS [FROM <measurement_name>]
Return the field keys across all measurements in the database NOAA_water_database
:
> SHOW FIELD KEYS
CLI response:
name: average_temperature
-------------------------
fieldKey
degrees
name: h2o_feet
--------------
fieldKey
level description
water_level
name: h2o_pH
------------
fieldKey
pH
name: h2o_quality
-----------------
fieldKey
index
name: h2o_temperature
---------------------
fieldKey
degrees
Return the field keys in the measurement h2o_feet
in the database NOAA_water_database
:
> SHOW FIELD KEYS FROM h2o_feet
CLI response:
name: h2o_feet
--------------
fieldKey
level description
water_level