README

Rockset Go Client

Official Go client library for Rockset

Installation

Install the Rockset Go client from Github:

go get github.com/rockset/rockset-go-client

or install it from a source code checkout:

cd $GOPATH/src/github.com
mkdir rockset
cd rockset
git clone git@github.com:rockset/rockset-go-client.git
go install rockset-go-client/rockclient.go

Usage

You can see a few examples in the godoc of how to create a collection, how to put documents in a collection and how to use SQL to query your collections.

client, err := rockset.NewClient(rockset.WithAPIKey("..."))
if err != nil {
    log.Fatal(err)
}

q := models.QueryRequest{
    Sql: &models.QueryRequestSql{
        Query: `SELECT * FROM "_events" LIMIT 1`,
    },
}

res, _, err := client.Query(q)
if err != nil {
    log.Fatal(err)
}

fmt.Printf("%+v\n", res)

Testing

Tests are available in the test folder.

Set ROCKSET_APIKEY and ROCKSET_APISERVER endpoint in the environment variables. To run tests:

go test ./...

Support

Feel free to log issues against this client through GitHub.

License

The Rockset Go Client is licensed under the Apache 2.0 License

Documentation

Overview

Example (AddDocument)

Code:

client, err := rockset.NewClient(rockset.FromEnv())
if err != nil {
	log.Fatal(err)
}

createResp, _, err := client.Collection.Create("commons", models.CreateCollectionRequest{
	Name:        "go-test-add-docs-collection",
	Description: "go test add docs collection",
})
if err != nil {
	log.Fatal(err)
}

fmt.Printf("created collection %s\n", createResp.Data.Name)

time.Sleep(5 * time.Second)

// document to be inserted
doc := map[string]interface{}{"name": "foo"}

// array of documents
docs := []interface{}{doc}

docReq := models.AddDocumentsRequest{
	Data: docs,
}

res, _, err := client.Documents.Add("commons", "go-test-add-docs-collection", docReq)
if err != nil {
	log.Fatal(err)
}

fmt.Printf("document status: %s\n", res.Data[0].Status)

created collection go-test-add-docs-collection
document status: ADDED
deleted collection go-test-add-docs-collection

Example (CreateCollection)

Code:

client, err := rockset.NewClient(rockset.FromEnv())
if err != nil {
	log.Fatal(err)
}

// create collection
createResp, _, err := client.Collection.Create("commons", models.CreateCollectionRequest{
	Name:        "go-test-collection",
	Description: "go test collection",
})
fmt.Printf("created collection %s\n", createResp.Data.Name)

// get collection
getResp, _, err := client.Collection.Get("commons", "go-test-collection")
if err != nil {
	log.Fatal(err)
}
fmt.Printf("collection status for %s: %s\n", getResp.Data.Name, getResp.Data.Status)

// delete collection
deleteResp, _, err := client.Collection.Delete("commons", "go-test-collection")
if err != nil {
	log.Fatal(err)
}

fmt.Printf("deleted collection %s\n", deleteResp.Data.Name)

created collection go-test-collection
collection status for go-test-collection: CREATED
deleted collection go-test-collection

Example (CreateIntegration)

Code:

client, err := rockset.NewClient(rockset.FromEnv())
if err != nil {
	log.Fatal(err)
}

// create integration
req := models.CreateIntegrationRequest{
	Name:        "my-first-integration",
	Description: "my first integration",
	Kinesis: &models.KinesisIntegration{
		AwsAccessKey: &models.AwsAccessKey{
			AwsAccessKeyId:     "...",
			AwsSecretAccessKey: "...",
		},
		AwsRole: &models.AwsRole{
			AwsRoleArn: "arn:aws:iam::<account-id>:role/<role-name>",
		},
	},
}

res, _, err := client.Integration.Create(req)
if err != nil {
	log.Fatal(err)
}

res.PrintResponse()

Example (CreateS3Collection)

Code:

client, err := rockset.NewClient(rockset.FromEnv())
if err != nil {
	log.Fatal(err)
}

// create collection
req := models.CreateCollectionRequest{
	Name:        "s3_collection",
	Description: "s3 collection",
	Sources: []models.Source{
		{
			IntegrationName: "my-first-integration",
			S3: &models.SourceS3{
				Bucket: "s3://<bucket-name>",
			},
		},
	},
}

resp, _, err := client.Collection.Create("commons", req)
if err != nil {
	fmt.Printf("error: %s\n", err)
	return
}

resp.PrintResponse()

Example (ErrorHandling)

Code:

client, err := rockset.NewClient(rockset.FromEnv())
if err != nil {
	log.Fatal(err)
}

_, _, err = client.DeleteWorkspace("non-existing-workspace")
if err != nil {
	if e, ok := rockset.AsRocksetError(err); ok {
		fmt.Printf("%s: %s", e.Type_, e.Message)
	}
}

NotFound: Could not find workspace with name 'non-existing-workspace'

Example (QueryLambda)

Example code to create, use, and delete a Query Lambda

Code:

client, err := rockset.NewClient(rockset.FromEnv())
if err != nil {
	log.Fatalf("failed to create Rockset client: %v", err)
}

fatal := func(msg string, err error) {
	if e, ok := rockset.AsRocksetError(err); ok {
		log.Fatalf("%s (%s): %v", msg, e.Message, err)
	}
	log.Fatalf("%s: %v", msg, err)
}

workspace := "commons"
lambdaName := "MyQueryLambda"

// construct request
createLambda := models.CreateQueryLambdaRequest{
	Name: lambdaName,
	Sql: &models.QueryLambdaSql{
		Query: "SELECT :param as echo",
		DefaultParameters: []models.QueryParameter{
			{
				Name:  "param",
				Type_: "string",
				Value: "Hello, world!",
			},
		},
	},
}

// create Query Lambda
createResp, _, err := client.QueryLambdas.Create(workspace, createLambda)
if err != nil {
	fatal("failed to create query lambda", err)
}

fmt.Printf("created Query Lambda %s\n", createResp.Data.Name)

// execute Query Lambda with default parameters
runResp, _, err := client.QueryLambdas.Execute_4(workspace, lambdaName, createResp.Data.Version, nil)
if err != nil {
	fatal("failed to execute query lambda", err)
}

fmt.Printf("query result: %v\n", runResp.Results[0])

// execute Query Lambda with explicit parameters
q := models.Execute_4Opts{
	Body: optional.NewInterface(models.ExecuteQueryLambdaRequest{
		Parameters: []models.QueryParameter{
			{
				Name:  "param",
				Type_: "string",
				Value: "All work and no play makes Jack a dull boy",
			},
		},
	}),
}

runResp, _, err = client.QueryLambdas.Execute_4(workspace, lambdaName, createResp.Data.Version, &q)
if err != nil {
	fatal("failed to execute query lambda with explicit params", err)
}

fmt.Printf("query result: %v\n", runResp.Results[0])

deleteResp, _, err := client.QueryLambdas.Delete(workspace, lambdaName)
if err != nil {
	fatal("failed to delete query lambda", err)
}

fmt.Printf("deleted Query Lambda %s\n", deleteResp.Data.Name)

created Query Lambda MyQueryLambda
query result: map[echo:Hello, world!]
query result: map[echo:All work and no play makes Jack a dull boy]
deleted Query Lambda MyQueryLambda

Index

• Constants
• func AsRocksetError(err error) (api.ErrorModel, bool)
• type RockClient
  • func Client(apiKey string, apiServer string) *RockClient
  • func NewClient(options ...RockOption) (*RockClient, error)
  • func (rc *RockClient) CreateWorkspace(name, description string) (api.Workspace, *http.Response, error)
  • func (rc *RockClient) DeleteWorkspace(name string) (api.Workspace, *http.Response, error)
  • func (rc *RockClient) GetWorkspace(name string) (api.Workspace, *http.Response, error)
  • func (rc *RockClient) ListWorkspaces() ([]api.Workspace, *http.Response, error)
  • func (rc *RockClient) Organization() (api.Organization, *http.Response, error)
  • func (rc *RockClient) Query(request api.QueryRequest) (api.QueryResponse, *http.Response, error)
  • func (rc *RockClient) Validate() error
• type RockOption
  • func FromEnv() RockOption
  • func WithAPIKey(key string) RockOption
  • func WithAPIServer(s string) RockOption
  • func WithHTTPClient(c *http.Client) RockOption
  • func WithTimeout(t time.Duration) RockOption

Examples

• Package (AddDocument)
• Package (CreateCollection)
• Package (CreateIntegration)
• Package (CreateS3Collection)
• Package (ErrorHandling)
• Package (QueryLambda)
• RockClient (QueryParam)
• RockClient.Query

Constants

const APIKeyEnvironmentVariableName = "ROCKSET_APIKEY"

const APIServerEnvironmentVariableName = "ROCKSET_APISERVER"

const DefaultAPIServer = "https://api.rs2.usw2.rockset.com"

DefaultAPIServer is the default Rockset API server to use

const Version = "0.10.0"

Version is the Rockset client version

Variables

This section is empty.

Functions

func AsRocksetError

func AsRocksetError(err error) (api.ErrorModel, bool)

AsRocksetError takes an error returned from an API call and returns the underlying error message

Types

type RockClient

type RockClient struct {

	// API Services
	ApiKeys       *api.ApiKeysApiService
	Collection    *api.CollectionsApiService
	Integration   *api.IntegrationsApiService
	Documents     *api.DocumentsApiService
	QueryApi      *api.QueriesApiService
	Users         *api.UsersApiService
	Organizations *api.OrganizationsApiService
	QueryLambdas  *api.QueryLambdasApiService
	Workspaces    *api.WorkspacesApiService // contains filtered or unexported fields

}

Example (QueryParam)

Code:

client, err := rockset.NewClient(rockset.FromEnv())
if err != nil {
	log.Fatal(err)
}

// construct query
q := models.QueryRequest{
	Sql: &models.QueryRequestSql{
		Query: `SELECT :k`,
		Parameters: []models.QueryParameter{
			{Name: "k", Type_: "string", Value: "foo"},
		},
	},
}

// execute query
res, _, err := client.Query(q)
if err != nil {
	log.Fatal(err)
}

fmt.Printf("got %d response(s)\n", len(res.Results))

got 1 response(s)

func Client

func Client(apiKey string, apiServer string) *RockClient

Create a Client object to securely connect to Rockset using an API key Optionally, an alternate API server host can also be provided.

Deprecated: this function has been superseded by NewClient()

func NewClient

func NewClient(options ...RockOption) (*RockClient, error)

NewClient creates a new Rockset client.

Accessing the online database requires an API key, which you either have to supply through the ROCKSET_APIKEY environment variable and pass the FromEnv() option

c, err := rockset.NewClient(rockset.FromEnv())

or explicitly using the WithAPIKey() option

c, err := rockset.NewClient(rockset.WithAPIKey("..."))

func (*RockClient) CreateWorkspace

func (rc *RockClient) CreateWorkspace(name, description string) (api.Workspace, *http.Response, error)

CreateWorkspace creates a new workspace

func (*RockClient) DeleteWorkspace

func (rc *RockClient) DeleteWorkspace(name string) (api.Workspace, *http.Response, error)

DeleteWorkspace deletes the workspace with name

func (*RockClient) GetWorkspace

func (rc *RockClient) GetWorkspace(name string) (api.Workspace, *http.Response, error)

GetWorkspace gets the workspace with name

func (*RockClient) ListWorkspaces

func (rc *RockClient) ListWorkspaces() ([]api.Workspace, *http.Response, error)

ListWorkspaces list all workspaces

func (*RockClient) Organization

func (rc *RockClient) Organization() (api.Organization, *http.Response, error)

Organization returns the organization the RockClient belongs to

func (*RockClient) Query

func (rc *RockClient) Query(request api.QueryRequest) (api.QueryResponse, *http.Response, error)

Query executes a query request against Rockset

Example

This example runs a query against Rockset

Code:

// create the API client
client, err := rockset.NewClient(rockset.FromEnv())
if err != nil {
	log.Fatal(err)
}

// construct a query
q := models.QueryRequest{
	Sql: &models.QueryRequestSql{
		Query: `SELECT * FROM "_events" LIMIT 1`,
	},
}

// execute the query
res, _, err := client.Query(q)
if err != nil {
	log.Fatal(err)
}

fmt.Printf("got %d row(s)\n", len(res.Results))

got 1 row(s)

func (*RockClient) Validate

func (rc *RockClient) Validate() error

Validate validates and sets the Rockset client configuration options

type RockOption

type RockOption func(rc *RockClient)

RockOption is the type for RockClient options

func FromEnv

func FromEnv() RockOption

FromEnv sets API key and API server from the environment variables ROCKSET_APIKEY and ROCKSET_APISERVER, and if ROCKSET_APISERVER is not set, it will use the default API server.

func WithAPIKey

func WithAPIKey(key string) RockOption

WithAPIKey sets the API key to key

func WithAPIServer

func WithAPIServer(s string) RockOption

WithAPIServer sets the API server

func WithHTTPClient

func WithHTTPClient(c *http.Client) RockOption

WithHTTPClient sets the HTTP client. Without this option RockClient uses the http.DefaultClient, which does not have a timeout.

func WithTimeout

func WithTimeout(t time.Duration) RockOption

WithTimeout sets the HTTP client timeout, and will override any value set using using the WithHTTPClient() option