使用 InfluxDB 3.0 开发时选择客户端库

作者：Gary Fowler / 产品
2023 年 8 月 18 日

导航至

我们经常被问到的一个问题是“我应该将哪个客户端库与 InfluxDB 3.0 一起使用？”

这个问题并不像看起来那么简单。当决定在开发应用程序以写入和查询 InfluxDB 时应使用哪个客户端库时，可能会感到困惑。有许多选项可供选择，答案可能会因以下标准而异

  • 您当前使用或过去使用的 InfluxDB 版本
  • 您正在寻找的 API 类型（查询、写入、管理）
  • 您想要使用的查询语言（SQL、InfluxQL、Flux）

今天，有三个版本的 InfluxDB 客户端库可用

  • v1 客户端库
  • v2 客户端库
  • v3 轻量级客户端库

乍一看，这似乎是一个简单的答案。将 v1 客户端库与 InfluxDB 1.x 一起使用；将 v2 客户端库与 InfluxDB 2.x 一起使用；并将 v3 轻量级客户端库与 InfluxDB 3.0 一起使用，对吗？嗯，有点，有点，不，也许？

好的，嗯，您可能会认为，与其根据版本做出决定，不如根据您首选的查询语言做出决定。换句话说，如果您想使用 InfluxQL，请使用 v1 客户端库；如果您想使用 Flux，请使用 v2 客户端库；如果您想使用 SQL，请使用 v3 轻量级客户端库？这在某种程度上也是准确的，但并非在所有情况下都完全如此。

v3 轻量级客户端库

我们将 v3 客户端库称为“轻量级”，因为它们仅实现了我们大多数客户使用的两个功能：查询和写入。我们专注于客户最常与 InfluxDB 一起使用的五种语言：Python、Golang、Java、JavaScript 和 C#。

v1 和 v2 API 也提供了管理 API（创建数据库、设置保留期等）。InfluxDB 3.0 分离了数据平面和控制平面工具，因此您可以在 InfluxDB 3.0 Cloud UI（如果使用 InfluxDB Cloud Serverless）或 influxctl 命令行实用程序（如果使用 InfluxDB Cloud Dedicated 或 InfluxDB Clustered）中执行管理功能。

除非您的应用程序依赖于管理 API，否则轻量级客户端库应该能满足您的所有需求。

对于尚未编写使用 v1 或 v2 客户端库的应用程序的新 InfluxDB 客户，v3 轻量级客户端库是最佳选择。

然而，这不是您唯一的选择。您实际上可以选择“以上都不是”，而是使用 Apache Arrow Flight 进行查询，并使用 REST API 进行写入。

Apache Arrow Flight 库

查询 InfluxDB 3.0 的一种选择是使用 Apache Arrow Flight 框架。InfluxDB 3.0 利用 Apache Arrow 和 Apache Arrow 生态系统（Arrow、DataFusion、Flight、Flight SQL、Parquet）。这意味着您可以使用任何 Apache Arrow Flight 客户端通过 gRPC 查询 InfluxDB。v3 轻量级客户端库也使用 Arrow Flight，因此从技术上讲，无论如何您都在使用它。

Apache Arrow Flight 是一个基于 gRPC 和 IPC 格式构建的高性能客户端-服务器框架。InfluxDB 3.0 Flight 的实现允许您通过简单地更改 Flight 票证中的语言标志来使用 SQL 或 InfluxQL 进行查询。Flight 利用 Arrow 内存中的列式数据格式。当您通过 Flight 检索数据时，您会获得列式数据，类似于 pandas DataFrame，您可以使用第三方工具（如 Python 的 pyarrow 和 pandas 或 Python、JavaScript 和 Rust 的 Polars）高效地查询、分析和转换这些数据。

以下是使用 Flight 库和 Python 可以完成的一些巧妙事情的示例

因此，如果您决定直接使用 Apache Flight（而不是使用 v3 轻量级客户端库），您可能会问：“Apache Flight 是我唯一需要的吗？”在一篇没有是或否答案的博客文章中，我们不得不再次回答“也许”。如果您只需要查询，那么是的，Apache Flight 库可能是您唯一需要的。

许多客户属于此类，因为他们使用 InfluxDB Telegraf 代理将数据摄取（写入）到数据库中，并且他们仅以编程方式查询数据。但是，如果您还需要从应用程序代码中将数据写入 InfluxDB，您会发现 InfluxDB 客户端库对于写入和查询非常方便。

您可以同时使用 Arrow Flight 库和一个 v1/v2/v3 客户端库，因此您可以简单地使用 Arrow Flight 进行查询，并使用 v3 轻量级库进行写入。但在大多数情况下，使用 v3 轻量级客户端库是您的最佳选择，因为它们已经使用了 Flight 并同时支持查询和写入。 如前所述，v3 轻量级客户端库使用 Arrow Flight，它只是使其更易于使用，因为您不必学习 Flight。相反，这些库允许您专注于 InfluxDB 3.0 的查询和写入功能。

关于这一点的补充说明：Python 的 Arrow Flight 框架是最先进的。您会发现它在 Python 中比在它支持的其他语言中更容易使用。

v1 客户端库

我们的一些现有客户询问：“如果我今天正在使用 v1 客户端库，当我迁移到 InfluxDB 3.0 平台（InfluxDB Cloud Serverless、InfluxDB Cloud Dedicated、InfluxDB Clustered 或最终的 OSS 3.x）时，我是否需要转换我的代码以使用 v3 轻量级客户端库？”

在几乎所有情况下，答案都是“否”。您可以继续使用 v1 客户端库进行 InfluxQL 查询和写入。在我们过去的某个时候，我们引导客户远离 v1 客户端库，鼓励他们改用 v2 库。我们不再这样做了，因为 v1 客户端库与 InfluxDB 3.0 兼容。这使得客户可以轻松升级到 InfluxDB 3.0，而无需更改大量代码。

考虑 v1 客户端库的另一个原因是，它们比 v3 支持更多语言，包括 C++ 和 PHP。因此，如果您需要使用这些语言，v1 客户端库可能是您的最佳选择。

v2 客户端库

好的，正如我们在上面确定的，您可以将 v3 轻量级客户端库、Apache Arrow Flight 框架或 v1 客户端库与 InfluxDB 3.0 一起使用。但是，v2 库呢？

这里的情况变得有点复杂。v2 客户端库和 v2 查询 API（v2 库使用）使用 Flux 查询语言。虽然我们的一些客户喜欢这种 Influx 开发的查询语言，但我们的大多数客户表示他们没有时间学习新的查询语言，并且真的希望我们支持 SQL。虽然我们感到失望，但我们确实理解。因此，我们开发了 InfluxDB 3.0 以支持 SQL 和我们的时序变体 InfluxQL。

v2 API 不适用于 InfluxDB Cloud Dedicated 以及即将推出的 InfluxDB Clustered 和 OSS 3.0 版本的 InfluxDB 3.0。这意味着当您迁移到 InfluxDB 3.0 时，您需要使用 v3 轻量级客户端库、Arrow Flight 框架、v1 客户端库中的任何一个，或它们的某种组合。

对于 InfluxDB Cloud Serverless 客户，我们可以为某些客户启用兼容性层，允许 v2/Flux API 调用在某些情况下工作。但是，由于我们针对 SQL 和 InfluxQL 优化了 InfluxDB 3.0，因此这种兼容性是一种转换/转换，需要重新排序和其他操作，以按照与先前版本的 InfluxDB 相同的格式和顺序传递数据。

长话短说，v2 库在 InfluxDB 3.0 中的性能不佳。根据数据量和查询范围，您可能会看到 v2 库出现超时和其他异常。因此，我们仅建议在您将工作负载迁移到其他库之一并将查询从 Flux 迁移到 SQL 或 InfluxQL 时才这样做。

经过这一切后仍然感到困惑或不清楚？请参考此推荐表

客户类型 产品 推荐语言 推荐查询库 推荐写入库（如果未使用 Telegraf） 推荐管理工具
首次使用 InfluxDB 的全新客户 InfluxDB Cloud Serverless 使用 SQL 或 InfluxQL 使用 v3 轻量级客户端库；Apache Arrow Flight 是另一种选择 使用 v3 轻量级客户端库 使用 Cloud UI
InfluxDB Cloud Dedicated、InfluxDB Clustered、OSS 3.0 使用 SQL 或 InfluxQL 使用 v3 轻量级客户端库；Apache Arrow Flight 是另一种选择 使用 v3 轻量级客户端库 使用 influxctl 命令行实用程序
使用 InfluxQL 和 v1 客户端库的现有客户 InfluxDB Cloud Serverless 使用 InfluxQL 现有应用程序使用 v1 客户端库，对于未来应用程序，考虑 v3 轻量级客户端库或 Apache Arrow Flight 现有应用程序使用 v1 客户端库，对于未来应用程序，考虑 v3 轻量级客户端库 使用 Cloud UI
InfluxDB Cloud Dedicated、InfluxDB Clustered、OSS 3.0 使用 InfluxQL 现有应用程序使用 v1 客户端库，对于未来应用程序，考虑 v3 轻量级客户端库或 Apache Arrow Flight 现有应用程序使用 v1 客户端库，对于未来应用程序，考虑 v3 轻量级客户端库 使用 influxctl 命令行实用程序
使用 InfluxQL 和 v2 客户端库的现有客户 InfluxDB Cloud Serverless 使用 InfluxQL 或 SQL 仅在短期兼容性中使用 v2 客户端库（如果无法避免）；尽快迁移到 v3 轻量级客户端库、Arrow Flight 或 v1 客户端库 仅在短期兼容性中使用 v2 客户端库（如果无法避免）；尽快迁移到 v3 轻量级客户端库、Arrow Flight 或 v1 客户端库 使用 Cloud UI
使用 InfluxQL 和 v2 客户端库的现有客户 InfluxDB Cloud Dedicated、InfluxDB Clustered、OSS 3.0 使用 InfluxQL 或 SQL 使用 v3 轻量级客户端库、Arrow Flight 或 v1 客户端库；v2 客户端库和 v2 API 将不起作用 使用 v3 轻量级客户端库、Arrow Flight 或 v1 客户端库；v2 客户端库和 v2 API 将不起作用 使用 influxctl 命令行实用程序

您可以在以下位置找到 v3 轻量级客户端库

有关 Python v3 客户端库的更深入探讨，请查看我同事 Jay Clifford 的这篇博客。