Documentation

Get started with InfluxDB Clustered

InfluxDB is the platform purpose-built to collect, store, and query time series data. InfluxDB Clustered is powered by the InfluxDB 3.0 storage engine, that provides nearly unlimited series cardinality, improved query performance, and interoperability with widely used data processing tools and platforms.

Time series data is a sequence of data points indexed in time order. Data points typically consist of successive measurements made from the same source and are used to track changes over time. Examples of time series data include:

  • Industrial sensor data
  • Server performance metrics
  • Heartbeats per minute
  • Electrical activity in the brain
  • Rainfall measurements
  • Stock prices

This multi-part tutorial walks you through writing time series data to your InfluxDB cluster, querying, and then visualizing that data.

Key concepts before you get started

Before you get started using InfluxDB, it’s important to understand how time series data is organized and stored in InfluxDB and some key definitions that are used throughout this documentation.

Data organization

The InfluxDB Clustered data model organizes time series data into databases and tables.

A database can contain multiple tables. Tables contain multiple tags and fields.

  • Database: A named location where time series data is stored in tables. Database is synonymous with bucket in InfluxDB Cloud Serverless and InfluxDB TSM.
    • Table: A logical grouping for time series data. All points in a given table should have the same tags. A table contains tags and fields. Table is synonymous with measurement in InfluxDB Cloud Serverless and InfluxDB TSM.
      • Tags: Key-value pairs that provide metadata for each point–for example, something to identify the source or context of the data like host, location, station, etc. Tag values may be null.
      • Fields: Key-value pairs with values that change over time–for example, temperature, pressure, stock price, etc. Field values may be null, but at least one field value is not null on any given row.
      • Timestamp: Timestamp associated with the data. When stored on disk and queried, all data is ordered by time. A timestamp is never null.

What about buckets and measurements?

If coming from InfluxDB Cloud Serverless or InfluxDB powered by the TSM storage engine, you’re likely familiar with the concepts bucket and measurement. Bucket in TSM or InfluxDB Cloud Serverless is synonymous with database in InfluxDB Clustered. Measurement in TSM or InfluxDB Cloud Serverless is synonymous with table in InfluxDB Clustered.

Schema on write

As you write data to InfluxDB, the data defines the table schema. You don’t need to create tables or explicitly define the table schema.

Important definitions

The following definitions are important to understand when using InfluxDB:

  • Point: Single data record identified by its measurement, tag keys, tag values, field key, and timestamp.
  • Series: A group of points with the same measurement, tag keys and values, and field key.
  • Primary key: Columns used to uniquely identify each row in a table. Rows are uniquely identified by their timestamp and tag set. A row’s primary key tag set does not include tags with null values.
Example InfluxDB query results

name: weather

timecitycountrytemperaturehumidity
2022-01-01T12:00:00ZLondonUK12.088.4
2022-01-01T12:00:00ZCologneDE13.288.5
2022-02-01T12:00:00ZLondonUK12.194.0
2022-02-01T12:00:00ZCologneDE11.587.8
2022-03-01T12:00:00ZLondonUK11.582.1
2022-03-01T12:00:00ZCologneDE10.276.4
2022-04-01T12:00:00ZLondonUK5.987.6
2022-04-01T12:00:00ZCologneDE7.993.3

Tools to use

The following table compares tools that you can use to interact with InfluxDB Clustered. This tutorial covers many of the recommended tools.

ToolAdministrationWriteQuery
Chronograf--
influx CLI---
influxctl CLI*
influx3 data CLI*-
InfluxDB HTTP API*-
InfluxDB user interface---
InfluxDB v3 client libraries*-
InfluxDB v2 client libraries--
InfluxDB v1 client libraries-
Telegraf*--
Third-party tools
Flight SQL clients--
Grafana--
Superset--
Tableau--
* Covered in this tutorial

Avoid using the influx CLI with InfluxDB Clustered. While it may coincidentally work, it isn’t supported.

influxctl admin CLI

The influxctl command line interface (CLI) writes, queries, and performs administrative tasks, such as managing databases and authorization tokens in a cluster.

influx3 data CLI

The influx3 data CLI is a community-maintained tool that lets you write and query data in InfluxDB Clustered from a command line. It uses the HTTP API to write data and uses Flight gRPC to query data.

InfluxDB HTTP API

The InfluxDB HTTP API provides a simple way to let you manage InfluxDB Clustered and write and query data using HTTP(S) clients. Examples in this tutorial use cURL, but any HTTP(S) client will work.

The /write and /query v1-compatible endpoints work with the username/password authentication schemes and existing InfluxDB 1.x tools and code. The /api/v2/write v2-compatible endpoint works with existing InfluxDB 2.x tools and code.

InfluxDB client libraries

InfluxDB client libraries are community-maintained, language-specific clients that interact with InfluxDB APIs.

InfluxDB v3 client libraries are the recommended client libraries for writing and querying data InfluxDB Clustered. They use the HTTP API to write data and use InfluxDB’s Flight gRPC API to query data.

InfluxDB v2 client libraries can use /api/v2 HTTP endpoints to manage resources such as buckets and API tokens, and write data in InfluxDB Clustered.

InfluxDB v1 client libraries can write data to InfluxDB Clustered.

Authorization

InfluxDB Clustered requires authentication using one of the following token types:

  • Database token: A token that grants read and write access to InfluxDB databases.

  • Management token: A short-lived (1 hour) Auth0 token used to administer your InfluxDB cluster. These are generated by the influxctl CLI and do not require any direct management. Management tokens authorize a user to perform tasks related to:

    • Account management
    • Database management
    • Database token management
    • Pricing

Was this page helpful?

Thank you for your feedback!


The future of Flux

Flux is going into maintenance mode. You can continue using it as you currently are without any changes to your code.

Read more

InfluxDB v3 enhancements and InfluxDB Clustered is now generally available

New capabilities, including faster query performance and management tooling advance the InfluxDB v3 product line. InfluxDB Clustered is now generally available.

InfluxDB v3 performance and features

The InfluxDB v3 product line has seen significant enhancements in query performance and has made new management tooling available. These enhancements include an operational dashboard to monitor the health of your InfluxDB cluster, single sign-on (SSO) support in InfluxDB Cloud Dedicated, and new management APIs for tokens and databases.

Learn about the new v3 enhancements


InfluxDB Clustered general availability

InfluxDB Clustered is now generally available and gives you the power of InfluxDB v3 in your self-managed stack.

Talk to us about InfluxDB Clustered