SDK
SDK Golang v1.x
1

# Subscribe

Subscribes by providing a set of filters: messages, document changes and, optionally, user events matching the provided filters will generate real-time notifications, sent to you in real-time by Kuzzle.

# Arguments

Copied to clipboard!
func (r *Realtime) Subscribe(
  index string,
  collection string,
  filters json.RawMessage,
  listener chan<- types.NotificationResult,
  options types.RoomOptions
) (*types.SubscribeResult, error)

Arguments Type Description
index
string
Index name
collection
string
Collection name
filters
json.RawMessage
A set of filters following Koncorde syntax
listener
chan<- types.NotificationResult
Channel receiving the notification
options
types.RoomOptions
A struct containing subscription options

# listener

A channel for types.NotificationResult objects. The channel will receive an object each time a new notifications is received.

# options

Additional subscription options.

Property Type
(default)
Description
scope
string

(all)
Subscribe to document entering or leaving the scope
Possible values: all, in, out, none
users
string

(none)
Subscribe to users entering or leaving the room
Possible values: all, in, out, none
subscribeToSelf
bool

(true)
Subscribe to notifications fired by our own queries
volatile
json.RawMessage

({})
subscription information, used in user join/leave notifications

# Return

Return an error if something was wrong or a types.SubscribeResult containing the following properties:

Property Type Description
Room
string
The room ID
Channel
string
The channel ID

# Usage

Simple subscription to document notifications

Copied to clipboard!
// Subscribe to notifications for documents containing a 'name' property
filters := json.RawMessage(`{ "exists": "name" }`)
// Start an async listener
listener := make(chan types.NotificationResult)
go func() {
  notification := <-listener
  if notification.Scope == "in" {
    fmt.Printf("Document %s enter the scope\n", notification.Result.Id)
  } else {
    fmt.Printf("Document %s leave the scope\n", notification.Result.Id)
  }
}()
_, err := kuzzle.Realtime.Subscribe(
  "nyc-open-data",
  "yellow-taxi",
  filters,
  listener,
  nil)
if err != nil {
  log.Fatal(err)
}
document := json.RawMessage(`{ "name": "nina vkote", "age": 19 }`)
kuzzle.Document.Create(
  "nyc-open-data",
  "yellow-taxi",
  "nina-vkote",
  document,
  nil)

Subscription to document notifications with scope option

Copied to clipboard!
// Subscribe to notifications for documents containing a 'name' property
filters := json.RawMessage(`{ "range": { "age": { "lte": 20 } } }`)
// Start an async listener
listener := make(chan types.NotificationResult)
go func() {
  notification := <-listener
  fmt.Printf("Document moved %s from the scope\n", notification.Scope)
}()
options := types.NewRoomOptions()
options.SetScope(types.SCOPE_OUT)
_, err := kuzzle.Realtime.Subscribe(
  "nyc-open-data",
  "yellow-taxi",
  filters,
  listener,
  options)
if err != nil {
  log.Fatal(err)
}
document := json.RawMessage(`{ "name": "nina vkote", "age": 19 }`)
// The document is in the scope
kuzzle.Document.Create(
  "nyc-open-data",
  "yellow-taxi",
  "nina-vkote",
  document,
  nil)
// The document isn't in the scope anymore
kuzzle.Document.Update(
  "nyc-open-data",
  "yellow-taxi",
  "nina-vkote",
  json.RawMessage(`{ "age": 42 }`),
  nil)

Subscription to message notifications

Copied to clipboard!
// Start an async listener
listener := make(chan types.NotificationResult)
go func() {
  <-listener
  fmt.Printf("Message notification received")
}()
// Subscribe to a room
_, err := kuzzle.Realtime.Subscribe(
  "i-dont-exist",
  "i-database",
  json.RawMessage(`{}`),
  listener,
  nil)
if err != nil {
  log.Fatal(err)
}
message := json.RawMessage(`{ "metAt": "Insane", "hello": "world" }`)
// Publish a message to this room
kuzzle.Realtime.Publish("i-dont-exist", "i-database", message, nil)

Subscription to user notifications

Copied to clipboard!
// Subscribe to notifications for documents containing a 'name' property
filters := json.RawMessage(`{ "exists": "name" }`)
// Start an async listener
listener := make(chan types.NotificationResult)
go func() {
  notification := <-listener
  if notification.Type == "user" {
    fmt.Printf("Volatile data: %s\n", notification.Volatile)
    // Volatile data: {"sdkVersion":"1.0.0","username":"nina vkote"}
    fmt.Printf("Currently %d users in the room\n", notification.Result.Count)
  }
}()
options := types.NewRoomOptions()
options.SetUsers(types.USERS_ALL)
_, err := kuzzle.Realtime.Subscribe(
  "nyc-open-data",
  "yellow-taxi",
  filters,
  listener,
  options)
if err != nil {
  log.Fatal(err)
}
// Instantiates a second kuzzle client: multiple subscriptions
// made by the same user will not trigger "new user" notifications
ws2 := websocket.NewWebSocket("kuzzle", nil)
kuzzle2, _ := kuzzlepkg.NewKuzzle(ws2, nil)
connectErr = kuzzle2.Connect()
if connectErr != nil {
  log.Fatal(connectErr)
  os.Exit(1)
}
// Set some volatile data
options2 := types.NewRoomOptions()
options2.SetVolatile(json.RawMessage(`{ "username": "nina vkote" }`))
// Subscribe to the same room with the second client
kuzzle2.Realtime.Subscribe(
  "nyc-open-data",
  "yellow-taxi",
  filters,
  make(chan types.NotificationResult),
  options2)