feat: query structured

.markdownlint.yml

@@ -1,5 +1,6 @@
 {
   "MD013": false,
+  "MD024": false,
   "MD033": {
     "allowed_elements": [ "a", "img", "p", "details", "summary" ]
   },

CHANGELOG.md

@@ -1,5 +1,9 @@
 ## 0.3.0 [unreleased]
 
+### Features
+
+1. [#89](https://github.com/InfluxCommunity/influxdb3-js/pull/89): Add structured query support
+
 ## 0.2.0 [2023-08-11]
 
 ### Features

README.md

@@ -65,18 +65,18 @@ export INFLUXDB_TOKEN="<token>"
 
 ### powershell
 
-```console
-set INFLUXDB_URL=<url>
-set INFLUXDB_DATABASE=<database>
-set INFLUXDB_TOKEN=<token>
+```powershell
+$env:INFLUXDB_URL = "<url>"
+$env:INFLUXDB_DATABASE = "<database>"
+$env:INFLUXDB_TOKEN = "<token>"
 ```
 
 ### cmd
 
-```powershell
-$env:INFLUXDB_URL "<url>"
-$env:INFLUXDB_DATABASE "<database>"
-$env:INFLUXDB_TOKEN "<token>"
+```console
+set INFLUXDB_URL=<url>
+set INFLUXDB_DATABASE=<database>
+set INFLUXDB_TOKEN=<token>
 ```
 
 </details>
@@ -138,6 +138,23 @@ for await (const row of queryResult) {
 }
 ```
 
+or use typesafe `PointValues` structure with `client.queryPoints`
+
+```ts
+const queryPointsResult = client.queryPoints(
+    query,
+    database,
+    queryType,
+    'stat'
+)
+
+for await (const row of queryPointsResult) {
+    console.log(`avg is ${row.getField('avg', 'float')}`)
+    console.log(`max is ${row.getField('max', 'float')}`)
+    console.log(`lp: ${row.toLineProtocol()}`)
+}
+```
+
 ## Examples
 
 For more advanced usage, see [examples](https://github.com/InfluxCommunity/influxdb3-js/blob/HEAD/examples/README.md).

examples/README.md

@@ -1,8 +1,7 @@
 ## Examples
 
-### Basic
-
 - [IOxExample](https://github.com/InfluxCommunity/influxdb3-js/blob/HEAD/examples/basic/README.md) - How to use write and query data from InfluxDB IOx
+- [Downsampling](https://github.com/InfluxCommunity/influxdb3-js/blob/HEAD/downsampling/basic/README.md) - How to use queries to structure data for downsampling
 
 ### Browser
 

examples/basic/README.md

@@ -18,7 +18,7 @@ set environment variables.
 - `INFLUXDB_TOKEN` read/write token generated in cloud
 - `INFLUXDB_DATABASE` name of database e.g .*`my-database`*
 
-For simplicity you can use dotenv library to load environment variables in this example. Create `.env` file and paste your variables as follows:
+For simplicity, you can use dotenv library to load environment variables in this example. Create `.env` file and paste your variables as follows:
 
 ```conf
 INFLUXDB_URL="<url>"

examples/basic/src/index.ts

@@ -1,4 +1,4 @@
-import {InfluxDBClient, Point, PointRecord} from '@influxdata/influxdb3-client'
+import {InfluxDBClient, Point} from '@influxdata/influxdb3-client'
 
 type Defined<T> = Exclude<T, undefined>
 
@@ -24,30 +24,32 @@ async function main() {
 
   try {
     // Write point
-    const p = new Point('stat')
-      .tag('unit', 'temperature')
-      .floatField('avg', 24.5)
-      .floatField('max', 45.0)
-      .timestamp(new Date())
+    const p = Point.measurement('stat')
+      .setTag('unit', 'temperature')
+      .setFloatField('avg', 24.5)
+      .setFloatField('max', 45.0)
+      .setTimestamp(new Date())
     await client.write(p, database)
 
-    // Write record
-    const sensorData: PointRecord = {
-      measurement: 'stat',
-      tags: {
-        unit: 'temperature',
-      },
-      fields: {
-        avg: 28,
-        max: 40.3,
-      },
-      timestamp: new Date(),
+    // Write point as template with anonymous fields object
+    const pointTemplate = Object.freeze(
+      Point.measurement('stat').setTag('unit', 'temperature')
+    )
+
+    const sensorData = {
+      avg: 28,
+      max: 40.3,
     }
-    await client.write([sensorData], database)
+    const p2 = pointTemplate
+      .copy()
+      .setFields(sensorData)
+      .setTimestamp(new Date())
+
+    await client.write(p2, database)
 
     // Or write directly line protocol
-    const line = `stat,unit=temperature avg=20.5,max=43.0`
-    await client.write(line, database)
+    const lp = `stat,unit=temperature avg=20.5,max=43.0`
+    await client.write(lp, database)
 
     // Prepare flightsql query
     const query = `
@@ -67,6 +69,18 @@ async function main() {
       console.log(`avg is ${row.avg}`)
       console.log(`max is ${row.max}`)
     }
+
+    // Execute query again as points
+    const queryPointsResult = client.queryPoints(
+      query,
+      database,
+      queryType
+    )
+
+    for await (const row of queryPointsResult) {
+      console.log(`avg is ${row.getField('avg', 'float')}`)
+      console.log(`max is ${row.getField('max', 'float')}`)
+    }
   } catch (err) {
     console.error(err)
   } finally {

examples/browser/src/main.ts

@@ -56,14 +56,14 @@ view.setOnRandomize(() => {
 
 view.setOnWrite(async () => {
   const data = view.getWriteInput()
-  const p = new Point('stat')
-    .tag('Device', data['Device'])
-    .floatField('Temperature', data['Temperature'])
-    .floatField('Humidity', data['Humidity'])
-    .floatField('Pressure', data['Pressure'])
-    .intField('CO2', data['CO2'])
-    .intField('TVOC', data['TVOC'])
-    .timestamp(new Date())
+  const p = Point.measurement('stat')
+    .setTag('Device', data['Device'])
+    .setFloatField('Temperature', data['Temperature'])
+    .setFloatField('Humidity', data['Humidity'])
+    .setFloatField('Pressure', data['Pressure'])
+    .setIntField('CO2', data['CO2'])
+    .setIntField('TVOC', data['TVOC'])
+    .setTimestamp(new Date())
 
   try {
     view.setWriteInfo('writing')

examples/downsampling/README.md

@@ -0,0 +1,32 @@
+## Downsampling Example
+
+- [index.ts](./src/index.ts) - How to use queries to structure data for downsampling
+
+## prerequisites
+
+- `node` and `yarn` installed
+
+- build influxdb-client: *(in project root directory)*
+  - run `yarn install`
+  - run `yarn build`
+
+## Usage
+
+set environment variables.
+
+- `INFLUXDB_URL` region of your influxdb cloud e.g. *`https://us-east-1-1.aws.cloud2.influxdata.com/`*
+- `INFLUXDB_TOKEN` read/write token generated in cloud
+- `INFLUXDB_DATABASE` name of database e.g .*`my-database`*
+
+For simplicity, you can use dotenv library to load environment variables in this example. Create `.env` file and paste your variables as follows:
+
+```conf
+INFLUXDB_URL="<url>"
+INFLUXDB_DATABASE="<database>"
+INFLUXDB_TOKEN="<token>"
+```
+
+### Run example
+
+- run `yarn install`
+- run `yarn dev`

examples/downsampling/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "influxdb3-client-example-downsampling",
+  "main": "index.js",
+  "license": "MIT",
+  "private": true,
+  "scripts": {
+    "dev": "ts-node -r dotenv/config ./src/index.ts"
+  },
+  "dependencies": {
+    "@influxdata/influxdb3-client": "link:../../packages/client"
+  },
+  "devDependencies": {
+    "dotenv": "^16.3.1",
+    "ts-node": "^10.9.1",
+    "typescript": "^5.1.3"
+  }
+}

examples/downsampling/src/index.ts

@@ -0,0 +1,84 @@
+import {InfluxDBClient} from '@influxdata/influxdb3-client'
+
+/* get environment value or throw error if missing */
+const getEnv = (variableName: string): string => {
+  if (process.env[variableName] == null)
+    throw new Error(`missing ${variableName} environment variable`)
+  return process.env[variableName] as string
+}
+
+/* eslint-disable no-console */
+async function main() {
+  //
+  // Use environment variables to initialize client
+  //
+  const host = getEnv('INFLUXDB_URL')
+  const token = getEnv('INFLUXDB_TOKEN')
+  const database = getEnv('INFLUXDB_DATABASE')
+
+  //
+  // Create a new client using an InfluxDB server base URL and an authentication token
+  //
+  const client = new InfluxDBClient({host, token, database})
+
+  try {
+    //
+    // Write data
+    //
+    await client.write(`stat,unit=temperature avg=24.5,max=45.0`)
+
+    await new Promise((resolve) => setTimeout(resolve, 1000))
+    await client.write(`stat,unit=temperature avg=28,max=40.3`)
+
+    await new Promise((resolve) => setTimeout(resolve, 1000))
+    await client.write(`stat,unit=temperature avg=20.5,max=49.0`)
+
+    //
+    // Query downsampled data
+    //
+    const downSamplingQuery = `\
+    SELECT
+      date_bin('5 minutes', "time") as window_start,
+      AVG("avg") as avg,
+      MAX("max") as max
+    FROM "stat"
+    WHERE
+      "time" >= now() - interval '1 hour'
+    GROUP BY window_start
+    ORDER BY window_start ASC;`
+
+    //
+    // Execute downsampling query into pointValues
+    //
+    const queryPointsResult = client.queryPoints(
+      downSamplingQuery,
+      database,
+      'sql'
+    )
+
+    for await (const row of queryPointsResult) {
+      const timestamp = new Date(row.getFloatField('window_start') as number)
+      console.log(
+        `${timestamp.toISOString()}: avg is ${row.getField(
+          'avg',
+          'float'
+        )}, max is ${row.getField('max', 'float')}`
+      )
+
+      //
+      // write back downsampled date to 'stat_downsampled' measurement
+      //
+      const downSampledPoint = row
+        .asPoint('stat_downsampled')
+        .setTimestamp(timestamp)
+
+      await client.write(downSampledPoint, database)
+    }
+  } catch (err) {
+    console.error(err)
+  } finally {
+    await client.close()
+  }
+}
+
+main()

examples/downsampling/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "target": "es2018",
+    "lib": ["es2018"],
+    "strict": true,
+    "moduleResolution": "node",
+    "esModuleInterop": true
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["*.js"]
+}