Collections

Collections enable you to store information to Stream. This allows you to use it inside your feeds, and to provide additional data for the personalized endpoints. Examples include products and articles, but any unstructured object (e.g. JSON) is a good match for collections.

Collection entries can be embedded inside activities and used to store nested data inside activities. When doing so, Stream will automatically enrich your activities with the current version of the data (see later section). Collection endpoints can be used both client-side and server-side except the batch methods that are only available server-side.

Adding Collections

This method allows you to create a new entry on a named collection.

Parameters

name	type	description	default	optional
collection	string	The name of the collection	-
entry_id	string	The id of the entry, if not given an ID will be generated by Stream.	-	✓
data	object	The data related to the user	-

var collectionData = new Dictionary<string, object>();
collectionData.Add("name", "Cheese burger");
collectionData.Add("rating", "4 stars");
await client.Collections.AddAsync("food", collectionData, "cheese-burger");

// if you don't have an id on your side, just use null as the ID and Stream will generate a unique ID
await client.Collections.AddAsync("food", collectionData);

await client.collections.add('food', 'cheese-burger', { name: "Cheese Burger", rating: "4 stars" });

// if you don't have an id on your side, just use null as the ID and Stream will generate a unique ID
await client.collections.add("food", null, { name: "Cheese Burger", rating: "4 stars" });

client.collections.add("food", {"name": "Cheese Burger", "rating": "4 stars"}, id="cheese-burger")

# if you don't have an id on your side, Stream will generate a unique ID
client.collections.add("food", {"name": "Cheese Burger", "rating": "4 stars"})

client.collections.add(
  "food", 
  {:name =&gt; "Cheese Burger", :rating =&gt; "4 stars"}, 
  :id =&gt; "cheese-burger"
)

# if you don't have an id on your side, Stream will generate a unique ID
client.collections.add("food", {:name =&gt; "Cheese Burger", :rating =&gt; "4 stars"})

$client->collections()->add(
  "food", ["name" => "Cheese Burger", "rating" => "4 stars"], "cheese-burger"
);

// if you don't have an id on your side, Stream will generate a unique ID
$client->collections()->add(
  "food", ["name" => "Cheese Burger", "rating" => "4 stars"]
);

client.collections().add("food", new CollectionData("cheese-burger")
    .set("name", "Cheese Burger")
    .set("rating", "4 stars")).join();

// if you don't have an id on your side, just use null as the ID and Stream will generate a unique ID
client.collections().add("food", new CollectionData()
    .set("name", "Cheese Burger")
    .set("rating", "4 stars")).join();

obj := stream.CollectionObject{
		ID: "cheese-burger",
		Data: map[string]any{
			"name":  "Cheese Burger",
			"rating": "4 stars",
		},
	}
	resp, err := client.Collections().Add(context.TODO(), "food", obj)
	if err != nil {
		panic(err)
	}

	//if you don't have an id on your side, Stream will generate a unique ID
	obj := stream.CollectionObject{
		Data: map[string]any{
			"name":  "Cheese Burger",
			"rating": "4 stars",
		},
	}
	resp, err := client.Collections().Add(context.TODO(), "food", obj)
	if err != nil {
		panic(err)
	}

// create a new collection object type with custom properties
final class Food: CollectionObject {
  private enum CodingKeys: String, CodingKey {
    case name
    case rating
  }
  
  var name: String
  var rating: Float
  
  init(name: String, rating: Float, id: String? = nil) {
    self.name = name
    self.rating = rating
    // For example, set the collection name here for all instances of Food.
    super.init(collectionName: "food", id: id)
  }
  
  required init(from decoder: Decoder) throws {
    let dataContainer = try decoder.container(keyedBy: DataCodingKeys.self)
    let container = try dataContainer.nestedContainer(keyedBy: CodingKeys.self, forKey: .data)
    name = try container.decode(String.self, forKey: .name)
    rating = try container.decode(Float.self, forKey: .rating)
    try super.init(from: decoder)
  }
  
  override func encode(to encoder: Encoder) throws {
    var dataContainer = encoder.container(keyedBy: DataCodingKeys.self)
    var container = dataContainer.nestedContainer(keyedBy: CodingKeys.self, forKey: .data)
    try container.encode(name, forKey: .name)
    try container.encode(rating, forKey: .rating)
    try super.encode(to: encoder)
  }
}

client.add(collectionObject: Food(name: "Cheese Burger", rating: 4, id: "cheese-burger")) { result in /* ... */ }

// if you don't have an id on your side, just use nil as the ID and Stream will generate a unique ID
client.add(collectionObject: Food(name: "Cheese Burger", rating: 4)) { result in /* ... */ }

await client.collections.add(
  'food',
  {'name': 'Cheese Burger', 'rating': '4 stars'},
  entryId: 'cheese-burger',
 );

// if you don't have an id on your side, just use null as the ID and Stream will generate a unique ID
final entry = await client.collections
 .add('food', {'name': "Cheese Burger", 'rating': '4 stars'});

The max size of a collection can not exceed 50kB

Retrieving Collections

After adding an entry to a collection, you can also retrieve it easily by its ID.

Parameters

name	type	description	default	optional
collection	string	The name of the collection	-
entry_id	string	The id of the entry	-

await client.Collections.GetAsync("food", "cheese-burger");

let response = client.collections.get('food', 'cheese-burger');

client.collections.get("food", "cheese-burger")

client.collections.get("food", "cheese-burger")

$client->collections()->get("food", "cheese-burger");

CollectionData collection = client.collections().get("food", "cheese-burger").join();

resp, err := client.Collections().Get(context.TODO(), "food", "cheese-burger")
	if err != nil {
		panic(err)
	}

client.get(typeOf: Food.self, collectionName: "food", collectionObjectId: "cheese-burger") { result in /* ... */ }

await client.collections.get('food', entry.id!);

Removing Collections

An entry can also be removed from a collection with its ID.

Parameters

name	type	description	default	optional
collection	string	The name of the collection	-
entry_id	string	The id of the entry	-

await client.Collections.DeleteAsync("food", "cheese-burger");

let response = client.collections.delete('food', 'cheese-burger');

client.collections.delete("food", "cheese-burger")

client.collections.delete("food", "cheese-burger")

client.collections().delete("food", "cheese-burger").join();

_, err := client.Collections().Delete(context.TODO(), "food", "cheese-burger")
	if err != nil {
		panic(err)
	}

client.delete(collectionName: "food", collectionObjectId: "cheese-burger") { result in /* ... */ }

await client.collections.delete('food', entry.id!);

When you delete an entry from a collection any references will be converted to a missing reference error when reading feeds with enrichment.

Updating Collections

A collection’s entry data can be updated. Updates are propagated instantly to all activities embedding the entry.

Parameters

name	type	description	default
collection	string	The name of the collection	-
entry_id	string	The id of the entry	-
data	object	The data related to the user	-

var collectionData = new Dictionary<string, object>();
collectionData.Add("name", "Cheese Burger");
collectionData.Add("rating", "1 star");
await client.Collections.UpdateAsync("food", "cheese-burger", collectionData);

await client.collections.update('food', 'cheese-burger', { name: "Cheese Burger", rating: "1 star" });

client.collections.update("food", "cheese-burger", {"name": "Cheese Burger", "rating": "1 star"})

client.collections.update(
  "food", 
  "cheese-burger", 
  :data =&gt; {:name =&gt; "Cheese Burger", :rating =&gt; "1 stars"}
)

$client->collections()->update("food", "cheese-burger",
  ["name" => "Cheese Burger", "rating" => "1 stars"]);

client.collections().update("food", new CollectionData("cheese-burger")
    .set("name", "Cheese Burger")
    .set("rating", "1 star")).join();

resp, err := client.Collections().Update(context.TODO(), "food", "cheese-burger", map[string]any{
		"name":  "Cheese Burger",
		"rating": "1 star",
	})
	if err != nil {
		panic(err)
	}

client.update(collectionObject: Food(name: "Cheese Burger", rating: 1, id: "cheese-burger")) { result in /* ... */ }

await client.collections.update(
   entry.copyWith(data: {'name': 'Cheese Burger', 'rating': '1 star'}));

Updating Reactions

Batch Endpoints