Influxdata
/
docs-v2
mirror of https://github.com/influxdata/docs-v2.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

updated client lib docs, resolves #1890

pull/1893/head
Scott Anderson 2020-11-25 12:16:34 -07:00
parent b22f6e7d32
commit 6472a83bce
5 changed files with 5 additions and 511 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
content/influxdb/cloud/tools/client-libraries/_index.md
View File

@ -14,12 +14,4 @@ menu:
influxdb/cloud/tags: [client libraries]
---
InfluxDB client libraries are language-specific packages that integrate with the InfluxDB v2 API.
The following **InfluxDB v2** client libraries are available:
{{% note %}}
These client libraries are in active development and may not be feature-complete.
This list will continue to grow as more client libraries are released.
{{% /note %}}
{{< children type="list" >}}
{{< duplicate-oss >}}

191
content/influxdb/cloud/tools/client-libraries/go.md
View File

@ -14,193 +14,4 @@ aliases:
- /influxdb/cloud/reference/api/client-libraries/go/
---
Use the [InfluxDB Go client library](https://github.com/influxdata/influxdb-client-go) to integrate InfluxDB into Go scripts and applications.
This guide presumes some familiarity with Go and InfluxDB.
If just getting started, see [Get started with InfluxDB](/influxdb/cloud/get-started/).
## Before you begin
1. [Install Go 1.3 or later](https://golang.org/doc/install).
2. Download the client package in your $GOPATH and build the package.
```sh
# Download the InfluxDB Go client package
go get github.com/influxdata/influxdb-client-go
# Build the package
go build
```
3. Ensure that InfluxDB is running and you can connect to it.
For information about what URL to use to connect to InfluxDB OSS or InfluxDB Cloud, see [InfluxDB URLs](/influxdb/cloud/reference/urls/).
## Boilerplate for the InfluxDB Go Client Library
Use the Go library to write and query data from InfluxDB.
1. In your Go program, import the necessary packages and specify the entry point of your executable program.
```go
package main
import (
"context"
"fmt"
"time"
influxdb2 "github.com/influxdata/influxdb-client-go"
)
```
2. Define variables for your InfluxDB [bucket](/influxdb/cloud/organizations/buckets/), [organization](/influxdb/cloud/organizations/), and [token](/influxdb/cloud/security/tokens/).
```go
bucket := "example-bucket"
org := "example-org"
token := "example-token"
// Store the URL of your InfluxDB instance
url := "https://cloud2.influxdata.com"
```
3. Create the the InfluxDB Go client and pass in the `url` and `token` parameters.
```go
client := influxdb2.NewClient(url, token)
```
4. Create a **write client** with the `WriteApiBlocking` method and pass in the `org` and `bucket` parameters.
```go
writeApi := client.WriteApiBlocking(org, bucket)
```
5. To query data, create an InfluxDB **query client** and pass in your InfluxDB `org`.
```go
queryApi := client.QueryApi(org)
```
## Write data to InfluxDB with Go
Use the Go library to write data to InfluxDB.
1. Create a [point](/influxdb/cloud/reference/glossary/#point) and write it to InfluxDB using the `WritePoint` method of the API writer struct.
2. Close the client to flush all pending writes and finish.
```go
p := influxdb2.NewPoint("stat",
map[string]string{"unit": "temperature"},
map[string]interface{}{"avg": 24.5, "max": 45},
time.Now())
writeApi.WritePoint(context.Background(), p)
client.Close()
```
### Complete example write script
```go
func main() {
bucket := "example-bucket"
org := "example-org"
token := "example-token"
// Store the URL of your InfluxDB instance
url := "https://cloud2.influxdata.com"
// Create new client with default option for server url authenticate by token
client := influxdb2.NewClient(url, token)
// User blocking write client for writes to desired bucket
writeApi := client.WriteApiBlocking(org, bucket)
// Create point using full params constructor
p := influxdb2.NewPoint("stat",
map[string]string{"unit": "temperature"},
map[string]interface{}{"avg": 24.5, "max": 45},
time.Now())
// Write point immediately
writeApi.WritePoint(context.Background(), p)
// Ensures background processes finishes
client.Close()
}
```
## Query data from InfluxDB with Go
Use the Go library to query data to InfluxDB.
1. Create a Flux query and supply your `bucket` parameter.
```js
from(bucket:"<bucket>")
|> range(start: -1h)
|> filter(fn: (r) => r._measurement == "stat")
```
The query client sends the Flux query to InfluxDB and returns the results as a FluxRecord object with a table structure.
**The query client includes the following methods:**
- `Query`: Sends the Flux query to InfluxDB.
- `Next`: Iterates over the query response.
- `TableChanged`: Identifies when the group key changes.
- `Record`: Returns the last parsed FluxRecord and gives access to value and row properties.
- `Value`: Returns the actual field value.
```go
result, err := queryApi.Query(context.Background(), `from(bucket:"<bucket>")|> range(start: -1h) |> filter(fn: (r) => r._measurement == "stat")`)
if err == nil {
for result.Next() {
if result.TableChanged() {
fmt.Printf("table: %s\n", result.TableMetadata().String())
}
fmt.Printf("value: %v\n", result.Record().Value())
}
if result.Err() != nil {
fmt.Printf("query parsing error: %s\n", result.Err().Error())
}
} else {
panic(err)
}
```
**The FluxRecord object includes the following methods for accessing your data:**
- `Table()`: Returns the index of the table the record belongs to.
- `Start()`: Returns the inclusive lower time bound of all records in the current table.
- `Stop()`: Returns the exclusive upper time bound of all records in the current table.
- `Time()`: Returns the time of the record.
- `Value() `: Returns the actual field value.
- `Field()`: Returns the field name.
- `Measurement()`: Returns the measurement name of the record.
- `Values()`: Returns a map of column values.
- `ValueByKey(<your_tags>)`: Returns a value from the record for given column key.
### Complete example query script
```go
func main() {
// Create client
client := influxdb2.NewClient(url, token)
// Get query client
queryApi := client.QueryApi(org)
// Get QueryTableResult
result, err := queryApi.Query(context.Background(), `from(bucket:"my-bucket")|> range(start: -1h) |> filter(fn: (r) => r._measurement == "stat")`)
if err == nil {
// Iterate over query response
for result.Next() {
// Notice when group key has changed
if result.TableChanged() {
fmt.Printf("table: %s\n", result.TableMetadata().String())
}
// Access data
fmt.Printf("value: %v\n", result.Record().Value())
}
// Check for an error
if result.Err() != nil {
fmt.Printf("query parsing error: %s\n", result.Err().Error())
}
} else {
panic(err)
}
// Ensures background processes finishes
client.Close()
}
```
For more information, see the [Go client README on GitHub](https://github.com/influxdata/influxdb-client-go).
{{< duplicate-oss >}}

157
content/influxdb/cloud/tools/client-libraries/js.md
View File

@ -14,159 +14,4 @@ aliases:
- /influxdb/cloud/reference/api/client-libraries/js/
---
Use the [InfluxDB JavaScript client library](https://github.com/influxdata/influxdb-client-js) to integrate InfluxDB into JavaScript scripts and applications. This client supports both client-side (browser) and server-side (NodeJS) environments.
This guide presumes some familiarity with JavaScript, browser environments, and InfluxDB.
If just getting started, see [Get started with InfluxDB](/influxdb/cloud/get-started/).
## Before you begin
1. Install [NodeJS](https://nodejs.org/en/download/package-manager/).
2. Ensure that InfluxDB is running and you can connect to it.
For information about what URL to use to connect to InfluxDB OSS or InfluxDB Cloud, see [InfluxDB URLs](/influxdb/cloud/reference/urls/).
## Easiest way to get started
1. Clone the [examples directory](https://github.com/influxdata/influxdb-client-js/tree/master/examples) in the [influxdb-client-js](https://github.com/influxdata/influxdb-client-js) repo.
2. Navigate to the `examples` directory:
```js
cd examples
```
3. Install `yarn` or `npm` dependencies as needed:
```js
yarn install
npm install
```
3. Update your `./env` and `index.html` with the name of your InfluxDB [bucket](/influxdb/cloud/organizations/buckets/), [organization](/influxdb/cloud/organizations/), [token](/influxdb/cloud/security/tokens/), and `proxy` which relies upon proxy to forward requests to the target InfluxDB.
4. Run the following command to run the application at [http://localhost:3001/examples/index.html]()
```sh
npm run browser
```
## Boilerplate for the InfluxDB Javascript client library
Use the Javascript library to write data to and query data from InfluxDB.
1. To write a data point to InfluxDB using the JavaScript library, import the latest InfluxDB Javascript library in your script.
```js
import {InfluxDB, Point} from 'https://unpkg.com/@influxdata/influxdb-client/dist/index.browser.mjs'
```
2. Define constants for your InfluxDB [bucket](/influxdb/cloud/organizations/buckets/), [organization](/influxdb/cloud/organizations/), [token](/influxdb/cloud/security/tokens/), and `proxy` which relies on a proxy to forward requests to the target InfluxDB instance.
```js
const proxy = '/influx'
const token = 'example-token'
const org = 'example-org'
const bucket = 'example-bucket'
```
3. Instantiate the InfluxDB JavaScript client and pass in the `proxy` and `token` parameters.
```js
const InfluxDB = new InfluxDB({proxy, token})
```
## Write data to InfluxDB with JavaScript
Use the Javascript library to write data to InfluxDB.
1. Use the `getWriteApi` method of the InfluxDB client to create a **write client**. Provide your InfluxDB `org` and `bucket`.
```js
const writeApi = InfluxDB.getWriteApi(org, bucket)
```
The `useDefaultTags` method instructs the write api to use default tags when writing points. Create a [point](/influxdb/cloud/reference/glossary/#point) and write it to InfluxDB using the `writePoint` method. The `tag` and `floatField` methods add key value pairs for the tags and fields, respectively. Close the client to flush all pending writes and finish.
```js
writeApi.useDefaultTags({location: 'browser'})
const point1 = new Point('temperature')
.tag('example', 'index.html')
.floatField('value', 24)
writeApi.writePoint(point1)
console.log(`${point1}`)
writeApi.close()
```
### Complete example write script
```js
const writeApi = new InfluxDB({proxy, token})
const writeApi = influxDB.getWriteApi(org, bucket)
// setup default tags for all writes through this API
writeApi.useDefaultTags({location: 'browser'})
const point1 = new Point('temperature')
.tag('example', 'index.html')
.floatField('value', 24)
writeApi.writePoint(point1)
console.log(` ${point1}`)
// flush pending writes and close writeApi
writeApi
.close()
.then(() => {
console.log('WRITE FINISHED')
})
```
## Query data from InfluxDB with JavaScript
Use the Javascript library to query data from InfluxDB.
1. Use the `getQueryApi` method of the `InfluxDB` client to create a new **query client**. Provide your InfluxDB `org`.
```js
const queryApi = influxDB.getQueryApi(org)
```
2. Create a Flux query (including your `bucket` parameter).
```js
const fluxQuery =
'from(bucket:"<my-bucket>")
|> range(start: 0)
|> filter(fn: (r) => r._measurement == "temperature")'
```
The **query client** sends the Flux query to InfluxDB and returns line table metadata and rows.
3. Use the `next` method to iterate over the rows.
```js
queryApi.queryRows(fluxQuery, {
next(row: string[], tableMeta: FluxTableMetaData) {
const o = tableMeta.toObject(row)
// console.log(JSON.stringify(o, null, 2))
console.log(
`${o._time} ${o._measurement} in '${o.location}' (${o.example}): ${o._field}=${o._value}`
)
}
}
```
### Complete example query script
```js
// performs query and receive line table metadata and rows
// https://v2.docs.influxdata.com/v2.0/reference/syntax/annotated-csv/
queryApi.queryRows(fluxQuery, {
next(row: string[], tableMeta: FluxTableMetaData) {
const o = tableMeta.toObject(row)
// console.log(JSON.stringify(o, null, 2))
console.log(
'${o._time} ${o._measurement} in '${o.location}' (${o.example}): ${o._field}=${o._value}`
)
},
error(error: Error) {
console.error(error)
console.log('\nFinished ERROR')
},
complete() {
console.log('\nFinished SUCCESS')
},
})
```
For more information, see the [JavaScript client README on GitHub](https://github.com/influxdata/influxdb-client-js).
{{< duplicate-oss >}}

156
content/influxdb/cloud/tools/client-libraries/python.md
View File

@ -14,158 +14,4 @@ aliases:
weight: 201
---
Use the [InfluxDB Python client library](https://github.com/influxdata/influxdb-client-python) to integrate InfluxDB into Python scripts and applications.
This guide presumes some familiarity with Python and InfluxDB.
If just getting started, see [Get started with InfluxDB](/influxdb/cloud/get-started/).
## Before you begin
1. Install the InfluxDB Python library:
```sh
pip install influxdb-client
```
2. Visit the URL of your InfluxDB Cloud UI.
## Write data to InfluxDB with Python
We are going to write some data in [line protocol](/influxdb/cloud/reference/syntax/line-protocol/) using the Python library.
1. In your Python program, import the InfluxDB client library and use it to write data to InfluxDB.
```python
import influxdb_client
from influxdb_client.client.write_api import SYNCHRONOUS
```
2. Define a few variables with the name of your [bucket](/influxdb/cloud/organizations/buckets/), [organization](/influxdb/cloud/organizations/), and [token](/influxdb/cloud/security/tokens/).
```python
bucket = "<my-bucket>"
org = "<my-org>"
token = "<my-token>"
# Store the URL of your InfluxDB instance
url="https://cloud2.influxdata.com"
```
3. Instantiate the client. The `InfluxDBClient` object takes three named parameters: `url`, `org`, and `token`. Pass in the named parameters.
```python
client = InfluxDBClient(
url=url,
token=token,
org=org
)
```
The `InfluxDBClient` object has a `write_api` method used for configuration.
4. Instantiate a **write client** using the `client` object and the `write_api` method. Use the `write_api` method to configure the writer object.
```python
write_api = client.write_api(write_options=SYNCHRONOUS)
```
5. Create a [point](/influxdb/cloud/reference/glossary/#point) object and write it to InfluxDB using the `write` method of the API writer object. The write method requires three parameters: `bucket`, `org`, and `record`.
```python
p = influxdb_client.Point("my_measurement").tag("location", "Prague").field("temperature", 25.3)
write_api.write(bucket=bucket, org=org, record=p)
```
### Complete example write script
```python
import influxdb_client
from influxdb_client.client.write_api import SYNCHRONOUS
bucket = "<my-bucket>"
org = "<my-org>"
token = "<my-token>"
# Store the URL of your InfluxDB instance
url="https://cloud2.influxdata.com"
client = influxdb_client.InfluxDBClient(
url=url,
token=token,
org=org
)
write_api = client.write_api(write_options=SYNCHRONOUS)
p = influxdb_client.Point("my_measurement").tag("location", "Prague").field("temperature", 25.3)
write_api.write(bucket=bucket, org=org, record=p)
```
## Query data from InfluxDB with Python
1. Instantiate the **query client**.
```python
query_api = client.query_api()
```
2. Create a Flux query.
```python
query = ‘ from(bucket:"my-bucket")\
|> range(start: -10m)\
|> filter(fn:(r) => r._measurement == "my_measurement")\
|> filter(fn: (r) => r.location == "Prague")\
|> filter(fn:(r) => r._field == "temperature" )‘
```
The query client sends the Flux query to InfluxDB and returns a Flux object with a table structure.
3. Pass the `query()` method two named parameters:`org` and `query`.
```python
result = client.query_api().query(org=org, query=query)
```
4. Iterate through the tables and records in the Flux object.
- Use the `get_value()` method to return values.
- Use the `get_field()` method to return fields.
```python
results = []
for table in result:
for record in table.records:
results.append((record.get_field(), record.get_value()))
print(results)
[(temperature, 25.3)]
```
**The Flux object provides the following methods for accessing your data:**
- `get_measurement()`: Returns the measurement name of the record.
- `get_field()`: Returns the field name.
- `get_values()`: Returns the actual field value.
- `values()`: Returns a map of column values.
- `values.get("<your tag>")`: Returns a value from the record for given column.
- `get_time()`: Returns the time of the record.
- `get_start()`: Returns the inclusive lower time bound of all records in the current table.
- `get_stop()`: Returns the exclusive upper time bound of all records in the current table.
### Complete example query script
```python
query_api = client.query_api()
query = ‘ from(bucket:"my-bucket")\
|> range(start: -10m)\
|> filter(fn:(r) => r._measurement == "my_measurement")\
|> filter(fn: (r) => r.location == "Prague")\
|> filter(fn:(r) => r._field == "temperature" )‘
result = client.query_api().query(org=org, query=query)
results = []
for table in result:
for record in table.records:
results.append((record.get_field(), record.get_value()))
print(results)
[(temperature, 25.3)]
```
For more information, see the [Python client README on GitHub](https://github.com/influxdata/influxdb-client-python).
{{< duplicate-oss >}}

2
content/influxdb/v2.0/tools/client-libraries/python.md
View File

@ -144,7 +144,7 @@ write_api.write(bucket=bucket, org=org, record=p)
- `get_measurement()`: Returns the measurement name of the record.
- `get_field()`: Returns the field name.
- `get_values()`: Returns the actual field value.
- `get_value()`: Returns the actual field value.
- `values()`: Returns a map of column values.
- `values.get("<your tag>")`: Returns a value from the record for given column.
- `get_time()`: Returns the time of the record.