InfluxDB JavaScript Client

Use the @influxdata/influxdb-client-browser package when developing for browser-based environments or Deno. This package provides the reference InfluxDB 2.x JavaScript client specifically optimized for these runtimes.

Important Compatibility Notes:

• Target Version: This library is designed for InfluxDB 2.x or InfluxDB 1.8+.
• Environment Restriction: Browser distributions use APIs that are incompatible with Node.js. If you are working in a Node.js environment, you must use @influxdata/influxdb-client instead.
• Legacy InfluxDB: For connecting to InfluxDB 1.x instances, use the node-influx library.

The client library is split into two primary functional areas:

@influxdata/influxdb-client

Used for data plane operations:

• Querying: Use the Flux language to retrieve data.
• Writing: Send data to InfluxDB with features like background batching and automatic retries on failure.

@influxdata/influxdb-client-apis

Used for control plane operations (built on top of the core client):

• Management: Create, modify, delete, or manage buckets, tasks, authorizations, and sources.
• Data Deletion: Delete data from specific buckets.
• Script Execution: Invoke Flux scripts.

The @influxdata/influxdb-client package is the reference JavaScript client for InfluxDB 2.x and InfluxDB 1.8+. It supports both Node.js and browser environments, but you must select the correct package for your runtime to avoid platform API conflicts.

• For Node.js: Use @influxdata/influxdb-client. It provides both CommonJS (main) and ESM (module) distributions.
• For Browsers: Use @influxdata/influxdb-client-browser to import the browser-compatible ESM module.

Important Compatibility Note: This client is designed for InfluxDB 2.x or 1.8+. If you need to connect to older InfluxDB 1.x instances, use the node-influx library instead.

The repository includes examples compatible with Deno.

To query InfluxDB using Flux in Deno, use the query.deno.ts example. The primary difference between the Deno and Node.js versions is the import statement syntax and Deno's built-in TypeScript support.

// Example reference: query.deno.ts

To run the Node.js examples provided in this repository, follow these steps:

1. Prerequisites: Ensure you have Node.js installed (version 18 or higher is recommended).
2. Install dependencies: Run npm install in the examples/ directory.
3. Configure connection: Update the variables in ./env.mjs to match your InfluxDB instance (e.g., URL, Token, Org, Bucket). The file is pre-configured to work with a fresh Docker InfluxDB v2.3 OSS GA installation.
4. Execute examples: Most examples are executable directly. If an example fails to run, use the command npm run esr EXAMPLE.ts (replacing EXAMPLE.ts with the specific filename).

npm install
# After configuring env.mjs
npm run esr write.mjs

To interact with InfluxDB 2.x, install the core client package. Use @influxdata/influxdb-client for Node.js environments. If you are targeting browsers, Deno, or Ionic, use @influxdata/influxdb-client-browser instead.

# For Node.js
$ npm install --save @influxdata/influxdb-client
$ yarn add @influxdata/influxdb-client
$ pnpm add @influxdata/influxdb-client

# For Browser, Deno, or Ionic
$ npm install --save @influxdata/influxdb-client-browser

If the OpenAPI definitions have changed, you can re-generate the client APIs using yarn regenerate. This process performs the following steps:

1. Fetches the latest versions of OpenAPI files.
2. Re-generates src/generated/types.ts and resources/operations.json using oats.
3. Generates the APIs in src/generated from resources/operations.json.
4. Validates the generated output.

After regeneration, you should create a new git branch containing the regenerated code and submit a pull request to review the changes.

The @influxdata/influxdb-client-giraffe package provides a queryToTable function designed to bridge InfluxDB (v2) and Giraffe visualizations. It executes a Flux query and transforms the results into a Table format that Giraffe components can consume directly as data input.

import {InfluxDB} from '@influxdata/influxdb-client'
import {queryToTable} from '@influxdata/influxdb-client-giraffe'
import {newTable, Plot} from '@influxdata/giraffe'

// ... setup InfluxDB client ...
const queryApi = new InfluxDB({url, token}).getQueryApi(org)

// Convert Flux query results to a Giraffe Table
const table = await queryToTable(
  queryApi,
  'from(bucket: "my-bucket") |> range(start: -30d)',
  newTable,
  {maxTableRows: 5000}
)

// Use the resulting table in a Giraffe Plot component
// <Plot config={{table, ...}}></Plot>

If you need to manage InfluxDB domain objects (such as buckets, tasks, authorizations, or sources), delete data from buckets, or invoke Flux scripts, you must also install the @influxdata/influxdb-client-apis package.

$ npm install --save @influxdata/influxdb-client-apis
$ yarn add @influxdata/influxdb-client-apis
$ pnpm add @influxdata/influxdb-client-apis

Selecting the right library depends on your InfluxDB version and environment: