client

package
v1.0.3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 17, 2022 License: MIT Imports: 15 Imported by: 0

README

CnosDB go-client

This is the current Go client API for CnosDB.

Usage

To import into your Go project, run the following command in your terminal: go get github.com/cnosdb/cnosdb/client . Then, in your import declaration section of your Go file, paste the following: import "github.com/cnosdb/cnosdb/client".

Example

The following example creates a new client to the CnosDB host on localhost:8086 and runs a query for the measurement cpu_load from the mydb database.

func ExampleClient_query() {
	c, err := client.NewHTTPClient(client.HTTPConfig{
		Addr: "http://localhost:8086",
	})
	if err != nil {
		fmt.Println("Error creating CnosDB Client: ", err.Error())
	}
	defer func() {
		_ = c.Close()
	}()

	q := client.NewQuery("SELECT count(value) FROM cpu_load", "mydb", "")
	if response, err := c.Query(q); err == nil && response.Error() == nil {
		fmt.Println(response.Results)
	}
}

Documentation

Index

Constants

View Source
const (
	// DEFAULT_HOST is the default host used to connect to an CnosDB instance
	DEFAULT_HOST = "localhost"

	// DEFAULT_PORT is the default port used to connect to an CnosDB instance
	DEFAULT_PORT = 8086

	// DEFAULT_TIMEOUT is the default connection timeout used to connect to an CnosDB instance
	DEFAULT_TIMEOUT = 0
)

Variables

This section is empty.

Functions

This section is empty.

Types

type BatchPoints

type BatchPoints interface {
	// AddPoint adds the given point to the Batch of points.
	AddPoint(p *Point)
	// AddPoints adds the given points to the Batch of points.
	AddPoints(ps []*Point)
	// Points lists the points in the Batch.
	Points() []*Point

	// Precision returns the currently set precision of this Batch.
	Precision() string
	// SetPrecision sets the precision of this batch.
	SetPrecision(s string) error

	// Database returns the currently set database of this Batch.
	Database() string
	// SetDatabase sets the database of this Batch.
	SetDatabase(s string)

	// WriteConsistency returns the currently set write consistency of this Batch.
	WriteConsistency() string
	// SetWriteConsistency sets the write consistency of this Batch.
	SetWriteConsistency(s string)

	// RetentionPolicy returns the currently set retention policy of this Batch.
	RetentionPolicy() string
	// SetRetentionPolicy sets the retention policy of this Batch.
	SetRetentionPolicy(s string)
}

BatchPoints is an interface into a batched grouping of points to write into CnosDB together. BatchPoints is NOT thread-safe, you must create a separate batch for each goroutine.

func NewBatchPoints

func NewBatchPoints(conf BatchPointsConfig) (BatchPoints, error)

NewBatchPoints returns a BatchPoints interface based on the given config.

type BatchPointsConfig

type BatchPointsConfig struct {
	// Precision is the write precision of the points, defaults to "ns".
	Precision string

	// Database is the database to write points to.
	Database string

	// RetentionPolicy is the retention policy of the points.
	RetentionPolicy string

	// Write consistency is the number of servers required to confirm write.
	WriteConsistency string
}

BatchPointsConfig is the config data needed to create an instance of the BatchPoints struct.

type ChunkedResponse

type ChunkedResponse struct {
	// contains filtered or unexported fields
}

ChunkedResponse represents a response from the server that uses chunking to stream the output.

func NewChunkedResponse

func NewChunkedResponse(r io.Reader) *ChunkedResponse

NewChunkedResponse reads a stream and produces responses from the stream.

func (*ChunkedResponse) Close

func (r *ChunkedResponse) Close() error

Close closes the response.

func (*ChunkedResponse) NextResponse

func (r *ChunkedResponse) NextResponse() (*Response, error)

NextResponse reads the next line of the stream and returns a response.

type Client

type Client interface {
	// Ping checks that status of cluster, and will always return 0 time and no
	// error for UDP clients.
	Ping(timeout time.Duration) (time.Duration, string, error)

	// Write takes a BatchPoints object and writes all Points to CnosDB.
	Write(bp BatchPoints) error

	// Query makes an CnosDB Query on the database. This will fail if using
	// the UDP client.
	Query(q Query) (*Response, error)

	// QueryAsChunk makes an CnosDB Query on the database. This will fail if using
	// the UDP client.
	QueryAsChunk(q Query) (*ChunkedResponse, error)

	// Close releases any resources a Client may be using.
	Close() error
}

Client is a client interface for writing & querying the database.

func NewHTTPClient

func NewHTTPClient(conf HTTPConfig) (Client, error)

NewHTTPClient returns a new Client from the provided config. Client is safe for concurrent use by multiple goroutines.

type HTTPConfig

type HTTPConfig struct {
	// Addr should be of the form "http://host:port"
	// or "http://[ipv6-host%zone]:port".
	Addr string

	// Username is the cnosdb username, optional.
	Username string

	// Password is the cnosdb password, optional.
	Password string

	// UserAgent is the http User Agent, defaults to "CnosDBClient".
	UserAgent string

	// Timeout for cnosdb writes, defaults to no timeout.
	Timeout time.Duration

	// InsecureSkipVerify gets passed to the http client, if true, it will
	// skip https certificate verification. Defaults to false.
	InsecureSkipVerify bool

	// TLSConfig allows the user to set their own TLS config for the HTTP
	// Client. If set, this option overrides InsecureSkipVerify.
	TLSConfig *tls.Config

	// Proxy configures the Proxy function on the HTTP client.
	Proxy func(r *http.Request) (*url.URL, error)
}

HTTPConfig is the config data needed to create an HTTP Client.

type Message

type Message struct {
	Level string
	Text  string
}

Message represents a user message.

type Point

type Point struct {
	// contains filtered or unexported fields
}

Point represents a single data point.

func NewPoint

func NewPoint(
	name string,
	tags map[string]string,
	fields map[string]interface{},
	t ...time.Time,
) (*Point, error)

NewPoint returns a point with the given timestamp. If a timestamp is not given, then data is sent to the database without a timestamp, in which case the server will assign local time upon reception. NOTE: it is recommended to send data with a timestamp.

func NewPointFrom

func NewPointFrom(pt models.Point) *Point

NewPointFrom returns a point from the provided models.Point.

func (*Point) Fields

func (p *Point) Fields() (map[string]interface{}, error)

Fields returns the fields for the point.

func (*Point) Name

func (p *Point) Name() string

Name returns the measurement name of the point.

func (*Point) PrecisionString

func (p *Point) PrecisionString(precision string) string

PrecisionString returns a line-protocol string of the Point, with the timestamp formatted for the given precision.

func (*Point) String

func (p *Point) String() string

String returns a line-protocol string of the Point.

func (*Point) Tags

func (p *Point) Tags() map[string]string

Tags returns the tags associated with the point.

func (*Point) Time

func (p *Point) Time() time.Time

Time return the timestamp for the point.

func (*Point) UnixNano

func (p *Point) UnixNano() int64

UnixNano returns timestamp of the point in nanoseconds since Unix epoch.

type Query

type Query struct {
	Command         string
	Database        string
	RetentionPolicy string
	Precision       string
	Chunked         bool
	ChunkSize       int
	Parameters      map[string]interface{}
}

Query defines a query to send to the server.

func NewQuery

func NewQuery(command, database, precision string) Query

NewQuery returns a query object. The database and precision arguments can be empty strings if they are not needed for the query.

func NewQueryWithParameters

func NewQueryWithParameters(command, database, precision string, parameters map[string]interface{}) Query

NewQueryWithParameters returns a query object. The database and precision arguments can be empty strings if they are not needed for the query. parameters is a map of the parameter names used in the command to their values.

func NewQueryWithRP

func NewQueryWithRP(command, database, retentionPolicy, precision string) Query

NewQueryWithRP returns a query object. The database, retention policy, and precision arguments can be empty strings if they are not needed for the query.

type Response

type Response struct {
	Results []Result
	Err     string `json:"error,omitempty"`
}

Response represents a list of statement results.

func (*Response) Error

func (r *Response) Error() error

Error returns the first error from any statement. It returns nil if no errors occurred on any statements.

type Result

type Result struct {
	Series   []models.Row
	Messages []*Message
	Err      string `json:"error,omitempty"`
}

Result represents a resultset returned from a single statement.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL