SDK
SDK Golang v3.x
2
GolangGolang v3.x

Getting Started #

In this tutorial you will learn how to install the Kuzzle Go SDK. This page shows examples of scripts that store documents in Kuzzle, and of scripts that subcribe to real-time notifications for each new document created.

Before proceeding, please make sure your system meets the following requirements:

Having trouble? Get in touch with us on Discord!

Installation #

To easily install the Go SDK:

$ go get github.com/kuzzleio/sdk-go

This fetches the SDK and installs it in your GOPATH directory.

First connection #

Initialize a new Go project as described in the Go Documentation. Then create a init.go file and start by adding the code below:

package main
import (
  "fmt"
  "log"
  "os"
  "github.com/kuzzleio/sdk-go/kuzzle"
  "github.com/kuzzleio/sdk-go/protocol/websocket"
)
func main() {
  // Creates a WebSocket connection.
  // Replace "kuzzle" with
  // your Kuzzle hostname like "localhost"
  c := websocket.NewWebSocket("kuzzle", nil)
  // Instantiates a Kuzzle client
  kuzzle, _ := kuzzle.NewKuzzle(c, nil)
  // Connects to the server.
  err := kuzzle.Connect()
  if err != nil {
    log.Fatal(err)
    os.Exit(1)
  }
  fmt.Println("Connected!")
  // Freshly installed Kuzzle servers are empty: we need to create
  // a new index.
  if err := kuzzle.Index.Create("nyc-open-data", nil); err != nil {
    log.Fatal(err)
    os.Exit(1)
  }
  fmt.Println("Index nyc-open-data created!")
  // Creates a collection
  if err := kuzzle.Collection.Create(
    "nyc-open-data",
    "yellow-taxi",
    nil,
    nil,
  ); err != nil {
    log.Fatal(err)
    os.Exit(1)
  }
  fmt.Println("Collection yellow-taxi created!")
  // Disconnects the SDK
  kuzzle.Disconnect()
}

This program initializes the Kuzzle server storage by creating a index, and a collection inside it Run the program with the following command:

$ go run init.go
Connected!
Index nyc-open-data created!
Collection yellow-taxi created!

Congratulations, you performed a first connection to Kuzzle with a Go program. You are now able to:

  • Load the Kuzzle Go SDK from your GOPATH directory
  • Instantiate a protocol (here websocket) and a Kuzzle SDK instance
  • Connect to a Kuzzle instance running on localhost, with the WebSocket protocol
  • Create a index
  • Create a collection within an existing index

Create your first document #

Now that you successfully connected to your Kuzzle server with the Go SDK, and created an index and a collection, it's time to manipulate data.

Here is how Kuzzle structures its storage space:

  • indexes contain collections
  • collections contain documents Create a document.go file in the playground and add this code:
package main
import (
  "encoding/json"
  "fmt"
  "log"
  "os"
  "github.com/kuzzleio/sdk-go/kuzzle"
  "github.com/kuzzleio/sdk-go/protocol/websocket"
)
func main() {
  // Creates a WebSocket connection.
  // Replace "kuzzle" with
  // your Kuzzle hostname like "localhost"
  c := websocket.NewWebSocket("kuzzle", nil)
  // Instantiates a Kuzzle client
  kuzzle, _ := kuzzle.NewKuzzle(c, nil)
  // Connects to the server.
  if err := kuzzle.Connect(); err != nil {
    log.Fatal(err)
    os.Exit(1)
  }
  fmt.Println("Connected!")
  // New document content
  content := json.RawMessage(`
    {
      "name": "Sirkis",
      "birthday": "1959-06-22",
      "license": "B"
    }
  `)
  // Stores the document in the "yellow-taxi" collection.
  if _, err := kuzzle.Document.Create(
    "nyc-open-data",
    "yellow-taxi",
    "some-id",
    content,
    nil,
  ); err != nil {
    log.Fatal(err)
    os.Exit(1)
  }
  fmt.Println("New document added to the yellow-taxi collection!")
  // Disconnects the SDK.
  kuzzle.Disconnect()
}

As you did before, run your program:

$ go run document.go
Connected!
New document added to yellow-taxi collection!

You can perform other actions such as delete, replace or search documents. There are also other ways to interact with Kuzzle like our Admin Console, the Kuzzle HTTP API or by using your own protocol.

Now you know how to:

  • Store documents in a Kuzzle server, and access those

Subscribe to realtime document notifications (pub/sub) #

Time to use realtime with Kuzzle. Create a new file realtime.go with the following code:

package main
import (
  "encoding/json"
  "fmt"
  "log"
  "os"
  "github.com/kuzzleio/sdk-go/kuzzle"
  "github.com/kuzzleio/sdk-go/protocol/websocket"
  "github.com/kuzzleio/sdk-go/types"
)
func main() {
  // Creates a WebSocket connection.
  // Replace "kuzzle" with
  // your Kuzzle hostname like "localhost"
  c := websocket.NewWebSocket("kuzzle", nil)
  // Instantiates a Kuzzle client
  kuzzle, _ := kuzzle.NewKuzzle(c, nil)
  // Connects to the server.
  if err := kuzzle.Connect(); err != nil {
    log.Fatal(err)
    os.Exit(1)
  }
  fmt.Println("Connected!")
  // Prevents the program from exiting before receiving a notification
  exit := make(chan bool)
  // Starts an async listener
  listener := make(chan types.NotificationResult)
  go func() {
    notification := <-listener
    // Parses the document content embedded in the notification.
    var doc struct {
      Name     string `json:"name"`
      Birthday string `json:"birthday"`
      License  string `json:"license"`
    }
    json.Unmarshal(notification.Result.Content, &doc)
    fmt.Printf("Driver %s born on %s got a %s license.\n",
      doc.Name,
      doc.Birthday,
      doc.License,
    )
    // Allows the program to exit
    exit <- true
  }()
  // Subscribes to notifications for drivers having a "B" driver license.
  filters := json.RawMessage(`
    {
      "equals": {
        "license":"B"
      }
    }
  `)
  // Sends the subscription
  if _, err := kuzzle.Realtime.Subscribe(
    "nyc-open-data",
    "yellow-taxi",
    filters,
    listener,
    nil,
  ); err != nil {
    log.Fatal(err)
    os.Exit(1)
  }
  fmt.Println("Successfully subscribed!")
  // Writes a new document. This triggers a notification sent to our subscription.
  content := json.RawMessage(`
    {
      "name": "John",
      "birthday": "1995-11-27",
      "license": "B"
    }
  `)
  if _, err := kuzzle.Document.Create(
    "nyc-open-data",
    "yellow-taxi",
    "",
    content,
    nil,
  ); err != nil {
    log.Fatal(err)
    os.Exit(1)
  }
  fmt.Println("New document added to the yellow-taxi collection!")
  // Waits for a notification to be received
  <-exit
  // Disconnects the SDK.
  kuzzle.Disconnect()
}

This program subscribes to changes made to documents with a license field set to B, within the yellow-taxi collection. Whenever a document matching the provided filters changes, a new notification is received from Kuzzle. Run your program:

$ go run realtime.go
Connected!
Successfully subscribing!
New document added to yellow-taxi collection!
Driver John born on 1995-11-27 got a B license.

Now, you know how to:

  • Create realtime filters
  • Subscribe to notifications

Where do we go from here? #

Now that you're more familiar with the Go SDK, you can dive even deeper to learn how to leverage its full capabilities:

Edit this page on Github(opens new window)