rockset · pkg.go.dev

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

Expand ▾ Collapse ▴

Documentation

Overview ¶

Example (AddDocument) ¶

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)

Output:

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

Example (CreateCollection) ¶

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)

Output:

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

Example (CreateIntegration) ¶

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()

Output:

Example (CreateS3Collection) ¶

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()

Output:

Example (ErrorHandling) ¶

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)
	}
}

Output:

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

Example (QueryLambda) ¶

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

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)

Output:

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)
type RockOption

Constants ¶

View Source

const APIKeyEnvironmentVariableName = "ROCKSET_APIKEY"

View Source

const APIServerEnvironmentVariableName = "ROCKSET_APISERVER"

View Source

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

DefaultAPIServer is the default Rockset API server to use

View Source

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) ¶

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))

Output:

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

// 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))

Output:

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

Source Files

View all

Directories

Path	Synopsis
lib
go

?	: This menu
/	: Search site
f or F	: Jump to