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 (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
Examples ¶
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 ¶
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 ¶
DeleteWorkspace deletes the workspace with name
func (*RockClient) GetWorkspace ¶
GetWorkspace gets the workspace with name
func (*RockClient) ListWorkspaces ¶
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 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
Directories
Path | Synopsis |
---|---|
lib/go |