文档

在 InfluxQL 中使用参数化查询

InfluxDB 集群版中的参数化查询允许您动态且安全地更改查询中的值。如果您的应用程序代码允许用户输入来定制查询中的值或表达式,请使用参数化查询以确保未经验证的输入严格作为数据处理,而不是作为代码执行。

参数化查询

  • 帮助防止注入攻击,如果输入被作为代码执行,可能会发生此类攻击
  • 有助于使查询更具可重用性

防止注入攻击

有关安全和查询参数化的更多信息,请参阅OWASP SQL 注入预防备忘单

InfluxDB v3 中的参数化查询是包含一个或多个命名参数占位符的 InfluxQL 或 SQL 查询——这些占位符代表输入数据。

参数仅在 WHERE 表达式中受支持

InfluxDB v3 支持 WHERE 子句中的 谓词表达式 中的参数。参数值必须是 允许的参数数据类型 之一。

如果您在其他表达式或子句中使用参数,例如函数参数、SELECT 或 GROUP BY,则您的查询可能不会按预期工作。

在 WHERE 表达式中使用参数

您可以在 WHERE 子句的 谓词表达式 中使用参数——例如,以下查询包含一个 $temp 参数

SELECT * FROM measurement WHERE temp > $temp

在执行查询时,您指定参数名称-值对。分配给参数的值必须是 参数数据类型 之一。

{"temp": 22.0}

InfluxDB查询器解析带占位符的查询文本,然后生成查询计划,用您提供的值替换占位符。这种将查询结构与输入数据分离的做法确保输入被视为允许的数据类型之一,而不是可执行的代码。

参数数据类型

参数值可以是以下数据类型之一

  • Null
  • 布尔值
  • 无符号整数(u_int64
  • 整数(int64
  • 双精度浮点数(float64
  • 字符串

数据类型示例

{
  "string": "Living Room",
  "double": 3.14,
  "unsigned_integer": 1234,
  "integer": -1234,
  "boolean": false,
  "null": Null,
}

时间表达式

为了参数化时间范围,用参数替换时间戳文字——例如

SELECT *
FROM home
WHERE time >= $min_time

对于参数值,将时间戳文字指定为字符串——例如

// Assign a timestamp string literal to the min_time parameter.
parameters := influxdb3.QueryParameters{
    "min_time": "2022-01-01 00:00:00.00",
}

InfluxDB将按以下方式执行查询

SELECT *
FROM home
WHERE time >= '2022-01-01 00:00:00.00'

与参数不兼容

如果您为以下内容使用参数,则查询可能不会按预期工作

  • WHERE子句以外的子句中,例如SELECTGROUP BY
  • 作为函数参数,例如avg($temp)
  • 代替标识符,例如列名或表名
  • 代替持续时间文字,例如time > now() - $min_duration

参数化 SQL 查询

示例数据

以下示例使用入门家庭传感器数据。要运行示例查询并返回结果,请在运行示例查询之前,将样本数据写入您的InfluxDB集群数据库。

要使用参数化查询,请按照以下步骤操作

  1. 在查询文本中,使用$parameter语法引用参数名——例如,以下查询包含$room$min_temp参数占位符

    SELECT *
    FROM home
    WHERE time > now() - 7d
    AND temp >= $min_temp
    AND room = $room
    
  2. 为每个参数名提供一个值。如果您未为参数分配值,InfluxDB将返回错误。提供参数值的语法取决于您使用的客户端——例如

    // Define a QueryParameters struct--a map of parameters to input values.
    parameters := influxdb3.QueryParameters{
        "room": "Kitchen",
        "min_temp": 20.0,
    }
    

InfluxDB收到您的请求并解析查询后,将按以下方式执行查询

SELECT *
FROM home
WHERE time > now() - 7d
AND temp >= 20.0
AND room = 'Kitchen'

执行参数化 InfluxQL 查询

示例数据

以下示例使用入门家庭传感器数据。要运行示例查询并返回结果,请在运行示例查询之前,将样本数据写入您的InfluxDB集群数据库。

使用 InfluxDB Flight RPC 客户端

使用InfluxDB v3原生的Flight RPC协议和受支持的客户端,您可以发送参数化查询和参数名-值对列表。支持参数化查询的InfluxDB Flight客户端将在Flight票据的params字段中传递参数名-值对。

以下示例显示了如何使用客户端库执行参数化InfluxQL查询

import (
    "context"
    "fmt"
    "io"
    "os"
    "text/tabwriter"
    "time"
    "github.com/apache/arrow/go/v14/arrow"
    "github.com/InfluxCommunity/influxdb3-go/influxdb3"
)

func Query(query string, parameters influxdb3.QueryParameters,
 options influxdb3.QueryOptions) error {
    url := os.Getenv("INFLUX_HOST")
    token := os.Getenv("INFLUX_TOKEN")
    database := os.Getenv("INFLUX_DATABASE")

    // Instantiate the influxdb3 client.
    client, err := influxdb3.New(influxdb3.ClientConfig{
        Host:     url,
        Token:    token,
        Database: database,
    })

    if err != nil {
        panic(err)
    }

    // Ensure the client is closed after the Query function finishes.
    defer func(client *influxdb3.Client) {
        err := client.Close()
        if err != nil {
            panic(err)
        }
    }(client)

    // Call the client's QueryWithParameters function.
    // Provide the query, parameters, and the InfluxQL QueryType option.
    iterator, err := client.QueryWithParameters(context.Background(), query,
    parameters, influxdb3.WithQueryType(options.QueryType))

    // Create a buffer for storing rows as you process them.
    w := tabwriter.NewWriter(io.Discard, 4, 4, 1, ' ', 0)
    w.Init(os.Stdout, 0, 8, 0, '\t', 0)

    fmt.Fprintf(w, "time\troom\tco\thum\ttemp\n")

    // Format and write each row to the buffer.
    // Process each row as key-value pairs.
    for iterator.Next() {
        row := iterator.Value()
        // Use Go arrow and time packages to format unix timestamp
        // as a time with timezone layout (RFC3339 format)
        time := (row["time"].(arrow.Timestamp)).
                ToTime(arrow.Nanosecond).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
}

func main() {
    // Use the $placeholder syntax in a query to reference parameter placeholders
    // for input data.
    // The following InfluxQL query contains the placeholders $room and $min_temp.
    query := `
        SELECT *
        FROM home
        WHERE time > now() - 7d
        AND temp >= $min_temp
        AND room = $room`

    // Define a QueryParameters struct--a map of placeholder names to input values.
    parameters := influxdb3.QueryParameters{
        "room": "Kitchen",
        "min_temp": 20.0,
    }

    Query(query, parameters, influxdb3.QueryOptions{
        QueryType: influxdb3.InfluxQL,
    })
}

参数化查询的客户支持

  • 并非所有InfluxDB v3 Flight客户端都支持参数化查询。
  • InfluxDB目前不支持Flight SQL或Flight SQL客户端的参数化查询或DataFusion预编译语句。
  • InfluxDB v3 SQL和InfluxQL参数化查询不受InfluxDB v1和v2客户端支持。

不支持

目前,InfluxDB集群中的参数化查询不提供以下功能

  • 支持DataFusion预编译语句
  • 查询缓存、优化或性能优势

这个页面有帮助吗?

感谢您的反馈!


Flux 的未来

Flux 将进入维护模式。您可以在不更改代码的情况下继续像现在一样使用它。

阅读更多

InfluxDB v3 增强功能及 InfluxDB 集群版现已上市

包括更快的查询性能和管理工具在内的新功能推动了 InfluxDB v3 产品线的进步。InfluxDB 集群版现已上市。

InfluxDB v3 性能和功能

InfluxDB v3 产品线在查询性能方面取得了显著提升,并提供了新的管理工具。这些增强功能包括一个操作仪表板,用于监控您的 InfluxDB 集群的健康状况,InfluxDB 云专用版的单点登录 (SSO) 支持,以及新的令牌和数据库管理 API。

了解新的 v3 增强功能


InfluxDB 集群版上市

InfluxDB 集群版现已上市,为您在自行管理堆栈中提供 InfluxDB v3 的功能。

与我们谈论 InfluxDB 集群版