clarify

package module
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Jun 8, 2022 License: Apache-2.0 Imports: 15 Imported by: 3

README

Clarify Go SDK

GitHub Actions Go Reference Clarify Docs

This repository contains a Go(lang) SDK from Clarify. Clarify is a cloud service for active collaboration on time-series data. It includes a free plan to get started, a plan for small businesses as well as an Enterprise plan for our most demanding customers. If you are interested in SDKs for a different language, or perhaps a different way of integration altogether, please check our documentation.

Risk of breaking changes

This SDK is following Semantic Versioning. The SDK is currently in a v0 state, which means that we reserver the right to introduce breaking changes without increasing the MAJOR number.

Features

This SDK is currently written for Clarify API v1.1beta2, and include the following features:

  • Compose Clarify data frames using the data sub-package.
  • Write signal meta-data to Clarify with client.SaveSignals. See example.
  • Write data frames to Clarify with client.Insert. See example.

Copyright 2022 Searis AS

Licensed under the Apache License, Version 2.0 (the "License"); you may not use the content in this repo except in compliance with the License. You may obtain a copy of the License at

 http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Documentation

Overview

Package clarify allows interacting with https://api.clarify.io/v1/, and perform simple manipulations of Clarify data and meta-data.

Index

Examples

Constants

View Source 
const (
	TypeBasicAuth         = "basic-auth"
	TypeClientCredentials = "client-credentials"
)

Supported credentials types.

View Source 
const (
	// Standard JSON RPC error codes.
	CodeInvalidJSON    = -32700
	CodeInvalidRequest = -32600
	CodeMethodNotFound = -32601
	CodeInvalidParams  = -32602
	CodeInternal       = -32603

	// Clarify error codes.
	CodeServerError            = -32000
	CodeProduceInvalidResource = -32001
	CodeFoundInvalidResource   = -32002
	CodeForbidden              = -32003
	CodeConflict               = -32009
	CodeTryAgain               = -32015
	CodePartialFailure         = -32021
)
View Source 
const (
	ErrBadCredentials strErr = "bad credentials"
	ErrBadResponse    strErr = "bad response"
	ErrBadRequest     strErr = "bad request"
)

Client errors.

Variables

This section is empty.

Functions

This section is empty.

Types

type Client 

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

Client allows calling JSON RPC methods against Clarify.

func NewClient 

func NewClient(integration string, h jsonrpc.Handler) *Client

NewClient can be used to initialize an integration client from a jsonrpc.Handler implementation.

func (*Client) DataFrame 

func (c *Client) DataFrame() DataFrameRequest

DataFrame returns a new request from retrieving data from clarify. The request can be furthered modified by a chainable API before it's executed. By default, the data section is set to be included in the response.

Disclaimer: this method is based on a pre-release of the Clarify API, and might be unstable or stop working.

Example 
const inputID = "temp"
const integrationID = "c8ktonqsahsmemfs7lv0"
const itemID = "c8l95d2sahsh22imiabg"

// In this example we use a mock client; real code should insted initialize
// using a clarify.Credentials instance.
h := mockRPCHandler{
	"clarify.dataframe": {
		err:       nil,
		rawResult: json.RawMessage(testdata.ResultDataFrameRollup),
	},
}
c := clarify.NewClient(integrationID, h)

ctx := context.Background()

res, err := c.DataFrame().
	Filter(
		query.Field("id", query.In("c8keagasahsp3cpvma20")),
	).
	Limit(1).
	TimeRange(
		time.Date(2022, 1, 1, 0, 0, 0, 0, time.UTC),
		time.Date(2022, 1, 1, 4, 0, 0, 0, time.UTC),
	).
	RollupBucket(time.Hour).
	Include("items").
	Do(ctx)

if err != nil {
	fmt.Println("error:", err)
	return
}
fmt.Println("meta.total:", res.Meta.Total)
fmt.Println("len(data):", len(res.Data))
if len(res.Data) > 0 {
	fmt.Println("data."+itemID+"_sum:", res.Data[itemID+"_sum"])
}
fmt.Println("len(included.items):", len(res.Included.Items))
if len(res.Included.Items) > 0 {
	fmt.Println("included.items.0.id:", res.Included.Items[0].ID)
	fmt.Println("included.items.0.meta.annotations:", res.Included.Items[0].Meta.Annotations)
}

Output:

meta.total: 2
len(data): 5
data.c8l95d2sahsh22imiabg_sum: map[1640995200000000:64 1640998800000000:32.1 1641002400000000:32.5]
len(included.items): 1
included.items.0.id: c8l95d2sahsh22imiabg
included.items.0.meta.annotations: map[clarify/clarify-go/from/signal/attributes-hash:220596a7b7b4ea2ac5abb6a13e6198f161443226 clarify/clarify-go/from/signal/id:c8keagasahsp3cpvma20]

func (*Client) Insert 

func (c *Client) Insert(data views.DataFrame) resource.Request[InsertResult]

Insert returns a new insert request that can be executed at will. Requires access to the integration namespace. Will insert the data to the integration set in c.

func (*Client) PublishSignals 

func (c *Client) PublishSignals(integration string, itemsBySignal map[string]views.ItemSave) resource.SaveRequest[map[string]views.ItemSave, PublishSignalsResult]

PublishSignals returns a new request for publishing signals as Items. Requires access to the admin namespace.

Disclaimer: this method is based on a pre-release of the Clarify API, and might be unstable or stop working.

func (*Client) SaveSignals 

func (c *Client) SaveSignals(inputs map[string]views.SignalSave) resource.SaveRequest[map[string]views.SignalSave, SaveSignalsResult]

SaveSignals returns a new save signals request that can be modified though a chainable API before it's executed. Keys in inputs are scoped to the current integration. Requires access to the integration namespace.

func (*Client) SelectItems 

func (c *Client) SelectItems() resource.SelectRequest[SelectItemsResult]

SelectItems returns a new request for querying signals and related resources.

Disclaimer: this method is based on a pre-release of the Clarify API, and might be unstable or stop working.

func (*Client) SelectSignals 

func (c *Client) SelectSignals(integration string) resource.SelectRequest[SelectSignalsResult]

SelectSignals returns a new request for querying signals and related resources.

Disclaimer: this method is based on a pre-release of the Clarify API, and might be unstable or stop working.

Example 
const integrationID = "c8ktonqsahsmemfs7lv0"

// In this example we use a mock client; real code should insted initialize
// using a clarify.Credentials instance.
h := mockRPCHandler{
	"admin.selectsignals": {
		err:       nil,
		rawResult: json.RawMessage(testdata.ResultSelectSignals),
	},
}
c := clarify.NewClient(integrationID, h)

ctx := context.Background()

res, err := c.SelectSignals(integrationID).
	Filter(
		query.Field("id", query.In("c8keagasahsp3cpvma20", "c8l8bc2sahsgjg5cckcg")),
	).
	Limit(1).
	Include("items").
	Do(ctx)

if err != nil {
	fmt.Println("error:", err)
	return
}

fmt.Println("meta.total:", res.Meta.Total)
fmt.Println("len(data):", len(res.Data))
if len(res.Data) > 0 {
	fmt.Println("data.0.id:", res.Data[0].ID)
	fmt.Println("data.0.meta.attributesHash:", res.Data[0].Meta.AttributesHash)
}
fmt.Println("len(included.items):", len(res.Included.Items))
if len(res.Included.Items) > 0 {
	fmt.Println("included.items.0.id:", res.Included.Items[0].ID)
	fmt.Println("included.items.0.meta.annotations:", res.Included.Items[0].Meta.Annotations)
}

Output:

meta.total: 2
len(data): 1
data.0.id: c8keagasahsp3cpvma20
data.0.meta.attributesHash: 220596a7b7b4ea2ac5abb6a13e6198f161443226
len(included.items): 1
included.items.0.id: c8l95d2sahsh22imiabg
included.items.0.meta.annotations: map[clarify/clarify-go/from/signal/attributes-hash:220596a7b7b4ea2ac5abb6a13e6198f161443226 clarify/clarify-go/from/signal/id:c8keagasahsp3cpvma20]

type Credentials 

type Credentials struct {
	Name      string    `json:"name"`
	CreatedAt time.Time `json:"createdAt"`

	APIURL      string          `json:"apiUrl"`
	Integration string          `json:"integration"`
	Credentials CredentialsAuth `json:"credentials"`
}

Credentials contain a data-structure with Clarify integration credentials.

func BasicAuthCredentials 

func BasicAuthCredentials(integrationID, password string) *Credentials

BasicAuthCredentials returns basic auth credentials for use with Clarify.

func CredentialsFromFile 

func CredentialsFromFile(name string) (creds *Credentials, err error)

CredentialsFromFile parse Clarify Credentials from the passed in filename, and return either valid credentials or an error.

func CredentialsFromReader 

func CredentialsFromReader(r io.Reader) (*Credentials, error)

CredentialsFromReader parse Clarify Credentials from the passed in reader, and return either valid credentials or an error.

func (Credentials) Client 

func (creds Credentials) Client(ctx context.Context) *Client

Client returns a new Clarify client for the current credentials, assuming the client credentials to be valid. If the credentials are invalid, this method will return a non-functional client where all requests result return the ErrBadCredentials error.

func (Credentials) HTTPHandler 

func (creds Credentials) HTTPHandler(ctx context.Context) (*jsonrpc.HTTPHandler, error)

HTTPHandler returns a low-level RPC handler that communicates over HTTP using the credentials in creds.

func (*Credentials) Validate 

func (creds *Credentials) Validate() error

Validate returns an error if the credentials are invalid.

type CredentialsAuth 

type CredentialsAuth struct {
	Type         string `json:"type"`
	ClientID     string `json:"clientId"`
	ClientSecret string `json:"clientSecret"`
}

CredentialsAuth contains the information that is used to authenticate credentials against Clarify.

type DataFrameInclude 

type DataFrameInclude struct {
	Items []views.Item `json:"items"`
}

DataFrameInclude describe the included properties for the dataFrame select view.

type DataFrameRequest 

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

DataFrameRequest describes a data frame request.

func (DataFrameRequest) Do 

func (req DataFrameRequest) Do(ctx context.Context) (*DataFrameResult, error)

Do performs the request against the server and returns the result.

func (DataFrameRequest) Filter 

func (req DataFrameRequest) Filter(filter query.FilterType) DataFrameRequest

Filter returns a new request that includes Items matching the provided filter.

func (DataFrameRequest) FilterField deprecated 

func (req DataFrameRequest) FilterField(path string, cmp query.Comparison) DataFrameRequest

FilterField returns a new request that includes Items matching the provided filter.

Deprecated: use Filter(query.Field(path, cmp)) instead.

func (DataFrameRequest) Include 

func (req DataFrameRequest) Include(relationships ...string) DataFrameRequest

Include returns a new request set to include the specified relationships.

func (DataFrameRequest) Last 

func (req DataFrameRequest) Last(n int) DataFrameRequest

Last sets the query to only include the n last matching values per item.

func (DataFrameRequest) Limit 

func (req DataFrameRequest) Limit(n int) DataFrameRequest

Limit returns a new request that limits the number of matches. Setting n < 0 will use the max limit.

func (DataFrameRequest) RollupBucket 

func (req DataFrameRequest) RollupBucket(d time.Duration) DataFrameRequest

RollupBucket sets the query to rollup all data into fixed size bucket when d > 0. Otherwise, clear the rollup information from the query.

func (DataFrameRequest) RollupWindow 

func (req DataFrameRequest) RollupWindow() DataFrameRequest

RollupWindow sets the query to rollup all data into a single timestamp.

func (DataFrameRequest) Skip 

func (req DataFrameRequest) Skip(n int) DataFrameRequest

Skip returns a new request that skips the first n matches.

func (DataFrameRequest) TimeRange 

func (req DataFrameRequest) TimeRange(gte, lt time.Time) DataFrameRequest

TimeRange returns a new request that include data for matching items in the specified time range. Note that including data will reduce the maximum number of items that can be returned by the response.

type DataFrameResult 

type DataFrameResult = struct {
	Meta     resource.SelectionMeta `json:"meta"`
	Data     views.DataFrame        `json:"data"`
	Included DataFrameInclude       `json:"included"`
}

type HTTPError 

type HTTPError = jsonrpc.HTTPError

type InsertResult 

type InsertResult struct {
	SignalsByInput map[string]resource.CreateSummary `json:"signalsByInput"`
}

InsertResult holds the result of an Insert operation.

type PathErrors 

type PathErrors map[string][]string

PathErrors describes issues for fields in a data-structure. Nested field errors are reported with as `<parentField>.<subField>`. Field names are camelCased to match the preferred case used for JSON encoding.

func (PathErrors) Error 

func (err PathErrors) Error() string

type PublishSignalsResult 

type PublishSignalsResult struct {
	ItemsBySignals map[string]resource.SaveSummary `json:"itemsBySignal"`
}

PublishSignalsResult holds the result of a PublishSignals operation.

type SaveSignalsResult 

type SaveSignalsResult struct {
	SignalsByInput map[string]resource.SaveSummary `json:"signalsByInput"`
}

SaveSignalsResults holds the result of a SaveSignals operation.

type SelectItemsResult 

type SelectItemsResult = resource.Selection[views.Item, views.ItemInclude]

SelectItemsResult holds the result of a SelectItems operation.

type SelectSignalsResult 

type SelectSignalsResult = resource.Selection[views.Signal, views.SignalInclude]

SelectSignalsResult holds the result of a SelectSignals operation.

type ServerError 

type ServerError = jsonrpc.ServerError

Source Files

View all Source files

Directories

Path Synopsis
examples
basic_auth
data_frame
insert
publish_signals
save_signals
select_items
select_signals
Package fields define field types for defining JSON views and models.
 Package fields define field types for defining JSON views and models.
Package jsonrpc provides a Clarify specific low-level RPC client.
 Package jsonrpc provides a Clarify specific low-level RPC client.
resource
Package views define views for Clarify resources.
 Package views define views for Clarify resources.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.