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 #

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 scopePossible values: `all`, `in`, `out`, `none`
`users`	string (`none`)	Subscribe to users entering or leaving the roomPossible 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

// 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

// 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

// 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

// 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: {"sdkName":"go@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)

Edit this page on Github