API Libraries > Golang

Golang

This document describes how to use Go client for Rockset. This client allows you to:

  • securely connect to Rockset service
  • create, manage and administer collections
  • issue queries against collections

The Go client library is a Go module, and the code is available here.

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 ~/src
git clone git@github.com:rockset/rockset-go-client.git
go install rockset-go-client/rockclient.go

Connect

The NewClient() function returns a RockClient struct, which allow you to connect securely to Rockset service. All other API calls require a valid client struct.

In order to create a new RockClient, you will need a valid Rockset API key. If you have access to the Rockset Console, then you can use the console to create an API key. If not, please contact the Rockset team at support@rockset.com

import "github.com/rockset/rockset-go-client"

// create a Rockset client with an explicit API key
client, err := rockset.NewClient(rockset.WithAPIKey("<apiKey>"))

or from the ROCKSET_APIKEY environment variable

import "github.com/rockset/rockset-go-client"

// create a Rockset client with API key from the environment variable
client, err := rockset.NewClient(rockset.FromEnv())

See GoDoc for more options.

Usage

Create a Collection

Create a collection using the client as follows:

import (
    "github.com/rockset/rockset-go-client"
    models "github.com/rockset/rockset-go-client/lib/go")

// create collection
cinfo := models.CreateCollectionRequest {
    Name: "my-first-collection",
    Description: "my first collection",
}

res, _, err := client.Collection.Create("workspace-name", cinfo)
// print response as json 
res.PrintResponse()

If your document source is S3, follow the steps below otherwise refer to Rock CLI to add documents to the created collection.

Create an Integration

If you have an Amazon S3 bucket that you want to ingest data from, create a Rockset Integration to store credentials required to access the bucket. Create an integration struct using the client as follows:

// create Rockset integration
iinfo := models.CreateIntegrationRequest {
    Name: "my-first-integration",
    Description: "my first integration",
    Aws: &models.AwsKeyIntegration {
        AwsAccessKeyId: ".....",
        AwsSecretAccessKey: ".....",
    },
}

res, _, err := client.Integration.Create(iinfo)
res.PrintResponse()

Create a Collection from Amazon S3

Prior to creating a collection using Amazon S3 as source, create a Rockset Integration first as described above.

// create a collection from Amazon S3
cinfo := models.CreateCollectionRequest {
    Name: "my-first-s3-collection",
    Description: "my first s3 collection",
    Sources: []models.Source {
        {
            IntegrationName: "my-first-integration",
            S3 : &models.SourceS3 {
                Bucket: "&bucket-name&",
            },
        },
    },
}

res, _, err := client.Collection.Create("workspace-name", cinfo)
res.PrintResponse()

Add Documents

Add documents to an existing collection using the client.

// document to be inserted
m := map[string]interface{}{"name": "foo", "address": "bar"}

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

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

res, _, err := client.Documents.Add("workspace-name", "my-first-collection", dinfo)
res.PrintResponse()

Query

Make queries to Rockset using the client.

// construct query
q := models.QueryRequest {
    Sql : &models.QueryRequestSql{
        Query: "select * from hello",
    },
};

// query
res, _, err := client.Query(q)
// print json result
res.PrintResponse()

You can find more examples in the GoDoc.