InfluxDB OSS v1

https://docs.influxdata.com/influxdb/v1/
Admin
InfluxDB OSS v1 is a time series database designed to handle high write and query loads for...
Tokens:850,173
Snippets:7,040
Trust Score:10
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install and start InfluxDB with apt-get (sysvinit)

Source: https://docs.influxdata.com/influxdb/v1/introduction/installation

Installs InfluxDB via apt-get and starts the service using the sysvinit service command. Use this for systems without systemd.

```bash
sudo apt-get update && sudo apt-get install influxdb
sudo service influxdb start
```

--------------------------------

### Install and start InfluxDB with apt-get (systemd)

Source: https://docs.influxdata.com/influxdb/v1/introduction/installation

Installs InfluxDB via apt-get and starts it with systemd (Ubuntu 15.04+, Debian 8+). Unmasks the service before starting.

```bash
sudo apt-get update && sudo apt-get install influxdb
sudo systemctl unmask influxdb.service
sudo systemctl start influxdb
```

--------------------------------

### SHOW DATABASES example

Source: https://docs.influxdata.com/influxdb/v1/query_language/spec

Example of showing all databases.

```influxql
-- show all databases
SHOW DATABASES
```

--------------------------------

### Install and start InfluxDB with yum (sysvinit)

Source: https://docs.influxdata.com/influxdb/v1/introduction/installation

Installs InfluxDB via yum and starts the service using the sysvinit service command. Use this for systems without systemd.

```bash
sudo yum install influxdb
sudo service influxdb start
```

--------------------------------

### Start Telegraf with custom configuration

Source: https://docs.influxdata.com/influxdb/v1/administration/monitor/external-monitor-setup/index.md

Starts Telegraf with a custom configuration file. Use this command on each primary node after installing and configuring Telegraf.

```bash
telegraf -config path/to/telegraf.conf
```

--------------------------------

### SHOW USERS example

Source: https://docs.influxdata.com/influxdb/v1/query_language/spec

Example of a SHOW USERS query.

```influxql
-- show all users
SHOW USERS
```

--------------------------------

### Start InfluxDB on FreeBSD

Source: https://docs.influxdata.com/influxdb/v1/introduction/install/index.md

Start the InfluxDB backend on FreeBSD. To have InfluxDB start at system boot, add influxd_enable="YES" to /etc/rc.conf.

```bash
sudo service influxd onestart
```

--------------------------------

### CREATE SUBSCRIPTION pattern and examples

Source: https://docs.influxdata.com/influxdb/v1/administration/subscription-management/index.md

Shows the CREATE SUBSCRIPTION syntax pattern and two examples: one sending data to a single HTTP host, and one round-robining data between two UDP hosts. Use ALL to write to all specified hosts or ANY to round-robin writes.

```sql
-- Pattern:
CREATE SUBSCRIPTION "<subscription_name>" ON "<db_name>"."<retention_policy>" DESTINATIONS <ALL|ANY> "<subscription_endpoint_host>"

-- Examples:
-- Create a SUBSCRIPTION on database 'mydb' and retention policy 'autogen' that sends data to 'example.com:9090' via HTTP.
CREATE SUBSCRIPTION "sub0" ON "mydb"."autogen" DESTINATIONS ALL 'http://example.com:9090'

-- Create a SUBSCRIPTION on database 'mydb' and retention policy 'autogen' that round-robins the data to 'h1.example.com:9090' and 'h2.example.com:9090' via UDP.
CREATE SUBSCRIPTION "sub0" ON "mydb"."autogen" DESTINATIONS ANY 'udp://h1.example.com:9090', 'udp://h2.example.com:9090'
```

--------------------------------

### Install and start InfluxDB on Red Hat/CentOS

Source: https://docs.influxdata.com/influxdb/v1/introduction/install/index.md

Install InfluxDB on Red Hat and CentOS using the yum package manager, then start the influxdb service with systemctl.

```bash
sudo yum install influxdb
sudo systemctl start influxdb
```

--------------------------------

### Custom initialization scripts

Source: https://docs.influxdata.com/influxdb/v1/introduction/install/docker

Create a custom initialization script (init-scripts/setup.iql) and run it with the container. The script creates databases, users, grants, and a retention policy. The docker run command mounts the init-scripts directory into /docker-entrypoint-initdb.d. Scripts run only on first startup when the data directory is empty, in alphabetical order.

```iql
CREATE DATABASE sensors;
CREATE DATABASE logs;

CREATE USER "telegraf" WITH PASSWORD 'secret123';
GRANT WRITE ON "sensors" TO "telegraf";

CREATE USER "grafana" WITH PASSWORD 'secret456';
GRANT READ ON "sensors" TO "grafana";
GRANT READ ON "logs" TO "grafana";

CREATE RETENTION POLICY "one_week" ON "sensors" DURATION 1w REPLICATION 1 DEFAULT;
```

```bash
docker run -p 8086:8086 \
  -v $PWD/data:/var/lib/influxdb \
  -v $PWD/init-scripts:/docker-entrypoint-initdb.d \
  influxdb:1.13.0
```

--------------------------------

### SHOW QUERIES example

Source: https://docs.influxdata.com/influxdb/v1/query_language/spec/index.md

Example of SHOW QUERIES to display all currently-running queries.

```sql
-- show all currently-running queries
## SHOW QUERIES
```

--------------------------------

### Install and start InfluxDB on Ubuntu/Debian (service or systemd)

Source: https://docs.influxdata.com/influxdb/v1/introduction/install/index.md

Install and start InfluxDB on Ubuntu/Debian. The first block uses the service command; the second uses systemd for Ubuntu 15.04+ and Debian 8+.

```bash
sudo apt-get update && sudo apt-get install influxdb
sudo service influxdb start
```

```bash
sudo apt-get update && sudo apt-get install influxdb
sudo systemctl unmask influxdb.service
sudo systemctl start influxdb
```

--------------------------------

### GET /query

Source: https://docs.influxdata.com/influxdb/v1/api/query/index.md

Query data using InfluxQL. Use GET for read-only queries that start with SELECT (except queries with INTO clause) or SHOW.

```APIDOC
## GET /query

### Description
Query data using InfluxQL. Use GET for read-only queries that start with SELECT (except queries with INTO clause) or SHOW.

### Method
GET

### Endpoint
/query

### Parameters
#### Query Parameters
- **db** (string) - Optional - Target database for the query
- **q** (string) - Required - InfluxQL query string
- **epoch** (string) - Optional - Return timestamps as Unix epoch values with specified precision. By default, timestamps are returned in RFC3339 format. Allowed values: ns, u, µ, ms, s, m, h
- **pretty** (boolean) - Optional - Enable pretty-printed JSON output (not recommended for production)
- **chunked** (string) - Optional - Return results in streamed batches. Set to true to chunk by series or every 10,000 points. Set to a number to chunk by that many points.
- **u** (string) - Optional - Username for authentication
- **p** (string) - Optional - Password for authentication

### Request Example
```sh
curl --request GET \
  "http://localhost:8086/query?q=Q" \
  --header "Authorization: Bearer INFLUX_TOKEN"
```

### Response
#### Success Response (200)
Query executed successfully
- **results** (object[]) - Description
- **error** (string) - Description
- **series** (object[]) - Description
- **columns** (string[]) - Description
- **name** (string) - Measurement name
- **tags** (object) - Description
- **values** (array[]) - Description
- **statement_id** (integer) - Description

#### Response Example
{
  "results": [],
  "error": "",
  "series": [],
  "columns": [],
  "name": "",
  "tags": {},
  "values": [],
  "statement_id": 0
}

#### Error Response (400)
Bad request (syntax error in query)
- **error** (string) - Required - Error message

#### Error Response (401)
Unauthorized
- **error** (string) - Required - Error message
```

--------------------------------

### EXPLAIN example with output

Source: https://docs.influxdata.com/influxdb/v1/query_language/spec

Example of an EXPLAIN query and its output, showing the query plan with estimated costs.

```influxql
> explain select sum(pointReq) from "_internal"."monitor"."write" group by hostname;
> QUERY PLAN
------
EXPRESSION: sum(pointReq::integer)
NUMBER OF SHARDS: 2
NUMBER OF SERIES: 2
CACHED VALUES: 110
NUMBER OF FILES: 1
NUMBER OF BLOCKS: 1
SIZE OF BLOCKS: 931
```

--------------------------------

### Install InfluxDB on FreeBSD

Source: https://docs.influxdata.com/influxdb/v1/introduction/install/index.md

Install InfluxDB on FreeBSD using the pkg package manager. The configuration file is located at /usr/local/etc/influxd.conf with examples in /usr/local/etc/influxd.conf.sample.

```bash
sudo pkg install influxdb
```

--------------------------------

### Field set syntax and example

Source: https://docs.influxdata.com/influxdb/v1/write_protocols/line_protocol_tutorial/index.md

Shows the syntax for a single field key-value pair and multiple pairs separated by commas, followed by a complete line protocol example with two fields and a timestamp.

```text
<field_key>=<field_value>
```

```text
<field_key>=<field_value>,<field_key>=<field_value>
```

```text
weather,location=us-midwest temperature=82,humidity=71 1465839830100400200
```

--------------------------------

### SHOW USERS CLI example

Source: https://docs.influxdata.com/influxdb/v1/administration/authentication_and_authorization

Example output of the SHOW USERS command.

```influxql
> SHOW USERS
user 	   admin
todd     false
paul     true
hermione false
dobby    false
```

--------------------------------

### Example output of SHOW SUBSCRIPTIONS

Source: https://docs.influxdata.com/influxdb/v1/administration/subscription-management/index.md

Example output of the SHOW SUBSCRIPTIONS statement, showing the subscription name, mode, and destination.

```bash
name: _internal
retention_policy name                                           mode destinations
---------------- ----                                           ---- ------------
monitor          kapacitor-39545771-7b64-4692-ab8f-1796c07f3314 ANY  [http://localhost:9092]
```

--------------------------------

### Define the example data variable

Source: https://docs.influxdata.com/influxdb/v1/flux/guides/index.md

Defines the `data` variable used by many examples in the Flux guides. It filters data by measurement and field.

```flux
data = from(bucket: "db/rp")
|> range(start: -1h)
|> filter(fn: (r) => r._measurement == "example-measurement" and r._field == "example-field")
```

--------------------------------

### CREATE DATABASE examples

Source: https://docs.influxdata.com/influxdb/v1/query_language/spec

Examples of CREATE DATABASE: creating a simple database, specifying retention policy options (duration, replication, shard duration, name), and using future/past limits. Note that FUTURE LIMIT must appear before PAST LIMIT.

```influxql
-- Create a database called foo
CREATE DATABASE "foo"

-- Create a database called bar with a new DEFAULT retention policy and specify
-- the duration, replication, shard group duration, and name of that retention policy
CREATE DATABASE "bar" WITH DURATION 1d REPLICATION 1 SHARD DURATION 30m NAME "myrp"

-- Create a database called mydb with a new DEFAULT retention policy and specify
-- the name of that retention policy
CREATE DATABASE "mydb" WITH NAME "myrp"

-- Create a database called bar with a new retention policy named "myrp", and
-- specify the duration, future and past limits, and name of that retention policy
CREATE DATABASE "bar" WITH DURATION 1d FUTURE LIMIT 6h PAST LIMIT 6h NAME "myrp"
```

--------------------------------

### Install and start InfluxDB on Red Hat/CentOS (yum)

Source: https://docs.influxdata.com/influxdb/v1/introduction/install/index.md

Add the InfluxDB yum repository for Red Hat and CentOS, then install and start InfluxDB. The first block creates /etc/yum.repos.d/influxdb.repo; the second uses service, the third uses systemd for CentOS 7+ and RHEL 7+.

```bash
cat <<EOF | sudo tee /etc/yum.repos.d/influxdb.repo
[influxdb]
name = InfluxDB Repository - RHEL \$releasever
baseurl = https://repos.influxdata.com/rhel/\$releasever/\$basearch/stable
enabled = 1
gpgcheck = 1
gpgkey = https://repos.influxdata.com/influxdata-archive.key
EOF
```

```bash
sudo yum install influxdb
sudo service influxdb start
```

```bash
sudo yum install influxdb
sudo systemctl unmask influxdb.service
sudo systemctl start influxdb
```

--------------------------------

### Initial data for INTO query example

Source: https://docs.influxdata.com/influxdb/v1/troubleshooting/frequently-asked-questions

Shows the initial data in the french_bulldogs measurement, which includes the color tag and the name field. This is the starting point for the INTO query examples.

```influxql
> SELECT * FROM "french_bulldogs"
name: french_bulldogs
---------------------
time                  color  name
2016-05-25T00:05:00Z  peach  nugget
2016-05-25T00:05:00Z  grey   rumple
2016-05-25T00:10:00Z  black  prince
```

--------------------------------

### Relative time ranges with range()

Source: https://docs.influxdata.com/influxdb/v1/flux/get-started/query-influxdb/index.md

Shows relative time ranges using the range() function. The first example specifies only start, with stop defaulting to now; the second specifies both start and stop. Relative ranges are relative to now.

```js
// Relative time range with start only. Stop defaults to now.
from(bucket:"telegraf/autogen")
  |> range(start: -1h)

// Relative time range with start and stop
from(bucket:"telegraf/autogen")
  |> range(start: -1h, stop: -10m)
```

--------------------------------

### SHOW QUERIES example

Source: https://docs.influxdata.com/influxdb/v1/query_language/spec

Example SHOW QUERIES query to list all currently-running queries.

```influxql
-- show all currently-running queries
SHOW QUERIES
--
```

--------------------------------

### TOP() with GROUP BY time() example

Source: https://docs.influxdata.com/influxdb/v1/query_language/functions/index.md

Shows that TOP() with GROUP BY time() returns the specified number of points per interval and preserves original timestamps instead of forcing them to the interval start. The example returns two points per 18-minute interval.

```sql
> SELECT TOP("water_level",2) FROM "h2o_feet" WHERE time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:30:00Z' AND "location" = 'santa_monica' GROUP BY time(18m)

name: h2o_feet
time                   top
----                   ------
                           __
2015-08-18T00:00:00Z  2.064 |
2015-08-18T00:06:00Z  2.116 | <------- Greatest points for the first time interval
                           --
                           __
2015-08-18T00:18:00Z  2.126 |
2015-08-18T00:30:00Z  2.051 | <------- Greatest points for the second time interval
                           --
```

--------------------------------

### Convert all shards on a node with buildtsi

Source: https://docs.influxdata.com/influxdb/v1/tools/influx_inspect

Example command to convert all shards on a node using `buildtsi` with default data and WAL directories.

```bash
$ influx_inspect buildtsi -datadir ~/.influxdb/data -waldir ~/.influxdb/wal
```

--------------------------------

### SAMPLE()

Source: https://docs.influxdata.com/influxdb/v1/query_language/functions/index.md

Documentation for the SAMPLE() InfluxQL function, including syntax, parameters, and an example query.

```APIDOC
## SAMPLE()

### Description
Returns a random sample of N field values. SAMPLE() uses reservoir sampling to generate the random points.

### Syntax
```
SELECT SAMPLE(<field_key>, <N>)[,<tag_key(s)>|<field_key(s)>] [INTO_clause] FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause]
```

### Parameters
- **field_key** (string) - Required - The field key to sample.
- **N** (integer) - Required - The number of random field values to return.

### Usage Notes
- `SAMPLE(field_key,N)` returns N randomly selected field values associated with the field key.
- `SAMPLE(/regular_expression/,N)` returns N randomly selected field values associated with each field key that matches the regular expression.
- `SAMPLE(*,N)` returns N randomly selected field values associated with each field key in the measurement.
- `SAMPLE(field_key,N),tag_key(s),field_key(s)` returns N randomly selected field values associated with the field key in the parentheses and the relevant tag and/or field.
- N must be an integer.
- SAMPLE() supports all field value data types.

### Example
```sql
> SELECT SAMPLE("water_level",2) FROM "h2o_feet"

name: h2o_feet
time                   sample
----                   ------
2015-09-09T21:48:00Z   5.659
2015-09-18T10:00:00Z   6.939
```

The query returns two randomly selected points from the `water_level` field key and in the `h2o_feet` measurement.
```

--------------------------------

### Find the value representing the 99th percentile using quantile()

Source: https://docs.influxdata.com/influxdb/v1/flux/guides/percentile-quantile/index.md

Uses the default method, "estimate_tdigest", to return all rows in a table that contain values in the 99th percentile of data in the table. The example assumes the `data` variable is defined as described in the example data variable guide.

```flux
data
    |> quantile(q: 0.99)
```

--------------------------------

### Query data from InfluxDB with Flux

Source: https://docs.influxdata.com/influxdb/v1/flux/get-started/transform-data/index.md

Queries CPU usage data from the last hour, filtering for the usage_system field on cpu-total. This is the starting point for the transformation examples that follow.

```js
from(bucket: "telegraf/autogen")
    |> range(start: -1h)
    |> filter(fn: (r) => r._measurement == "cpu" and r._field == "usage_system" and r.cpu == "cpu-total")
```

--------------------------------

### Convert all shards for a database with buildtsi

Source: https://docs.influxdata.com/influxdb/v1/tools/influx_inspect

Example command to convert all shards for a specific database using `buildtsi`.

```bash
$ influx_inspect buildtsi -database mydb -datadir ~/.influxdb/data -waldir ~/.influxdb/wal
```

--------------------------------

### CREATE SUBSCRIPTION examples

Source: https://docs.influxdata.com/influxdb/v1/query_language/spec

Examples of CREATE SUBSCRIPTION statements. The first sends data to a single host via UDP; the second round-robins data between two hosts using the ANY destination option.

```influxql
-- Create a SUBSCRIPTION on database 'mydb' and retention policy 'autogen' that send data to 'example.com:9090' via UDP.
CREATE SUBSCRIPTION "sub0" ON "mydb"."autogen" DESTINATIONS ALL 'udp://example.com:9090'

-- Create a SUBSCRIPTION on database 'mydb' and retention policy 'autogen' that round robins the data to 'h1.example.com:9090' and 'h2.example.com:9090'.
CREATE SUBSCRIPTION "sub0" ON "mydb"."autogen" DESTINATIONS ANY 'udp://h1.example.com:9090', 'udp://h2.example.com:9090'
```
Tokens:
Raw