Get started querying data
InfluxDB Cloud Serverless supports multiple query languages:
- SQL: Traditional SQL powered by the Apache Arrow DataFusion query engine. The supported SQL syntax is similar to PostgreSQL.
- Flux: A functional scripting language designed to query and process data from InfluxDB and other data sources.
This tutorial walks you through the fundamentals of querying data in InfluxDB and focuses on using SQL to query your time series data. The InfluxDB SQL implementation is built using Arrow Flight SQL, a protocol for interacting with SQL databases using the Arrow in-memory format and the Flight RPC framework. It leverages the performance of Apache Arrow with the simplicity of SQL.
The examples in this section of the tutorial query the get-started bucket for data written in the Get started writing data section.
Tools to execute queries
InfluxDB Cloud Serverless supports many different tools for querying data, including:
* Covered in this tutorial- Flight SQL clients*
- InfluxDB user interface (UI)*
influx3
data CLI*- InfluxDB HTTP API*
influx
CLI*- Superset
- Grafana
- Chronograf
SQL query basics
The InfluxDB SQL implementation is powered by the Apache Arrow DataFusion query engine which provides a SQL syntax similar to PostgreSQL.
This is a brief introduction to writing SQL queries for InfluxDB. For more in-depth details, see Query data with SQL.
InfluxDB SQL queries most commonly include the following clauses:
* Required- *
SELECT
: Identify specific fields and tags to query from a measurement or use the wild card alias (*
) to select all fields and tags from a measurement. - *
FROM
: Identify the measurement to query. If coming from a SQL background, an InfluxDB measurement is the equivalent of a relational table. WHERE
: Only return data that meets defined conditions such as falling within a time range, containing specific tag values, etc.GROUP BY
: Group data into SQL partitions and apply an aggregate or selector function to each group.
Example SQL queries
Execute an SQL query
Get started with one of the following tools for querying data stored in an InfluxDB Cloud Serverless bucket:
- InfluxDB UI: View your schema, build queries using the query editor, and generate data visualizations.
- Flight SQL clients: Use language-specific (Python, Go, etc.) clients to execute queries in your terminal or custom code.
- influx3 CLI: Send SQL queries from your terminal command-line.
- Grafana: Query InfluxDB v3 with the FlightSQL Data Source plugin and connect and visualize data.
influx
CLI, InfluxDB API, and InfluxDB API v2 client libraries: Use the InfluxDB/api/v2/query
endpoint and Flux to execute SQL.
For this example, use the following query to select all the data written to the get-started bucket between
Go to cloud2.influxdata.com in a browser to log in and access the InfluxDB UI.
In the side navigation menu, click Data Explorer.
<div class="nav-items-v4"> <div class="nav-item-v4"> <div class="nav-icon-v4"> <span class="v4 cf-icon GraphLine_New"></span> </div> </div> <div class="nav-item-v4"> <div class="nav-icon-v4"> <span class="v4 cf-icon GraphLine_New"></span> </div> <p class="nav-label-v4">Data Explorer</p> </div> </div>
In the schema browser on the left, select the get-started bucket from the bucket drop-down menu. The displayed measurements and fields are read-only and are meant to show you the schema of data stored in the selected bucket.
Enter the SQL query in the text editor.
Click Run.
Results are displayed under the query editor.
See Query in the Data Explorer to learn more.
Query InfluxDB v3 using SQL and the influx3
CLI, part of the InfluxCommunity/pyinflux3
community repository.
The following steps include setting up a Python virtual environment already
covered in Get started writing data.
If your project’s virtual environment is already running, skip to step 3.
Setup your Python virtual environment. Inside of your project directory:
python -m venv envs/virtual-env
Activate the virtual environment.
source ./envs/virtual-env/bin/activate
Install the following dependencies:
* Already installed in the Write data section
pyarrow
*flightsql-dbapi
*pyinflux3
*
Create the
config.json
configuration.influx3 config \ --name="my-config" \ --database="BUCKET_NAME" \ --host="cloud2.influxdata.com" \ --token="INFLUX_API_READ_TOKEN" \ --org="INFLUX_ORG_ID"
Replace the following:
BUCKET_NAME
: the name of the InfluxDB Cloud Serverless bucket to queryINFLUX_API_READ_TOKEN
: InfluxDB API token with read access to the get-started bucketINFLUX_ORG_ID
: InfluxDB organization ID
Enter the
influx3 sql
command and your SQL query statement.
influx3
displays query results in your terminal.
To query data from InfluxDB Cloud Serverless using Python, use the
pyinflux3
module.
The following steps include setting up a Python virtual environment already
covered in Get started writing data.
If your project’s virtual environment is already running, skip to step 3.
Setup your Python virtual environment. Inside of your project directory:
python -m venv envs/virtual-env
Activate the virtual environment.
source ./envs/virtual-env/bin/activate
Install the following dependencies:
* Already installed in the Write data section
pyarrow
*flightsql-dbapi
*pyinflux3
*pandas
tabulate
(to return formatted tables)
pip install pandas tabulate
Build your python script to query your InfluxDB bucket. These can be structured as a Python script or executed in a
python
shell.Import the
InfluxDBClient3
constructor from theinfluxdb_client_3
module.Use the
InfluxDBClient3
constructor to instantiate an InfluxDB Client. The example below assigns it to theclient
variable. Provide the following credentials:- host: InfluxDB Cloud Serverless region hostname (URL without protocol or trailing slash)
- token: InfluxDB API token with read access to the specified bucket. For security reasons, we recommend setting this as an environment variable rather than including the raw token string.
- database: the name of the InfluxDB Cloud Serverless bucket to query
Provide the SQL query to execute. In the example below, it’s assigned to the
query
variable.Use the
client.query
method to query data in the get-started database and return an Arrow table. Assign the return value to thetable
variable. Provide the following:- sql_query SQL query string to execute
Use
read_all
to read the data from InfluxDB and return an Arrow table.Use
to_pandas
to convert the Arrow table to a pandas DataFrame.Use
to_markdown
to convert the DataFrame to a markdown table.Use
print
to print out the markdown table.
In the
influxdb_go_client
directory you created in the Write data section, create a new file namedquery.go
.In
query.go
:Import the following packages:
context
crypto/x509
encoding/json
fmt
os
github.com/apache/arrow/go/v12/arrow/flight/flightsql
google.golang.org/grpc
google.golang.org/grpc/credentials
google.golang.org/grpc/metadata
Create a
dbQuery
function. In `dbQuery, define the following variables:- url: InfluxDB Cloud Serverless region hostname and port (
:443
) (no protocol) - token: InfluxDB API token with read access to the specified bucket. For security reasons, we recommend setting this as an environment variable rather than including the raw token string.
- database: the name of the InfluxDB Cloud Serverless bucket to query
- url: InfluxDB Cloud Serverless region hostname and port (
In the
dbQuery
function, create a gRPC transport for communicating with InfluxDB Cloud Serverless over the gRPC+TLS protocol.Use
flightsql.NewClient
to create a new Flight SQL client.Append the following key-value pairs to the outgoing context:
- authorization: Bearer <INFLUX_TOKEN>
- database-name: Database name
Define the query to execute.
Create a reader to read the Arrow table returned by the query and print the results as JSON.
Create a
main
function that executes thedbQuery
function.
Install all the necessary packages and run the program to query InfluxDB Cloud Serverless.
go get ./...
go run ./query.go
The influx query
command
uses the InfluxDB /api/v2/query
endpoint to query InfluxDB.
This endpoint only accepts Flux queries. To use SQL with the influx
CLI, wrap
your SQL query in Flux and use iox.sql()
to query the InfluxDB IOx storage engine with SQL.
Provide the following:
- Bucket name with the
bucket
parameter - SQL query with the
query
parameter
If you haven’t already, download, install, and configure the
influx
CLI.Use the
influx query
command to query InfluxDB using Flux.Provide the following:
- String-encoded Flux query that uses
iox.sql()
to query the InfluxDB IOx storage engine with SQL. - Connection and authentication credentials
- String-encoded Flux query that uses
To query data from InfluxDB using SQL and the InfluxDB HTTP API, send a request
to the InfluxDB API /api/v2/query
endpoint
using the POST
request method.
POST http://localhost:8086/api/v2/query
The /api/v2/query
endpoint only accepts Flux queries.
To query data with SQL, wrap your SQL query in Flux and use iox.sql()
to query the InfluxDB IOx storage engine with SQL.
Provide the following:
- Bucket name with the
bucket
parameter - SQL query with the
query
parameter
Include the following with your request:
- Headers:
- Authorization: Token <INFLUX_TOKEN>
- Content-Type: application/vnd.flux
- Accept: application/csv
- (Optional) Accept-Encoding: gzip
- Request body: Flux query as plain text. In the Flux query, use
iox.sql()
and provide your bucket name and your SQL query.
The following example uses cURL and the InfluxDB API to query data with Flux:
The InfluxDB /api/v2/query
endpoint returns query results in
annotated CSV.
Query results
Congratulations! You’ve learned the basics of querying data in InfluxDB with SQL. For a deep dive into all the ways you can query InfluxDB, see the Query data in InfluxDB section of documentation.
Was this page helpful?
Thank you for your feedback!
Support and feedback
Thank you for being part of our community! We welcome and encourage your feedback and bug reports for InfluxDB and this documentation. To find support, use the following resources:
InfluxDB Cloud and InfluxDB Enterprise customers can contact InfluxData Support.