Choosing a Client Library When Developing with InfluxDB 3.0

By Gary Fowler / Product
Aug 18, 2023

A common question we get asked is “what client library should I use with InfluxDB 3.0?”

This question isn’t as simple as it may seem. It can get confusing when deciding which client library to use while developing applications to write to and query from InfluxDB. There are numerous options to choose from and the answer may differ based on the following criteria:

• the version of InfluxDB you currently use or used in the past
• the type of APIs you are looking for (query, write, management)
• the query language you want to use (SQL, InfluxQL, Flux)

Today, there are three versions of InfluxDB client libraries available:

• v1 Client Library
• v2 Client Library
• v3 Lightweight Client Library

At first, this seems like an easy answer. Use the v1 Client Library with InfluxDB 1.x; use the v2 Client Library with InfluxDB 2.x; and use the v3 Lightweight Client Library with InfluxDB 3.0, right? Uh, kinda, sorta, no, maybe?

Ok, well, you might be thinking that instead of making a decision based on the version, you should base it on your preferred query language. In other words, if you want to use InfluxQL, use the v1 Client Library; if you want to use Flux, use the v2 Client Library; and if you want to use SQL, use the v3 Lightweight Client Library? That is sort of accurate as well, but still not completely the case in all situations.

The v3 lightweight client libraries

We call the v3 client libraries “lightweight” because they only implement the two functions that most of our customers use: query and write. And we focused on the five languages our customers most commonly use with InfluxDB: Python, Golang, Java, JavaScript, and C#.

The v1 and v2 APIs provided administrative APIs as well (create databases, set retention periods, etc.). InfluxDB 3.0 separates data plane and control plane tooling, so you perform administrative functions within the InfluxDB 3.0 Cloud UI (if using InfluxDB Cloud Serverless) or the influxctl command line utility (if using InfluxDB Cloud Dedicated or InfluxDB Clustered).

Unless your application relies on the administrative APIs, the Lightweight Client Libraries should be all you need.

For new InfluxDB customers that have not already written applications using the v1 or v2 client libraries, the v3 Lightweight Client Libraries are the best choice.

It is not, however, your only choice. You can actually choose “none of the above” and use Apache Arrow Flight for querying and the REST API for writing instead.

The Apache Arrow Flight Library

One option for querying InfluxDB 3.0 is to use the Apache Arrow Flight framework. InfluxDB 3.0 utilizes Apache Arrow and the Apache Arrow ecosystem (Arrow, DataFusion, Flight, Flight SQL, Parquet). This means you can use any Apache Arrow Flight client to query InfluxDB over gRPC. The v3 Lightweight Client Libraries also use Arrow Flight, so technically, you are using it either way.

Apache Arrow Flight is a high performance client-server framework built upon gRPC and the IPC format. The InfluxDB 3.0 implementation of Flight allows you to query using SQL or InfluxQL by simply changing the language flag within the Flight ticket. Flight utilizes the Arrow in-memory columnar data format. When you retrieve data via Flight, you get columnar data, similar to a pandas DataFrame, that you can efficiently query, analyze, and transform using third-party tools like pyarrow and pandas for Python or Polars for Python, JavaScript, and Rust.

Here are some examples of the nifty things you can do with the Flight library and Python:

• Raw Flight example using Pandas and Plotly (Python)

• Query types (Python)

• InfluxDB 3.0 Python Client Cookbook (Uses Flight under the hood)

• Using the Batch capability of Flight

So if you decide to use Apache Flight directly (instead of using the v3 Lightweight Client library), you might be asking, “Is Apache Flight the only thing I need?” In a blog post devoid of yes or no answers, we have to answer again, “maybe”. If you only need to query, then yes, the Apache Flight library may be the only thing you need.

Many customers fall into this category because they use the InfluxDB Telegraf agent to ingest (write) data into the database and they only query data programmatically. But if you also need to write data to InfluxDB from within your application code, you’ll find the InfluxDB client libraries very convenient for writing and querying.

You can use both the Arrow Flight library and one of the v1/v2/v3 client libraries together so you could simply use Arrow Flight for querying and the v3 lightweight library for writing. But for most circumstances, using the v3 Lightweight Client Libraries is your best bet, because they already utilize Flight and enable both query and write. As mentioned previously, the v3 Lightweight Client Library uses Arrow Flight, it just makes it a little simpler to use because you don’t have to learn Flight. Instead, the libraries allow you to focus on just the query and write functions with InfluxDB 3.0.

One additional note on this: the Arrow Flight Framework for Python is the most advanced. You will find it easier to use with Python than with the other languages it supports.

The v1 Client Libraries

Some of our existing customers ask, “If I’m using a v1 Client Library today, do I need to convert my code to use the v3 Lightweight Client Library when I move to an InfluxDB 3.0 platform (InfluxDB Cloud Serverless, InfluxDB Cloud Dedicated, InfluxDB Clustered, or, eventually, OSS 3.x)?”

In nearly all cases, the answer to this is “No”. You can continue to use the v1 Client Library for InfluxQL queries and for writes. At one point in our past, we steered customers away from the v1 Client Library, encouraging them to use the v2 Library instead. We are no longer doing that because the v1 Client Libraries are compatible with InfluxDB 3.0. This makes it easy for customers to upgrade to InfluxDB 3.0 without having to change a lot of code.

The other reason to consider the v1 Client Libraries is that they support additional languages over v3, including C++ and PHP. So if you need to use these languages, the v1 Client Library may be your best choice.

The v2 Client Libraries

Ok, as we established above, you can use the v3 Lightweight Client Libraries, the Apache Arrow Flight framework, or the v1 Client Libraries with InfluxDB 3.0. But, what about the v2 Libraries?

Here is where things get a little murkier. The v2 Client Libraries and the v2 Query API (which the v2 libraries use) utilize the Flux query language. While some of our customers love this Influx-developed query language, the majority of our customers said they just don’t have time to learn a new query language and really want us to support SQL. While we were disappointed, we did understand. As a result, we developed InfluxDB 3.0 to support SQL and our time series variation, InfluxQL.

The v2 API is not available for InfluxDB Cloud Dedicated and the upcoming InfluxDB Clustered and OSS 3.0 flavors of InfluxDB 3.0. This means you need to use either the v3 Lightweight Client Library, the Arrow Flight Framework, the v1 Client Library — or some combination thereof — when you move to InfluxDB 3.0.

For InfluxDB Cloud Serverless customers, there is a compatibility layer we can enable for some customers that allows v2/Flux API calls to work in some cases. However, because we optimized InfluxDB 3.0 for SQL and InfluxQL, this compatibility is a translation/conversion and requires re-sorting and other operations to deliver the data in the same format and order that it would come in with previous versions of InfluxDB.

Long story short, the performance isn’t there with the v2 libraries in InfluxDB 3.0. Depending on the volume of data and the breadth of query, you could see timeouts and other anomalies with the v2 libraries. Because of this, we only recommend doing this while you are migrating your workloads to one of the other libraries and your queries from Flux to SQL or InfluxQL.

Still confused or unclear after all of this? Refer to this recommendation table:

You can find the v3 Lightweight client libraries at the following locations:

• Python
• C#
• Go
• Java
• JavaScript

For a deeper dive on the Python v3 Client Libraries, check out this blog from my colleague Jay Clifford.