Documentation

Frequently asked questions

This page documents an earlier version of InfluxDB. InfluxDB v2.5 is the latest stable version. View this page in the v2.5 documentation.

Account management
Security
Administration
Data types
Writing data
Querying data
Series and series cardinality

Account management

How do I reset my password?

Use the influx CLI and the influx user password command command to update a user’s password. For more information, see Change your password.


InfluxDB service health

Where can I see the current status of my InfluxDB instance?

InfluxDB 2.2 provides different ways to monitor its status:

  • The /health API endpoint returns a JSON body with a summary of the current status of your InfluxDB instance.

View example health summary


Security

What different types of API tokens exist?

InfluxDB 2.2 supports the following token types:

  • Operator tokens
  • All-Access tokens
  • Read/Write tokens

For more information about each token type, see Manage API tokens.

Can I use InfluxDB with authentication disabled?

InfluxDB 2.2 enforces security best practices by requiring API requests to be authenticated. Authentication cannot be disabled.


Administration

How can I identify my InfluxDB version?

Use one of the following methods to identify the version of InfluxDB OSS you’re using:

  • Use the InfluxDB UI:

    • On the user login page
    • In the right column of the main landing page
  • Use the influxd version command

    $ influxd version
    
    InfluxDB 2.2.0 (git: x0x000xx0x) build_date: YYYY-MM-DDThh:mm:ssZ
    
  • Use the /health API endpoint.

    The following example uses jq to process the JSON body returned from the /health API endpoint and extract the InfluxDB version. You don’t have to process the JSON with jq. For an example of the JSON returned by the /health endpoint, see View example health summary.

    $ curl -s http://localhost:8086/health | jq -r '.version'
    
    2.2.0
    

How can I identify the version of Flux I’m using in InfluxDB?

To see what version of Flux is used in InfluxDB 2.2, run the following query:

import "array"
import "runtime"

array.from(rows: [{version: runtime.version()}])

For more information, see Query the Flux version.

Where can I find InfluxDB logs?

All InfluxDB logs are output by the influxd service. To store logs to a file, pipe the output of influxd to a file. For example:

influxd 2>~/path/to/influxd-errors.log

What is the relationship between shard group durations and retention periods?

InfluxDB buckets store data in shard groups. A single shard group covers a specific time interval. InfluxDB determines that time interval by using the retention period of the bucket. The table below outlines the default relationship between the bucket retention period and the time interval of a shard group:

Bucket retention periodDefault shard group duration
less than 2 days1h
between 2 days and 6 months1d
greater than 6 months7d

For more information, see InfluxDB Shards and shard groups.

Why isn’t data dropped after I update a bucket’s retention period?

Below are reasons why data may not be dropped immediately after updating the retention period of a bucket:

  • The retention enforcement service runs every 30 minutes (by default). You may need to wait for the next retention enforcement cycle to run.

  • InfluxDB drops shard groups, not individual points. Shard groups cover a specific time interval assigned to the shard group on creation. The retention service will only delete a shard group when the entire time range covered by the shard group is beyond the bucket retention period.

    If the bucket’s new retention period is less than the old shard group duration and InfluxDB is currently writing data to the old, longer shard group, the the retention service will not drop old shard group until its assigned interval is fully expired.

For more information, see Data retention.


Data types

What are the minimum and maximum integers that InfluxDB can store?

InfluxDB stores all integers as signed 64bit integers.

Minimum integer: -9223372036854775808
Maximum integer: 9223372036854775807

Values close to but within those limits may lead to unexpected behavior. Some query operations convert 64bit integers to 64bit float values which can cause overflow issues.

What are the minimum and maximum timestamps that InfluxDB can store?

InfluxDB uses 64bit integers to represent Unix nanosecond timestamps.

Minimum timestamp: -9223372036854775806 or 1677-09-21T00:12:43.145224194Z
Maximum timestamp: 9223372036854775806 or 2262-04-11T23:47:16.854775806Z

Timestamps outside that range return a parsing error.

Can I change a field’s data type?

Flux type-conversion functions let you change a fields data type at query time. However, you cannot change the type of a field on disk. Below are some possible workarounds:

  • Copy a field to a new field as a different type. The example below does the following:

    • Queries the example-string-field.
    • Converts field values to booleans.
    • Changes the field name to example-boolean-field.
    • Writes the new field to the source bucket.
    from(bucket: "example-bucket")
        |> range(start: -30d)
        |> filter(fn: (r) => r._measurement == "exampled-measurement")
        |> filter(fn: (r) => r._field == "example-string-field")
        |> toBool()
        |> set(key: "_field", as: "example-boolean-field")
        |> to(bucket: "example-bucket")
    
  • Copy a field to a new bucket as a different type. The example below does the following:

    • Queries the example-int-field from the example-bucket-1 bucket.
    • Converts field values to float values.
    • Changes the field name to example-float-field.
    • Writes the new field to the example-bucket-2 bucket.
    from(bucket: "example-bucket-1")
        |> range(start: -30d)
        |> filter(fn: (r) => r._measurement == "exampled-measurement")
        |> filter(fn: (r) => r._field == "example-int-field")
        |> toFloat()
        |> set(key: "_field", as: "example-float-field")
        |> to(bucket: "example-bucket-2")
    

Writing data

How do I write integer and unsigned integer field values?

In line protocol, identify integers with a trailing i and unsigned integers with a trailing u. Without these, numeric field values are parsed as floats.

# Integer
value=100i

# Unsigned integer
value=100u

# Float
value=100

How does InfluxDB handle duplicate points?

InfluxDB uniquely identifies a point by its measurement, tag set, and timestamp. If you submit a new point with the same measurement, tag set, and timestamp as an existing point, InfluxDB unions the old field with the new field set, and any ties go to the new field set.

For more information, see Handle duplicate data points.

What newline character does the InfluxDB write API require?

InfluxDB line protocol relies on line feed (\n, which is ASCII 0x0A) to indicate the end of one line and the beginning of a new line. Files or data that use a newline character other than \n will result in errors similar to bad timestamp or unable to parse.

Windows newlines

Windows uses carriage return and line feed (\r\n) as the newline character which will result in an error if you manually write line protocol on a Windows machine. Strip out any carriage returns (\r) before submitting the line protocol to the InfluxDB write API.

When should I single quote and when should I double quote when writing data?

Line protocol quote usage guidelines are provided in the line protocol documentation.

Does the precision of the timestamp matter?

Yes. Timestamp precision affects ingest performance. The more precise the timestamp, the longer it takes to write the point. To maximize performance, use the coarsest possible timestamp precision when writing data to InfluxDB. However, if too coarse, you risk writing points from the same series with the same timestamp, which would be treated as duplicate points.

What are the configuration recommendations and schema guidelines for writing sparse, historical data?

For sparse historical data, we recommend:

  • Use a longer shard group duration on the bucket you’re writing historical data to. Historical shard group durations can and should cover several years. If your historical data spans many years, but your bucket’s shard group duration is 1 week, InfluxDB will create many shards, negatively affecting overall performance.

  • Temporarily lower the storage-cache-snapshot-write-cold-duration configuration setting while ingesting historical data. The default setting (10m) can cause the system cache all of your data for every shard. Temporarily lowering the storage-cache-snapshot-write-cold-duration setting to 10s while you write the historical data makes the process more efficient.


Querying data

Flux

How do I structure fields as columns (like InfluxQL)?

A SELECT statement in InfluxQL returns data with a column for each queried tag and field. The Flux from() function returns data with a column for each tag as well as a _field column that contains the field key. Each field is grouped into a different table.

To structure each field as a column, use either pivot() or schema.fieldsAsCols().

exampleData
    |> pivot(rowKey: ["_time"], columnKey: ["_field"], valueColumn: "_value")
import "influxdata/influxdb/schema"

exampleData
    |> schema.fieldsAsCols()
Example data returned by from()
_measurementsensor_idlocation_field_time_value
machineabc123station20temp2022-01-01T00:00:00Z150.1
machineabc123station20temp2022-01-01T00:00:10Z152.8
machineabc123station20temp2022-01-01T00:00:20Z153.3
_measurementsensor_idlocation_field_time_value
machineabc123station20flow2022-01-01T00:00:00Z12.2
machineabc123station20flow2022-01-01T00:00:10Z14.9
machineabc123station20flow2022-01-01T00:00:20Z16.1
Example pivoted data
_measurementsensor_idlocation_timetempflow
machineabc123station202022-01-01T00:00:00Z150.112.2
machineabc123station202022-01-01T00:00:10Z152.814.9
machineabc123station202022-01-01T00:00:20Z153.316.1

How can I derive a state from multiple field values?

To compare multiple field values and derive a state:

  1. Query all fields necessary to derive a state.

  2. Use pivot() or schema.fieldsAsCols() to pivot fields into columns.

  3. Use map() to iterate over each input row assign a new column value based on values in the field columns.

    The fn parameter of map() defines a functions that outputs a record for each input row. Use conditional logic to assign a state.

from(bucket: "example-bucket")
    |> range(start: -1h)
    |> filter(fn: (r) => r._measurement == "example-measurement")
    |> filter(fn: (r) => r._field == "field1" or r._field == "field2")
    |> pivot(rowKey: ["_time"], columnKey: ["_field"], valueColumn: "_value")
    |> map(
        fn: (r) =>
            ({r with state:
                    if r.field1 > 90 and r.field2 < 10 then
                        "critical"
                    else if r.field1 > 70 and r.field2 < 30 then
                        "warning"
                    else if r.field1 > 40 and r.field2 < 60 then
                        "info"
                    else
                        "ok",
            }),
    )

InfluxQL

How do I use InfluxQL with InfluxDB v2.x?

Using InfluxQL with InfluxDB 2.2 is made possible by the 1.x compatiblity API which replicates the /query endpoint from InfluxDB 1.x. This allows all InfluxDB 1.x-compatible clients to work with InfluxDB 2.2. However, InfluxQL relies on a database and retention policy data model doesn’t exist in InfluxDB 2.2, but has been replaced by buckets.

InfluxDB 2.2 lets you map unique database and retention policy combinations used in InfluxQL to specific buckets using DBRP mappings.

For detailed instructions on using InfluxQL with InfluxDB 2.2 and configuring DBRP mapping, see Query with InfluxQL.

How do I perform mathematical operations in an InfluxQL function?

InfluxQL does not support mathematical operations within functions. Use a subquery to perform the mathematical calculation.

For example, InfluxQL does not support the following syntax:

SELECT MEAN("dogs" - "cats") from "pet_daycare"

Instead, use a subquery to get the same result:

SELECT MEAN("difference") FROM (SELECT "dogs" - "cat" AS "difference" FROM "pet_daycare")

Why does my query return epoch 0 as the timestamp?

In InfluxQL, epoch 0 (1970-01-01T00:00:00Z) is often used as a null timestamp equivalent. If you request a query that has no timestamp to return, such as an aggregation function with an unbounded time range, InfluxDB returns epoch 0 as the timestamp.

Which InfluxQL functions support nesting?

The following InfluxQL functions support nesting:

For information on how to use subqueries as substitutes for nested functions, see InfluxQL data exploration.

What determines the time intervals returned by GROUP BY time() queries?

The time intervals returned by GROUP BY time() queries conform to the InfluxDB database’s preset time windows or to the user-specified offset interval.

Preset time windows

For example, the following query calculates the average value of sunflowers between 6:15pm and 7:45pm and groups those averages into one hour intervals:

SELECT mean("sunflowers")
FROM "flower_orders"
WHERE time >= '2016-08-29T18:15:00Z' AND time <= '2016-08-29T19:45:00Z' GROUP BY time(1h)

InfluxQL uses the duration specified in the GROUP BY time() clause to partition data based on time. Preset time window boundaries fall on the duration unit specified.

For example:

GROUP BY time() durationResulting window boundaries
1s00:00:00 - 00:00:01, 00:00:01 - 00:00:02, etc.
1m00:00:00 - 00:01:00, 00:01:00 - 00:02:00, etc.
5m00:00:00 - 00:05:00, 00:05:00 - 00:10:00, etc.
1h00:00:00 - 01:00:00, 01:00:00 - 02:00:00, etc.

Although window boundaries may fall outside of the queried time range, only points within the queried time range are used in the calculation for each window.

Offset time windows

As another example, the following query calculates the average value of sunflowers between 6:15pm and 7:45pm and groups those averages into one hour intervals. It offsets the InfluxDB database’s preset time windows by 15 minutes.

SELECT mean("sunflowers")
FROM "flower_orders"
WHERE time >= '2016-08-29T18:15:00Z' AND time <= '2016-08-29T19:45:00Z' GROUP BY time(1h,15m)
                                                                                         ---
                                                                                          |
                                                                                   offset interval

InfluxQL uses the duration and offset specified in the GROUP BY time() clause to partition data based on time. Time boundaries begin at the specified offset.

For example:

GROUP BY time() duration and offsetResulting window boundaries
1m,30s00:30:00 - 01:30:00, 01:30:00 - 02:30:00, etc.
5m,15s00:00:15 - 00:05:15, 00:05:15 - 00:10:15, etc.
1h,20m00:20:00 - 01:20:00, 01:20:00 - 02:20:00, etc.

Why do my queries return no data or partial data?

The most common reasons why your query returns no data or partial data:

Querying the wrong retention policy

InfluxDB automatically queries data in a database’s default retention policy (configured as part of a DBRP mapping). If your data is associated another retention policy, you must specify the correct retention policy to get results.

No field key in the SELECT clause

An InfluxQL query requires at least one field key in the SELECT clause. If the SELECT clause includes only tag keys, the query returns an empty response. For more information, see InfluxQL Data exploration.

SELECT query includes GROUP BY time()

If your SELECT query includes a GROUP BY time() clause, only data points between 1677-09-21 00:12:43.145224194 and now() are returned. If any of your data points occur after now(), specify an alternative upper bound in your time interval.

Tag and field key with the same name

Avoid using the same name for a tag and field key. If you inadvertently add the same name for a tag and field key, and then query both together, the query results show the second key queried (tag or field) appended with _1. To query a tag or field key appended with _1, you must drop the appended _1 and include the syntax ::tag or ::field. For example:

-- Query duplicate keys using the correct syntax
SELECT "leaves"::tag, "leaves"::field FROM db.rp."grape"

name: grape
time                leaves     leaves_1
----                --------   ----------
1574128162128468000 species    6.00
1574128238044155000            5.00

Why don’t my GROUP BY time() queries return timestamps that occur after now()?

SELECT statements without a time range defined in the WHERE clause have a default time range of 1677-09-21 00:12:43.145224194 to 2262-04-11T23:47:16.854775806Z UTC. For SELECT statements that don’t specify a time range but have a GROUP BY time() clause, the default time range is 1677-09-21 00:12:43.145224194 UTC to now().

To query data with timestamps that occur after now(), SELECT statements with a GROUP BY time() clause must provide an alternative upper bound in the WHERE clause. For example:

SELECT MEAN("boards") FROM "hillvalley"
WHERE time >= '2022-01-01T00:00:00Z' AND time <= now() + 10d
GROUP BY time(12m) fill(none)

Note that the WHERE clause must provide an alternative upper bound to override the default now() upper bound. The following query merely resets the lower bound to now() such that the query’s time range is between now() and now():

SELECT MEAN("boards") FROM "hillvalley"
WHERE time >= now()
GROUP BY time(12m) fill(none)

For for more on time syntax in queries, see InfluxQL data Exploration.

Can I perform mathematical operations against timestamps?

InfluxQL does not support mathematical operators against timestamp values. Most time calculations must be carried out by the client receiving the query results.

There is limited support for using InfluxQL functions against timestamp values. The ELAPSED() function returns the difference between subsequent timestamps in a single field.

Can I identify write precision from returned timestamps?

InfluxDB stores all timestamps as nanosecond values, regardless of the write precision supplied. InfluxQL silently drops trailing zeros from timestamps which obscures the initial write precision. Because InfluxDB silently drops trailing zeros on returned timestamps, the write precision is not recognizable in the returned timestamps.

When should I use single quote versus double quotes in a query?

Follow these general rules for quotes in InfluxQL queries:

Single quotes
  • Use to quote literal string values, like tag values.
  • Do not use on identifiers like database names, retention policy names, user names, measurement names, tag keys, and field keys.
  • Use on date-time strings.
Double quotes
  • Use on identifiers that start with a digit, contain characters other than [A-z,0-9,_], or that are an InfluxQL keyword. We generally recommend using double quotes on all identifiers, even if they don’t meet these criteria.
  • Do not use on date-time strings.
-- Correctly quote usage

SELECT bikes_available FROM bikes WHERE station_id='9'

SELECT "bikes_available" FROM "bikes" WHERE "station_id"='9'

SELECT MIN("avgrq-sz") AS "min_avgrq-sz" FROM telegraf

SELECT * from "cr@zy" where "p^e"='2'

SELECT "water_level" FROM "h2o_feet" WHERE time > '2015-08-18T23:00:01.232000000Z' AND time < '2015-09-19'

-- Incorrect quote usage

SELECT 'bikes_available' FROM 'bikes' WHERE 'station_id'="9"

SELECT * from cr@zy where p^e='2'

SELECT "water_level" FROM "h2o_feet" WHERE time > "2015-08-18T23:00:01.232000000Z" AND time < "2015-09-19"

Why is my query with a WHERE OR time clause returning empty results?

InfluxQL does not support using OR in the WHERE clause to specify multiple time ranges and returns an empty response if multiple are specified. For example, the following query will return an empty response:

SELECT * FROM "absolutismus"
WHERE time = '2016-07-31T20:07:00Z' OR time = '2016-07-31T23:07:17Z'

Why does fill(previous) return empty results?

fill(previous) doesn’t fill a null value if there is no previous value inside the queried time range.

How do I query data with an identical tag key and field key?

Use the :: syntax to specify if the key is a field key or tag key. For example:

SELECT * FROM "candied" WHERE "almonds"::field > 51
SELECT * FROM "candied" WHERE "almonds"::tag='true'

How do I query data across measurements?

InfluxQL does not support querying multiple measurements All data must be under a single measurement to query it together. To perform cross-measurement queries, use Flux.

Does the order timestamps in a query matter?

No, it doesn’t. There is a only a negligible difference between the following queries:

SELECT ... FROM ... WHERE time > 'timestamp1' AND time < 'timestamp2'
SELECT ... FROM ... WHERE time < 'timestamp2' AND time > 'timestamp1'

How do I query data by a tag with a null value?

In your WHERE clause, specify an empty or null tag value with ''. For example:

SELECT * FROM "vases" WHERE priceless=''

Series and series cardinality

What is series cardinality?

Series cardinality is the total number of unique measurement and tag set combinations (series) stored on disk and indexed in memory.

Why does series cardinality matter?

InfluxDB maintains an in-memory index of every series. As the number of unique series grows, so does the memory usage. High series cardinality can force the host operating system to kill the InfluxDB process with an out of memory (OOM) exception.

Use influxdb.cardinality() in Flux or SHOW SERIES CARDINALITY in InfluxQL to measure the series cardinality in a bucket. See Resolve high series cardinality for information about reducing series cardinality.

How do I remove series from the index?

To remove a series from an index:

  1. Use the influx CLI or InfluxDB 2.2 API to delete points associated with the series. See Delete data for more information.
  2. Use the influxd inspect build-tsi tool to rebuild your index.

Was this page helpful?

Thank you for your feedback!


Set your InfluxDB URL

Upgrade to InfluxDB Cloud or InfluxDB 2.0!

InfluxDB Cloud and InfluxDB OSS 2.0 ready for production.