3.0版InfluxQL的复兴：配置和使用快速入门指南

作者：Jay Clifford / 产品
2023年6月30日

导航至

如果我们把时钟拨回到2013年9月，我们发布了与InfluxDB一起的InfluxQL。InfluxQL是一种类似于SQL的查询语言，专门设计用于查询时序数据。对于许多用户来说，InfluxQL仍然是他们与InfluxDB交互的主要方式。根据这一反馈，InfluxQL在InfluxDB 3.0中得到了复兴，同时原生支持SQL查询语言。

那么我所说的复兴是指什么呢？好吧，如果你不知道的话，我们是在三个关键的开源项目上构建了InfluxDB 3.0

Apache DataFusion充当InfluxDB 3.0的基础查询引擎，为我们提供原生SQL支持。我们的工程师扩展了查询引擎以原生支持InfluxQL。这允许开发者在使用基于InfluxQL的查询的同时利用Apache Arrow Flight的完整性能。

在这篇博客中，我们将探讨如何通过我们新的v3客户端库利用InfluxQL。我们将讨论如何配置v1 InfluxQL API以用于无服务器和专用服务，这为InfluxQL插件（如Grafana和NodeRed）提供向后兼容性。

v3客户端库

我们目前有五个基于社区的v3客户端库

客户端库 状态 查询语言
C# 就绪 SQL, InfluxQL
Go 就绪 SQL, InfluxQL
Python 就绪 SQL, InfluxQL
Java 就绪 SQL, InfluxQL
JavaScript 就绪 SQL, InfluxQL

这些客户端库都支持使用InfluxDB进行写入和查询。如果您想深入了解它们的当前状态，我强烈建议您查看这篇博客。

让我们看看几个利用新InfluxQL查询功能客户端的示例。

Python

让我们从一个Python示例开始

import influxdb_client_3 as InfluxDBClient3

client = InfluxDBClient3.InfluxDBClient3(
    token="<INSERT TOKEN>",
    host="eu-central-1-1.aws.cloud2.influxdata.com",
    org="6a841c0c08328fb1",
    database="database")

table = client.query(
    query="SELECT * FROM <MEASUREMENT> WHERE time > now() - 4h",
    language="influxql")

print(table.to_pandas())

如您所见，我们创建了一个名为‘client’的新客户端实例。然后我们调用query()，它需要以下参数；

  • 查询：要执行的查询的字符串字面表示。可以是SQL或InfluxQL。

  • 语言：此参数指示您的查询字符串字面量是InfluxQL还是SQL。

注意：将我们的语言参数设置为influxql非常重要，因为SQL是默认查询语言。

Go

接下来，我们看看一个Go示例

import (
  "context"
  "encoding/json"
  "fmt"
  "os"
  "github.com/InfluxCommunity/influxdb3-go/influx"
)

url := os.Getenv("INFLUXDB_URL")
token := os.Getenv("INFLUXDB_TOKEN")
database := os.Getenv("INFLUXDB_DATABASE")

// Create a new client using an InfluxDB server base URL and an authentication token
client, err := influx.New(influx.Configs{
    HostURL: url,
    AuthToken: token,
})
// Close client at the end and escalate error if present
defer func (client *influx.Client)  {
    err := client.Close()
    if err != nil {
        panic(err)
    }
}(client)

query := `SELECT * FROM <MEASUREMENT> WHERE time > now() - 4h`;

iterator, err := client.QueryInfluxQL(context.Background(), database, query, nil)

if err != nil {
    panic(err)
}

for iterator.Next() {
    value := iterator.Value()

    fmt.Printf("avg is %f\n", value["avg"])
    fmt.Printf("max is %f\n", value["max"])
}

在这个例子中，我们遵循Python客户端库的类似做法，只是我们没有使用语言参数，而是使用了client.QueryInfluxQL函数。

JavaScript

最后，让我们考虑一个JavaScript示例

import {InfluxDBClient, Point} from '../index' // replace with @influxdata/influxdb3-client in your project

type Defined<T> = Exclude<T, undefined>

/* allows to throw error as expression */
const throwReturn = <T>(err: Error): Defined<T> => {
  throw err
}

async function main() {
  // Use environment variables to initialize client
  const url = 'INFLUXDB_URL'
  const token = 'INFLUXDB_TOKEN'
  const database = 'INFLUXDB_DATABASE'

  // Create a new client using an InfluxDB server base URL and an authentication token
  const client = new InfluxDBClient({url, token})

   // Prepare flightsql query
    const query = `SELECT * FROM <MEASUREMENT> WHERE time > now() - 4h`
    // Execute query
    const queryResult = await client.query(database, query, ‘influxql’)

    for await (const row of queryResult) {
      console.log(`avg is ${row.get('avg')}`)
      console.log(`max is ${row.get('max')}`)
    }
  } catch (err) {
    console.error(err)
  } finally {
    await client.close()
  }
}

main()

与Python库类似，我们提供凭证来实例化客户端。我们调用client.query()，包括将influxql作为queryType参数。

v1 InfluxQL API

我们介绍了客户端库，这些库利用 Arrow Flight 与 InfluxDB 3.0 进行通信。这对于构建新应用非常有效，但它不提供一种通用的通信方法来支持当前的 InfluxQL 应用和插件，因为这些插件使用 InfluxDB API 运行。这就是 v1 API 发挥作用的地方。

v1 API 包含一个 v1 查询端点，它接收传入的查询请求，将其传递给查询调度器，然后执行查询。然后，结果会传递回 v1 API 端点，并返回以完成 API 请求。

注意：撰写此博客时，Serverless 和 Dedicated 之间的 v1 API 设置存在明显差异。

InfluxDB Cloud Dedicated

由于 v1 API 桥接器，每个创建的数据库都内置于 v1 API 兼容。

InfluxDB Cloud Dedicated

InfluxDB Cloud Serverless

Serverless 目前需要创建 DBRP 映射来初始化针对 InfluxDB 3.0 数据库的 v1 API InfluxQL 查询的执行。

InfluxDB Cloud Serverless

接下来，让我们看看如何为 Serverless 配置 DBRP 映射。

使用 DBRP 配置桥接器（Serverless）

注意：由于此功能处于积极开发中，请始终检查 文档 以获取更新。Cloud Dedicated 用户可以跳过此步骤！

目前，您必须手动为要通过 v1 API 桥接器使用的每个数据库创建 DBRPs。您有两种方法可以这样做

  1. InfluxDB CLI：使用此方法，您必须在您的宿主计算机上安装 InfluxDB CLI。确保您还配置了一个 初始配置配置文件，该配置文件指向您的 InfluxDB 3.0 实例。接下来运行以下命令
    influx v1 dbrp create \
  --token API_TOKEN \
  --db DATABASE_NAME \
  --rp RETENTION_POLICY_NAME \
  --bucket-id BUCKET_ID \
  --default
    • API 令牌进行认证。我们建议将您的令牌设置为您的活动 InfluxDB 连接配置，在 influx CLI 中，这样您就不必在每个命令中添加这些参数。要设置您的活动 InfluxDB 配置，请参阅 influx config set。
    • 要映射的数据库名称
    • 要映射的保留策略名称
    • 要映射的 Bucket ID
    • 默认 — 此标志将提供的保留策略设置为数据库的默认保留策略。
  2. InfluxDB API：如果您希望直接与 API 交互，您可以通过以下 curl 请求这样做
    curl --request POST https://us-west-2-1.aws.cloud2.influxdata.com/api/v2/dbrps \
  --header "Authorization: Token API_TOKEN" \
  --header 'Content-type: application/json' \
  --data '{
        "bucketID": "BUCKET_ID",
        "database": "DATABASE_NAME",
        "default": true,
        "orgID": "ORG_ID",
        	   "retention_policy": "RETENTION_POLICY_NAME"
     		 }'

如您所见，curl 需要与 CLI 相同的参数。如果您想在 Serverless 中映射许多数据库，我强烈建议设置 InfluxDB CLI 并利用此 bash 脚本

#!/bin/bash

# Run influx bucket list and parse the output
influx bucket list | awk '
BEGIN {
    # Skip the header line
    getline
}
{
    # Extract the values
    bucket_id = $1
    database_name = $2

    # Construct and run the influx v1 dbrp create command
    cmd = "influx v1 dbrp create --db " database_name " --rp " database_name " --bucket-id " bucket_id " --default"
    system(cmd)
}'

这将映射每个数据库/存储桶到其自己的 DBRP。

Grafana InfluxQL 数据源

现在我们已经创建了我们第一个 v1 映射，让我们利用它在 Grafana 中的 InfluxQL 数据源中。让我们分两个阶段查看配置

阶段 1：认证

在这个插件配置的阶段，我们必须修改三个参数（这不包括创建 名称 并指定 InfluxQL 为您的 查询语言）。

Authentication

URL：请确保在此表单中添加您的协议和域名。一个示例可能如下所示：https://eu-central-1-1.aws.cloud2.influxdata.com

基本认证：切换到 true。

用户/密码： 用户名可以是任何字符串；它不用于认证目的，但不能为空。密码必须是具有足够权限查询您打算使用的数据库的InfluxDB API令牌。

第2阶段：数据库详细信息

在这个最终阶段，您只有一个参数可以更改。请注意，配置不使用用户名和密码参数。

Database details

数据库： 指定您希望查询的数据库的名称。

Node-RED 插件

让我们再看一个例子——Node-RED 的 node-red-contrib-influxdb 插件。我们社区成员的贡献使得InfluxDB在Node-RED中既可以查询也可以写入。使用v1 API，我们可以再次使用这个插件。让我们将设置分为两个阶段

阶段 1：认证

与Grafana数据源一样，我们首先需要配置到v1桥接器的连接和认证。为此，我们有几个参数要配置

stage-1-Authentication

版本： 确保将其设置为1.X

主机 & 端口： 去掉域名URL中的任何协议（https://）并指定端口‘443’。

数据库： 要查询的数据库的名称。

用户/密码： 用户名可以是任何字符串；它不用于认证目的，但不能为空。密码必须是具有足够权限查询您打算使用的数据库的InfluxDB API令牌。

启用安全： 确保启用SSL/TLS

第2阶段：查询详细信息

现在您可以在Node-RED中构建您的查询。有两个参数需要注意

Stage-2 Query details

时间精度： 确保根据存储的时间戳适当地设置此参数。

查询： 提供您的InfluxQL查询。

要点总结

InfluxQL已回归，并且比以往任何时候都要强大。当使用v3客户端库时，InfluxQL的高级用户可以继续使用该语言，同时获得InfluxDB 3.0和向量化、列式DataFusion查询引擎的性能提升。v1 API还为广泛使用的生态系统产品（如Grafana和Node-RED）提供了所需的向后兼容性阶梯。

现在是一些直言不讳的事实——InfluxQL仍在积极开发中，因此v1 InfluxQL还没有像样的功能表示。我的建议是查看InfluxQL参考文档并查看当前可能的功能。目前，它支持大多数核心查询功能或很快将支持。我的行动呼吁是将您的InfluxQL应用程序指向InfluxDB 3.0并告诉我们您在社区中的体验。在以后的博客文章中，我们将深入探讨一些核心的InfluxQL功能。