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:

Go version 1.9 or higher (Go installation instructions)
A running Kuzzle server (Kuzzle installation guide)

Having trouble? Get in touch with us on Gitter!

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"
  "os"
  "log"
  "github.com/kuzzleio/sdk-go/protocol/websocket"
  "github.com/kuzzleio/sdk-go/kuzzle"
)
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

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:

discover what this SDK has to offer by browsing other sections of this documentation
learn how to use Koncorde to create incredibly fine-grained and blazing-fast subscriptions
follow our guide to learn how to perform basic authentication
follow our guide to learn how to manage users and how to set up fine-grained access control

Edit this page on Github

Getting Started #

Installation #

First connection #

Create your first document #

Subscribe to realtime document notifications (pub/sub) #

Where do we go from here? #