Documentation

InfluxDB Cloud Serverless

Get started querying data

  • 3 / 3

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.
  • InfluxQL: An SQL-like query language designed to query time series data stored in InfluxDB.

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

Avoid using /api/v2/query

Avoid using the /api/v2/query API endpoint and associated tooling, such as the influx query CLI command and > InfluxDB v2 client libraries, with InfluxDB Cloud Serverless.

SQL query basics

The InfluxDB Cloud Serverless SQL implementation is powered by the Apache Arrow DataFusion query engine which provides an 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 wildcard alias (*) to select all fields and tags from a measurement.
  • * FROM: Identify the measurement to query. If coming from an 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.
-- Return the average temperature and humidity within time bounds from each room
SELECT
  avg(temp),
  avg(hum),
  room
FROM
  home
WHERE
  time >= '2022-01-01T08:00:00Z'
  AND time <= '2022-01-01T20:00:00Z'
GROUP BY
  room

Example SQL queries

Select all data in a measurement
SELECT * FROM home
Select all data in a measurement within time bounds
SELECT
  *
FROM
  home
WHERE
  time >= '2022-01-01T08:00:00Z'
  AND time <= '2022-01-01T20:00:00Z'
Select a specific field within relative time bounds
SELECT temp FROM home WHERE time >= now() - INTERVAL '1 day'
Select specific fields and tags from a measurement
SELECT temp, room FROM home
Select data based on tag value
SELECT * FROM home WHERE room = 'Kitchen'
Select data based on tag value within time bounds
SELECT
  *
FROM
  home
WHERE
  time >= '2022-01-01T08:00:00Z'
  AND time <= '2022-01-01T20:00:00Z'
  AND room = 'Living Room'
Downsample data by applying interval-based aggregates
SELECT
  DATE_BIN(INTERVAL '1 hour', time, '2022-01-01T00:00:00Z') as _time,
  room,
  selector_max(temp, time)['value'] AS 'max temp'
FROM
  home
GROUP BY
  _time,
  'max temp',
  room
ORDER BY room, _time

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.
  • InfluxDB 3 client libraries: Use language-specific (Python, Go, etc.) clients to execute queries in your terminal or custom code.
  • influx3 data CLI: Send queries from your terminal command-line.
  • Grafana: Use the FlightSQL Data Source plugin, to query, connect, and visualize data.

Avoid using /api/v2/query

Avoid using the /api/v2/query API endpoint in InfluxDB Cloud Serverless and associated tooling, such as the influx > query CLI command and InfluxDB v2 client libraries. You can’t use SQL or InfluxQL with these tools.

For this example, use the following query to select all the data written to the get-started bucket between 2022-01-01T08:00:00Z and 2022-01-01T20:00:00Z.

SELECT
  *
FROM
  home
WHERE
  time >= '2022-01-01T08:00:00Z'
  AND time <= '2022-01-01T20:00:00Z'

Some examples in this getting started tutorial assume your InfluxDB credentials (URL, organization, and token) are provided by environment variables.

InfluxDB UI influx3 CLI Python Go Node.js C# Java

  1. Go to cloud2.influxdata.com in a browser to log in and access the InfluxDB UI.

  2. In the side navigation menu, click Data Explorer.

Data Explorer

  1. 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.

  2. Enter the SQL query in the text editor.

  3. Click Run.

Results are displayed under the query editor.

See Query in the Data Explorer to learn more.

Query InfluxDB 3 using SQL and the influx3 CLI.

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.

  1. Create a directory for your project and change into it:

    mkdir influx3-query-example && cd $_

  2. To create and activate a Python virtual environment, run the following command:

    python -m venv envs/virtual-env && . envs/virtual-env/bin/activate

  3. Install the CLI package (already installed in the Write data section).

    pip install influxdb3-python-cli

    Installing influxdb3-python-cli also installs the pyarrow library for working with Arrow data returned from queries.

  4. Create the config.json configuration.

    influx3 config create \
  --name="config-serverless" \
  --database="get-started" \
  --host="cloud2.influxdata.com

"
–token=“API_TOKEN”
–org=“ORG_ID” ```

Replace the following:

  1. Enter the influx3 sql command and your SQL query statement.

    influx3 sql "SELECT *
              FROM home
              WHERE time >= '2022-01-01T08:00:00Z'
              AND time <= '2022-01-01T20:00:00Z'"

    influx3 displays query results in your terminal.

Use the influxdb_client_3 client library module to integrate InfluxDB Cloud Serverless with your Python code. The client library supports writing data to InfluxDB and querying data using SQL or InfluxQL.

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.

  1. Open a terminal in the influxdb_py_client module directory you created in the Write data section:

    1. To create and activate your Python virtual environment, enter the following command in your terminal:

      python -m venv envs/virtual-env && . ./envs/virtual-env/bin/activate

    2. Install the following dependencies:

      * Already installed in the Write data section

      • influxdb3-python*: Provides the InfluxDB influxdb_client_3 Python client library module and also installs the pyarrow package for working with Arrow data returned from queries.
      • pandas: Provides pandas functions, modules, and data structures for analyzing and manipulating data.
      • tabulate: Provides the tabulate function for formatting tabular data. pandas requires this module for formatting data as Markdown.

      In your terminal, enter the following command:

      pip install influxdb3-python pandas tabulate

    3. In your terminal or editor, create a new file for your code–for example: query.py.

  2. In query.py, enter the following sample code:

    from influxdb_client_3 import InfluxDBClient3

client = InfluxDBClient3(
    host=f"cloud2.influxdata.com

“, token=f"API_TOKEN”, database=f"get-started")

sql = '''
  SELECT
    *
  FROM
    home
  WHERE
    time >= '2022-01-01T08:00:00Z'
    AND time <= '2022-01-01T20:00:00Z'
'''

table = client.query(query=sql)
assert table[‘room’], "Expect table to have room column."
print(table.to_pandas().to_markdown())




</code></pre>
<div class="expand-wrapper">
<div class="expand" id="important-if-using-windows-specify-the-windows-certificate-path">
  <a class="expand-link" href="#important-if-using-windows-specify-the-windows-certificate-path"><span class="cf-icon Link"></span></a>
  <p class="expand-label">
      <span class="expand-toggle"></span><span><span class='req'>Important</span>: If using <strong>Windows</strong>, specify the <strong>Windows</strong> certificate path</span>
  </p>
  <div class="expand-content" style="display: none;" >
      <p>When instantiating the client, Python looks for SSL/TLS certificate authority
(CA) certificates for verifying the server&rsquo;s authenticity.
If using a non-POSIX-compliant operating system (such as Windows), you need to
specify a certificate bundle path that Python can access on your system.</p>
<p>The following example shows how to use the
<a href="https://certifiio.readthedocs.io/en/latest/">Python <code>certifi</code> package</a> and
client library options to provide a bundle of trusted certificates to the
Python Flight client:</p>
<ol>
<li>
<p>In your terminal, install the Python <code>certifi</code> package.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-sh" data-lang="sh"><span class="line"><span class="cl">pip install certifi</span></span></code></pre></div>
</li>
<li>
<p>In your Python code, import <code>certifi</code> and call the <code>certifi.where()</code> method to retrieve the root certificate path.</p>
</li>
<li>
<p>When instantiating the client, pass the <code>flight_client_options.tls_root_certs=&lt;ROOT_CERT_PATH&gt;</code> option with the certificate path&ndash;for example:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"><span class="line"><span class="cl"><span class="kn">from</span> <span class="nn">influxdb_client_3</span> <span class="kn">import</span> <span class="n">InfluxDBClient3</span><span class="p">,</span> <span class="n">flight_client_options</span>
</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">os</span>
</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">certifi</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="n">fh</span> <span class="o">=</span> <span class="nb">open</span><span class="p">(</span><span class="n">certifi</span><span class="o">.</span><span class="n">where</span><span class="p">(),</span> <span class="s2">&#34;r&#34;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl"><span class="n">cert</span> <span class="o">=</span> <span class="n">fh</span><span class="o">.</span><span class="n">read</span><span class="p">()</span>
</span></span><span class="line"><span class="cl"><span class="n">fh</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="n">client</span> <span class="o">=</span> <span class="n">InfluxDBClient3</span><span class="p">(</span>
</span></span><span class="line"><span class="cl">    <span class="n">host</span><span class="o">=</span><span class="sa">f</span><span class="s2">&#34;cloud2.influxdata.com</span></span></span></code></pre></div>
</li>
</ol>
<p>&ldquo;,
token=f&quot;API_TOKEN&rdquo;,
database=f&quot;get-started&quot;,
flight_client_options=flight_client_options(
tls_root_certs=cert))
```</p>
<p>For more information, see <a href="/influxdb3/cloud-serverless/reference/client-libraries/v3/python/#query-exceptions"><code>influxdb_client_3</code> query exceptions</a>.</p>
  </div>
</div>
</div>
<p>The sample code does the following:</p>
<ol>
<li>
<p>Imports the <code>InfluxDBClient3</code> constructor from the <code>influxdb_client_3</code> module.</p>
</li>
<li>
<p>Calls the <code>InfluxDBClient3()</code> constructor method with credentials to instantiate an InfluxDB <code>client</code> with the following credentials:</p>
<ul>
<li><strong><code>host</code></strong>: InfluxDB Cloud Serverless region hostname
(without <code>https://</code> protocol or trailing slash)</li>
<li><strong><code>database</code></strong>: the name of the <a href="/influxdb3/cloud-serverless/admin/buckets/">InfluxDB Cloud Serverless bucket</a> to query</li>
<li><strong><code>token</code></strong>:  an <a href="/influxdb3/cloud-serverless/admin/tokens/">API token</a> with <em>read</em> access to the specified bucket.
<em>Store this in a secret store or environment variable to avoid exposing
the raw token string.</em></li>
</ul>
</li>
<li>
<p>Defines the SQL query to execute and assigns it to a <code>query</code> variable.</p>
</li>
<li>
<p>Calls the <code>client.query()</code> method with the SQL query.
<code>query()</code> sends a
Flight request to InfluxDB, queries the database (bucket), retrieves result data from the endpoint, and then returns a
<a href="https://arrow.apache.org/docs/python/generated/pyarrow.Table.html#pyarrow.Table"><code>pyarrow.Table</code></a>
assigned to the <code>table</code> variable.</p>
</li>
<li>
<p>Calls the <a href="https://arrow.apache.org/docs/python/generated/pyarrow.Table.html#pyarrow.Table.to_pandas"><code>to_pandas()</code> method</a>
to convert the Arrow table to a <a href="https://arrow.apache.org/docs/python/pandas.html"><code>pandas.DataFrame</code></a>.</p>
</li>
<li>
<p>Calls the <a href="https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.to_markdown.html"><code>pandas.DataFrame.to_markdown()</code> method</a>
to convert the DataFrame to a markdown table.</p>
</li>
<li>
<p>Calls the <code>print()</code> method to print the markdown table to stdout.</p>
</li>
<li>
<p>In your terminal, enter the following command to run the program and query InfluxDB Cloud Serverless:</p>
 <!--pytest.mark.skip-->


<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-sh" data-lang="sh"><span class="line"><span class="cl">python query.py</span></span></code></pre></div>
</li>
</ol>
<div class="expand-wrapper">
<div class="expand" id="view-returned-markdown-table">
  <a class="expand-link" href="#view-returned-markdown-table"><span class="cf-icon Link"></span></a>
  <p class="expand-label">
      <span class="expand-toggle"></span><span>View returned markdown table</span>
  </p>
  <div class="expand-content" style="display: none;" >
      <table>
  <thead>
      <tr>
          <th style="text-align: right"></th>
          <th style="text-align: right">co</th>
          <th style="text-align: right">hum</th>
          <th style="text-align: left">room</th>
          <th style="text-align: right">temp</th>
          <th style="text-align: left">time</th>
      </tr>
  </thead>
  <tbody>
      <tr>
          <td style="text-align: right">0</td>
          <td style="text-align: right">0</td>
          <td style="text-align: right">35.9</td>
          <td style="text-align: left">Kitchen</td>
          <td style="text-align: right">21</td>
          <td style="text-align: left">2022-01-01 08:00:00</td>
      </tr>
      <tr>
          <td style="text-align: right">1</td>
          <td style="text-align: right">0</td>
          <td style="text-align: right">36.2</td>
          <td style="text-align: left">Kitchen</td>
          <td style="text-align: right">23</td>
          <td style="text-align: left">2022-01-01 09:00:00</td>
      </tr>
      <tr>
          <td style="text-align: right">2</td>
          <td style="text-align: right">0</td>
          <td style="text-align: right">36.1</td>
          <td style="text-align: left">Kitchen</td>
          <td style="text-align: right">22.7</td>
          <td style="text-align: left">2022-01-01 10:00:00</td>
      </tr>
      <tr>
          <td style="text-align: right">3</td>
          <td style="text-align: right">0</td>
          <td style="text-align: right">36</td>
          <td style="text-align: left">Kitchen</td>
          <td style="text-align: right">22.4</td>
          <td style="text-align: left">2022-01-01 11:00:00</td>
      </tr>
      <tr>
          <td style="text-align: right">4</td>
          <td style="text-align: right">0</td>
          <td style="text-align: right">36</td>
          <td style="text-align: left">Kitchen</td>
          <td style="text-align: right">22.5</td>
          <td style="text-align: left">2022-01-01 12:00:00</td>
      </tr>
      <tr>
          <td style="text-align: right">5</td>
          <td style="text-align: right">1</td>
          <td style="text-align: right">36.5</td>
          <td style="text-align: left">Kitchen</td>
          <td style="text-align: right">22.8</td>
          <td style="text-align: left">2022-01-01 13:00:00</td>
      </tr>
      <tr>
          <td style="text-align: right">6</td>
          <td style="text-align: right">1</td>
          <td style="text-align: right">36.3</td>
          <td style="text-align: left">Kitchen</td>
          <td style="text-align: right">22.8</td>
          <td style="text-align: left">2022-01-01 14:00:00</td>
      </tr>
      <tr>
          <td style="text-align: right">7</td>
          <td style="text-align: right">3</td>
          <td style="text-align: right">36.2</td>
          <td style="text-align: left">Kitchen</td>
          <td style="text-align: right">22.7</td>
          <td style="text-align: left">2022-01-01 15:00:00</td>
      </tr>
      <tr>
          <td style="text-align: right">8</td>
          <td style="text-align: right">7</td>
          <td style="text-align: right">36</td>
          <td style="text-align: left">Kitchen</td>
          <td style="text-align: right">22.4</td>
          <td style="text-align: left">2022-01-01 16:00:00</td>
      </tr>
      <tr>
          <td style="text-align: right">9</td>
          <td style="text-align: right">9</td>
          <td style="text-align: right">36</td>
          <td style="text-align: left">Kitchen</td>
          <td style="text-align: right">22.7</td>
          <td style="text-align: left">2022-01-01 17:00:00</td>
      </tr>
      <tr>
          <td style="text-align: right">10</td>
          <td style="text-align: right">18</td>
          <td style="text-align: right">36.9</td>
          <td style="text-align: left">Kitchen</td>
          <td style="text-align: right">23.3</td>
          <td style="text-align: left">2022-01-01 18:00:00</td>
      </tr>
      <tr>
          <td style="text-align: right">11</td>
          <td style="text-align: right">22</td>
          <td style="text-align: right">36.6</td>
          <td style="text-align: left">Kitchen</td>
          <td style="text-align: right">23.1</td>
          <td style="text-align: left">2022-01-01 19:00:00</td>
      </tr>
      <tr>
          <td style="text-align: right">12</td>
          <td style="text-align: right">26</td>
          <td style="text-align: right">36.5</td>
          <td style="text-align: left">Kitchen</td>
          <td style="text-align: right">22.7</td>
          <td style="text-align: left">2022-01-01 20:00:00</td>
      </tr>
      <tr>
          <td style="text-align: right">13</td>
          <td style="text-align: right">0</td>
          <td style="text-align: right">35.9</td>
          <td style="text-align: left">Living Room</td>
          <td style="text-align: right">21.1</td>
          <td style="text-align: left">2022-01-01 08:00:00</td>
      </tr>
      <tr>
          <td style="text-align: right">14</td>
          <td style="text-align: right">0</td>
          <td style="text-align: right">35.9</td>
          <td style="text-align: left">Living Room</td>
          <td style="text-align: right">21.4</td>
          <td style="text-align: left">2022-01-01 09:00:00</td>
      </tr>
      <tr>
          <td style="text-align: right">15</td>
          <td style="text-align: right">0</td>
          <td style="text-align: right">36</td>
          <td style="text-align: left">Living Room</td>
          <td style="text-align: right">21.8</td>
          <td style="text-align: left">2022-01-01 10:00:00</td>
      </tr>
      <tr>
          <td style="text-align: right">16</td>
          <td style="text-align: right">0</td>
          <td style="text-align: right">36</td>
          <td style="text-align: left">Living Room</td>
          <td style="text-align: right">22.2</td>
          <td style="text-align: left">2022-01-01 11:00:00</td>
      </tr>
      <tr>
          <td style="text-align: right">17</td>
          <td style="text-align: right">0</td>
          <td style="text-align: right">35.9</td>
          <td style="text-align: left">Living Room</td>
          <td style="text-align: right">22.2</td>
          <td style="text-align: left">2022-01-01 12:00:00</td>
      </tr>
      <tr>
          <td style="text-align: right">18</td>
          <td style="text-align: right">0</td>
          <td style="text-align: right">36</td>
          <td style="text-align: left">Living Room</td>
          <td style="text-align: right">22.4</td>
          <td style="text-align: left">2022-01-01 13:00:00</td>
      </tr>
      <tr>
          <td style="text-align: right">19</td>
          <td style="text-align: right">0</td>
          <td style="text-align: right">36.1</td>
          <td style="text-align: left">Living Room</td>
          <td style="text-align: right">22.3</td>
          <td style="text-align: left">2022-01-01 14:00:00</td>
      </tr>
      <tr>
          <td style="text-align: right">20</td>
          <td style="text-align: right">1</td>
          <td style="text-align: right">36.1</td>
          <td style="text-align: left">Living Room</td>
          <td style="text-align: right">22.3</td>
          <td style="text-align: left">2022-01-01 15:00:00</td>
      </tr>
      <tr>
          <td style="text-align: right">21</td>
          <td style="text-align: right">4</td>
          <td style="text-align: right">36</td>
          <td style="text-align: left">Living Room</td>
          <td style="text-align: right">22.4</td>
          <td style="text-align: left">2022-01-01 16:00:00</td>
      </tr>
      <tr>
          <td style="text-align: right">22</td>
          <td style="text-align: right">5</td>
          <td style="text-align: right">35.9</td>
          <td style="text-align: left">Living Room</td>
          <td style="text-align: right">22.6</td>
          <td style="text-align: left">2022-01-01 17:00:00</td>
      </tr>
      <tr>
          <td style="text-align: right">23</td>
          <td style="text-align: right">9</td>
          <td style="text-align: right">36.2</td>
          <td style="text-align: left">Living Room</td>
          <td style="text-align: right">22.8</td>
          <td style="text-align: left">2022-01-01 18:00:00</td>
      </tr>
      <tr>
          <td style="text-align: right">24</td>
          <td style="text-align: right">14</td>
          <td style="text-align: right">36.3</td>
          <td style="text-align: left">Living Room</td>
          <td style="text-align: right">22.5</td>
          <td style="text-align: left">2022-01-01 19:00:00</td>
      </tr>
      <tr>
          <td style="text-align: right">25</td>
          <td style="text-align: right">17</td>
          <td style="text-align: right">36.4</td>
          <td style="text-align: left">Living Room</td>
          <td style="text-align: right">22.2</td>
          <td style="text-align: left">2022-01-01 20:00:00</td>
      </tr>
  </tbody>
</table>
  </div>
</div>
</div>

</div>

<!---------------------------- END PYTHON CONTENT ----------------------------->

  1. In the influxdb_go_client directory you created in the Write data section, create a new file named query.go.

  2. In query.go, enter the following sample code:

    package main

import (
  "context"
  "fmt"
  "io"
  "os"
  "time"
  "text/tabwriter"

  "github.com/InfluxCommunity/influxdb3-go/v2/influxdb3"
)

func Query() error {

   // INFLUX_TOKEN is an environment variable you created
   // for your API read token.
  token := os.Getenv("INFLUX_TOKEN")

  // Instantiate the client.
  client, err := influxdb3.New(influxdb3.ClientConfig{
    Host:     "https://cloud2.influxdata.com

“, Token: token, Database: “get-started”, })

  // Close the client when the function returns.
  defer func(client *influxdb3.Client) {
    err := client.Close()
    if err != nil {
      panic(err)
    }
  }(client)

// Define the query.
query := SELECT * FROM home WHERE time &gt;= '2022-01-01T08:00:00Z' AND time &lt;= '2022-01-01T20:00:00Z'


// Execute the query.
iterator, err := client.Query(context.Background(), query)


if err != nil {
panic(err)
}


w := tabwriter.NewWriter(io.Discard, 4, 4, 1, ’ ‘, 0)
w.Init(os.Stdout, 0, 8, 0, ‘\t’, 0)
fmt.Fprintln(w, "time\troom\ttemp\thum\tco")


// Iterate over rows and prints column values in table format.
for iterator.Next() {
row := iterator.Value()
// Use Go time package to format unix timestamp
// as a time with timezone layout (RFC3339).
time := (row["time"].(time.Time)).
Format(time.RFC3339)
fmt.Fprintf(w, "%s\t%s\t%d\t%.1f\t%.1f\n",
time, row["room"], row["co"], row["hum"], row["temp"])
}


w.Flush()
return nil
}





The sample code does the following:

1.  Imports the following packages:

    - `context`
    - `fmt`
    - `io`
    - `os`
    - `text/tabwriter`
    - `github.com/InfluxCommunity/influxdb3-go/v2/influxdb3`

2.  Defines a `Query()` function that does the following:

    1.  Instantiates `influx.Client` with InfluxDB credentials.
      
        - **`Host`**: your InfluxDB Cloud Serverless region URL
        - **`Database`**: The name of your InfluxDB Cloud Serverless bucket
        - **`Token`**: an [API token](/influxdb3/cloud-serverless/admin/tokens/) with read permission on the specified bucket.
          _Store this in a secret store or environment variable to avoid
          exposing the raw token string._

    2.  Defines a deferred function to close the client after execution.
    3.  Defines a string variable for the SQL query.

    4.  Calls the `influxdb3.Client.Query(sql string)` method and passes the
        SQL string to query InfluxDB.
        The `Query(sql string)` method returns an `iterator` for data in the
        response stream.
    5.  Iterates over rows, formats the timestamp as an
        [RFC3339 timestamp](/influxdb3/cloud-serverless/reference/glossary/#rfc3339-timestamp),and prints the data in table format to stdout.
</code></pre>
<ol start="3">
<li>
<p>In your editor, open the <code>main.go</code> file you created in the
<a href="/influxdb3/cloud-serverless/get-started/write/?t=Go#write-line-protocol-to-influxdb">Write data section</a> and insert code to call the <code>Query()</code> function&ndash;for example:</p>


<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-go" data-lang="go"><span class="line"><span class="cl"><span class="kn">package</span><span class="w"> </span><span class="nx">main</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="kd">func</span><span class="w"> </span><span class="nf">main</span><span class="p">()</span><span class="w"> </span><span class="p">{</span><span class="w">	
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nf">WriteLineProtocol</span><span class="p">()</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nf">Query</span><span class="p">()</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="p">}</span></span></span></code></pre></div>
</li>
<li>
<p>In your terminal, enter the following command to install the necessary
packages, build the module, and run the program:</p>
<!--pytest.mark.skip-->


<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-sh" data-lang="sh"><span class="line"><span class="cl">go mod tidy <span class="o">&amp;&amp;</span> go run influxdb_go_client</span></span></code></pre></div>
<p>The program executes the <code>main()</code> function that writes the data and prints the query results to the console.</p>
</li>
</ol>

</div>

<!------------------------------ END GO CONTENT ------------------------------->

This tutorial assumes you installed Node.js and npm, and created an influxdb_js_client npm project as described in the Write data section.

  1. In your terminal or editor, change to the influxdb_js_client directory you created in the Write data section.

  2. If you haven’t already, install the @influxdata/influxdb3-client JavaScript client library as a dependency to your project:

    npm install --save @influxdata/influxdb3-client

  3. Create a file named query.mjs. The .mjs extension tells the Node.js interpreter that you’re using ES6 module syntax.

  4. Inside of query.mjs, enter the following sample code:

    // query.mjs
import {InfluxDBClient} from '@influxdata/influxdb3-client'
import {tableFromArrays} from 'apache-arrow';

/**
* Set InfluxDB credentials.
*/
const host = "https://cloud2.influxdata.com

“; const database = ‘get-started’; /** * INFLUX_TOKEN is an environment variable you assigned to your * API READ token value. */ const token = process.env.INFLUX_TOKEN;

/**
* Query InfluxDB with SQL using the JavaScript client library.
*/
export async function querySQL() {
  /**
  * Instantiate an InfluxDBClient
  */
  const client = new InfluxDBClient({host, token})
  const sql = `
  SELECT *
  FROM home
  WHERE time >= '2022-01-01T08:00:00Z'
    AND time <= '2022-01-01T20:00:00Z'
  `

const data = {time: [], room: [], co: [], hum: [], temp: []};
const result = client.query(query, database);


for await (const row of result) {
data.time.push(new Date(row._time))
data.room.push(row.room)
data.co.push(row.co);
data.hum.push(row.hum);
data.temp.push(row.temp);
}


console.table([…tableFromArrays(data)])


client.close()
}





The sample code does the following:

1.  Imports the following:
    - `InfluxDBClient` class
    - `tableFromArrays` function
2.  Calls `new InfluxDBClient()` and passes a `ClientOptions` object to instantiate a client configured
    with InfluxDB credentials.

    - **`host`**: your InfluxDB Cloud Serverless region URL
    - **`token`**: an [API token](/influxdb3/cloud-serverless/admin/tokens/)
      with _read_ permission on the bucket you want to query.
      _Store this in a secret store or environment variable to avoid exposing
      the raw token string._

  3.  Defines a string variable (`sql`) for the SQL query.
  4.  Defines an object (`data`) with column names for keys and array values for storing row data.
  5.  Calls the `InfluxDBClient.query()` method with the following arguments:

      - **`sql`**: the query to execute
      - **`database`**: the name of the InfluxDB Cloud Serverless bucket to query
      
      `query()` returns a stream of row vectors.
  6.  Iterates over rows and adds the column data to the arrays in `data`.
  7.  Passes `data` to the Arrow `tableFromArrays()` function to format the arrays as a table, and then passes the result to the `console.table()` method to output a highlighted table in the terminal.
</code></pre>
<ol start="5">
<li>
<p>Inside of <code>index.mjs</code> (created in the <a href="/influxdb3/cloud-serverless/get-started/write/?t=Nodejs">Write data section</a>), enter the following sample code to import the modules and call the functions:</p>


<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-js" data-lang="js"><span class="line"><span class="cl"><span class="c1">// index.mjs
</span></span></span><span class="line"><span class="cl"><span class="kr">import</span> <span class="p">{</span> <span class="nx">writeLineProtocol</span> <span class="p">}</span> <span class="nx">from</span> <span class="s2">&#34;./write.mjs&#34;</span><span class="p">;</span>
</span></span><span class="line"><span class="cl"><span class="kr">import</span> <span class="p">{</span> <span class="nx">querySQL</span> <span class="p">}</span> <span class="nx">from</span> <span class="s2">&#34;./query.mjs&#34;</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="cm">/**
</span></span></span><span class="line"><span class="cl"><span class="cm">* Execute the client functions.
</span></span></span><span class="line"><span class="cl"><span class="cm">*/</span>
</span></span><span class="line"><span class="cl"><span class="kr">async</span> <span class="kd">function</span> <span class="nx">main</span><span class="p">()</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">  <span class="cm">/** Write line protocol data to InfluxDB. */</span>
</span></span><span class="line"><span class="cl">  <span class="kr">await</span> <span class="nx">writeLineProtocol</span><span class="p">();</span>
</span></span><span class="line"><span class="cl">  <span class="cm">/** Query data from InfluxDB using SQL. */</span>
</span></span><span class="line"><span class="cl">  <span class="kr">await</span> <span class="nx">querySQL</span><span class="p">();</span>
</span></span><span class="line"><span class="cl"><span class="p">}</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nx">main</span><span class="p">();</span></span></span></code></pre></div>
</li>
<li>
<p>In your terminal, execute <code>index.mjs</code> to write to and query InfluxDB Cloud Serverless:</p>
<!--pytest.mark.skip-->


<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-sh" data-lang="sh"><span class="line"><span class="cl">node index.mjs</span></span></code></pre></div>
</li>
</ol>
<!---------------------------- END NODE.JS CONTENT --------------------------->

</div>

  1. In the influxdb_csharp_client directory you created in the Write data section, create a new file named Query.cs.

  2. In Query.cs, enter the following sample code:

    // Query.cs

using System;
using System.Threading.Tasks;
using InfluxDB3.Client;
using InfluxDB3.Client.Query;

namespace InfluxDBv3;

public class Query
{
  /**
    * Queries an InfluxDB database (bucket) using the C# .NET client
    * library.
    **/
  public static async Task QuerySQL()
  {
    /** INFLUX_TOKEN is an environment variable you assigned to your
      * API READ token value.
      **/
    string? token = System.Environment
        .GetEnvironmentVariable("INFLUX_TOKEN");

    /**
      * Instantiate the InfluxDB client with credentials.
      **/
    using var client = new InfluxDBClient(
        "https://cloud2.influxdata.com

“, token: token, database: database);

    const string sql = @"
      SELECT time, room, temp, hum, co
      FROM home
      WHERE time >= '2022-01-01T08:00:00Z'
      AND time <= '2022-01-01T20:00:00Z'
    ";

Console.WriteLine(&quot;{0,-30}{1,-15}{2,-15}{3,-15}{4,-15}&quot;,
    &quot;time&quot;, &quot;room&quot;, &quot;co&quot;, &quot;hum&quot;, &quot;temp&quot;);

await foreach (var row in client.Query(query: sql))
{
  {
    /** 
      * Iterate over rows and print column values in table format.
      * Format the timestamp as sortable UTC format.
      */
    Console.WriteLine(&quot;{0,-30:u}{1,-15}{4,-15}{3,-15}{2,-15}&quot;,
        row[0], row[1], row[2], row[3], row[4]);
  }
}
Console.WriteLine();

}
}

The sample code does the following:

1.  Imports the following classes:

    - `System`
    - `System.Threading.Tasks`;
    - `InfluxDB3.Client`;
    - `InfluxDB3.Client.Query`;

2.  Defines a `Query` class with a `QuerySQL()` method that does the following:

    1.  Calls the `new InfluxDBClient()` constructor to instantiate a client configured
          with InfluxDB credentials.
      
        - **`host`**: your InfluxDB Cloud Serverless region URL.
        - **`token`**: an [API token](/influxdb3/cloud-serverless/admin/tokens/) with read permission on the specified bucket.
          _Store this in a secret store or environment variable to avoid exposing the raw token string._
        - **`database`**: the name of the InfluxDB Cloud Serverless bucket to query
    2.  Defines a string variable for the SQL query.
    3.  Calls the `InfluxDBClient.Query()` method to send the query request with the SQL string.
        `Query()` returns batches of rows from the response stream as a two-dimensional array--an array of rows in which each row is an array of values.
    4.  Iterates over rows and prints the data in table format to stdout.
</code></pre>
<ol start="3">
<li>
<p>In your editor, open the <code>Program.cs</code> file you created in the
<a href="/influxdb3/cloud-serverless/get-started/write/?t=C%23#write-line-protocol-to-influxdb">Write data section</a> and insert code to call the <code>Query()</code> function&ndash;for example:</p>


<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-c#" data-lang="c#"><span class="line"><span class="cl"><span class="c1">// Program.cs</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="k">using</span> <span class="nn">System</span><span class="p">;</span>
</span></span><span class="line"><span class="cl"><span class="k">using</span> <span class="nn">System.Threading.Tasks</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="k">namespace</span> <span class="nn">InfluxDBv3</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="kd">public</span> <span class="k">class</span> <span class="nc">Program</span>
</span></span><span class="line"><span class="cl"><span class="p">{</span>
</span></span><span class="line"><span class="cl">  <span class="kd">public</span> <span class="kd">static</span> <span class="kd">async</span> <span class="n">Task</span> <span class="n">Main</span><span class="p">()</span>
</span></span><span class="line"><span class="cl">  <span class="p">{</span>
</span></span><span class="line"><span class="cl">    <span class="k">await</span> <span class="n">Write</span><span class="p">.</span><span class="n">WriteLineProtocol</span><span class="p">();</span>
</span></span><span class="line"><span class="cl">    <span class="k">await</span> <span class="n">Query</span><span class="p">.</span><span class="n">QuerySQL</span><span class="p">();</span>
</span></span><span class="line"><span class="cl">  <span class="p">}</span>
</span></span><span class="line"><span class="cl"><span class="p">}</span></span></span></code></pre></div>
</li>
<li>
<p>To build and execute the program and query InfluxDB Cloud Serverless,
enter the following commands in your terminal:</p>
<!--pytest.mark.skip-->


<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-sh" data-lang="sh"><span class="line"><span class="cl">dotnet run</span></span></code></pre></div>
</li>
</ol>

</div>

<!------------------------------ END C# CONTENT ------------------------------->

This tutorial assumes using Maven version 3.9, Java version >= 15, and an influxdb_java_client Maven project created in the Write data section.

  1. In your terminal or editor, change to the influxdb_java_client directory you created in the Write data section.

  2. Inside of the src/main/java/com/influxdbv3 directory, create a new file named Query.java.

  3. In Query.java, enter the following sample code:

    // Query.java
package com.influxdbv3;

import com.influxdb.v3.client.InfluxDBClient;
import java.util.stream.Stream;

/**
  * Queries an InfluxDB database (bucket) using the Java client
  * library.
  **/
public final class Query {

    private Query() {
        //not called
    }

    /**
    * @throws Exception
    */
    public static void querySQL() throws Exception {
        /**
        * Query using SQL.
        */

        /** Set InfluxDB credentials. **/
        final String host = "https://cloud2.influxdata.com

“; final String database = “get-started”;

        /** INFLUX_TOKEN is an environment variable you assigned to your
          * API READ token value.
          **/
        final char[] token = (System.getenv("INFLUX_TOKEN")).
        toCharArray();

    try (InfluxDBClient client = InfluxDBClient.getInstance(host,
    token, database)) {
        String sql =
            &quot;&quot;&quot;
            SELECT time, room, temp, hum, co
            FROM home
            WHERE time &gt;= '2022-01-01T08:00:00Z'
            AND time &lt;= '2022-01-01T20:00:00Z'&quot;&quot;&quot;;

        String layoutHead = &quot;| %-16s | %-12s | %-6s | %-6s | %-6s |%n&quot;;
        System.out.printf(
        &quot;--------------------------------------------------------%n&quot;);
        System.out.printf(layoutHead,
        &quot;time&quot;, &quot;room&quot;, &quot;co&quot;, &quot;hum&quot;, &quot;temp&quot;);
        System.out.printf(
        &quot;--------------------------------------------------------%n&quot;);
        String layout = &quot;| %-16s | %-12s | %-6s | %.1f | %.1f |%n&quot;;

        try (Stream&lt;Object[]&gt; stream = client.query(sql)) {
            stream.forEach(row -&gt; 
              System.out.printf(layout,
              row[0], row[1], row[4], row[3], row[2])
            );
        }
    }
}

}

The sample code does the following:

1.  Assigns the `com.influxdbv3` package name (the Maven **groupId**).
2.  Imports the following classes:

    - `com.influxdb.v3.client.InfluxDBClient`
    - `java.util.stream.Stream`

3.  Defines a `Query` class with a `querySQL()` method that does the following:

    1.  Calls `InfluxDBClient.getInstance()` to instantiate a client configured
        with InfluxDB credentials.

        - **`host`**: your InfluxDB Cloud Serverless region URL
        - **`database`**: the name of the InfluxDB Cloud Serverless bucket to write to
        - **`token`**: an [API token](/influxdb3/cloud-serverless/admin/tokens/) with _read_ access to the specified bucket.
          _Store this in a secret store or environment variable to avoid exposing the raw token string._
    2.  Defines a string variable (`sql`) for the SQL query.
    3.  Defines a Markdown table format layout for headings and data rows.
    4.  Calls the `InfluxDBClient.query()` method to send the query request with the SQL string.
        `query()` returns a stream of rows.
    5.  Iterates over rows and prints the data in the specified layout to stdout.
</code></pre>
<ol start="4">
<li>
<p>In your editor, open the <code>src/main/java/com/influxdbv3/App.java</code> file and replace its contents with the following sample code:</p>


<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="c1">// App.java</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="kn">package</span><span class="w"> </span><span class="nn">com.influxdbv3</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="cm">/**
</span></span></span><span class="line"><span class="cl"><span class="cm">* Execute the client functions.
</span></span></span><span class="line"><span class="cl"><span class="cm">*
</span></span></span><span class="line"><span class="cl"><span class="cm">*/</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="kd">public</span><span class="w"> </span><span class="kd">class</span> <span class="nc">App</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="cm">/**
</span></span></span><span class="line"><span class="cl"><span class="cm">    * @param args
</span></span></span><span class="line"><span class="cl"><span class="cm">    * @throws Exception
</span></span></span><span class="line"><span class="cl"><span class="cm">    */</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">public</span><span class="w"> </span><span class="kd">static</span><span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="nf">main</span><span class="p">(</span><span class="kd">final</span><span class="w"> </span><span class="n">String</span><span class="o">[]</span><span class="w"> </span><span class="n">args</span><span class="p">)</span><span class="w"> </span><span class="kd">throws</span><span class="w"> </span><span class="n">Exception</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="c1">// Write data to InfluxDB 3.</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">Write</span><span class="p">.</span><span class="na">writeLineProtocol</span><span class="p">();</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="c1">// Run the SQL query.</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">Query</span><span class="p">.</span><span class="na">querySQL</span><span class="p">();</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="p">}</span></span></span></code></pre></div>
<ul>
<li>The <code>App</code>, <code>Write</code>, and <code>Query</code> classes belong to the <code>com.influxdbv3</code> package (your project <strong>groupId</strong>).</li>
<li><code>App</code> defines a <code>main()</code> function that calls <code>Write.writeLineProtocol()</code> and <code>Query.querySQL()</code>.</li>
</ul>
</li>
<li>
<p>In your terminal or editor, use Maven to install dependencies and compile the project code&ndash;for example:</p>
<!--pytest.mark.skip-->


<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-sh" data-lang="sh"><span class="line"><span class="cl">mvn compile</span></span></code></pre></div>
</li>
<li>
<p>Set the <code>--add-opens=java.base/java.nio=ALL-UNNAMED</code> Java option for your environment.
The Apache Arrow Flight library requires this setting for access to the <a href="https://docs.oracle.com/en/java/javase/20/docs/api/java.base/java/nio/package-summary.html">java.nio API package</a>.</p>
<p>For example, enter the following command in your terminal:</p>
<p><strong>Linux/MacOS</strong></p>


<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-sh" data-lang="sh"><span class="line"><span class="cl"><span class="nb">export</span> <span class="nv">MAVEN_OPTS</span><span class="o">=</span><span class="s2">&#34;--add-opens=java.base/java.nio=ALL-UNNAMED&#34;</span></span></span></code></pre></div>
<p><strong>Windows PowerShell</strong></p>


<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-powershell" data-lang="powershell"><span class="line"><span class="cl"><span class="nv">$env:MAVEN_OPTS</span><span class="p">=</span><span class="s2">&#34;--add-opens=java.base/java.nio=ALL-UNNAMED&#34;</span></span></span></code></pre></div>
</li>
<li>
<p>To run the app to write to and query InfluxDB Cloud Serverless, execute <code>App.main()</code>&ndash;for example, using Maven:</p>
 <!--pytest.mark.skip-->


<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-sh" data-lang="sh"><span class="line"><span class="cl">mvn exec:java -Dexec.mainClass<span class="o">=</span><span class="s2">&#34;com.influxdbv3.App&#34;</span></span></span></code></pre></div>
</li>
</ol>

</div>

<!------------------------------ END JAVA CONTENT ------------------------------->

Query results

View 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 Cloud Serverless, see the Query data in InfluxDB section of documentation.

Was this page helpful?

Thank you for your feedback!

© 2026 InfluxData, Inc.

Select your InfluxDB Cloud Serverless region

Select your InfluxDB Cloud Serverless region and we’ll customize code examples for you.

AWS

For more information, see InfluxDB Cloud Serverless regions.

Thank you for your feedback!

Let us know what we can do better:

Thank you!

No thanks

Select a new date

Select a date in your bucket's retention period.

Update

New in InfluxDB 3.8

Key enhancements in InfluxDB 3.8 and the InfluxDB 3 Explorer 1.6.

See the Blog Post

InfluxDB 3.8 is now available for both Core and Enterprise, alongside the 1.6 release of the InfluxDB 3 Explorer UI. This release is focused on operational maturity and making InfluxDB easier to deploy, manage, and run reliably in production.

For more information, check out:

InfluxDB Docker latest tag changing to InfluxDB 3 Core

On April 7, 2026, the latest tag for InfluxDB Docker images will point to InfluxDB 3 Core. To avoid unexpected upgrades, use specific version tags in your Docker deployments.

If using Docker to install and run InfluxDB, the latest tag will point to InfluxDB 3 Core. To avoid unexpected upgrades, use specific version tags in your Docker deployments. For example, if using Docker to run InfluxDB v2, replace the latest version tag with a specific version tag in your Docker pull command–for example:

docker pull influxdb:2

InfluxDB Cloud Serverless

You are currently viewing documentation specific to InfluxDB Cloud Serverless powered by the v3 storage engine, which offers different functionality than InfluxDB Cloud powered by the TSM storage engine.

Are you using InfluxDB Cloud Serverless? How to find out?

Visit your organization's homepage and find the following at the bottom of the right column:

InfluxDB Cloud Serverless Storage Engine Version 3
Yes – I'm using InfluxDB Cloud Serverless No – I'm using InfluxDB Cloud (TSM)