Collections

Last Edit: Feb 02 2020

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 -


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 => "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" => "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]interface{}{
		"name":   "Cheese Burger",
		"rating": "4 stars",
	},
}
collection, err := client.Collections().Add("food", obj)

//if you don't have an id on your side, Stream will generate a unique ID

obj := stream.CollectionObject{
	Data: map[string]interface{}{
		"name":   "Cheese Burger",
		"rating": "4 stars",
	},
}
collection, err := client.Collections().Add("food", obj)
                    

// 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 /* ... */ }
                    

var collectionData = new GenericData();
collectionData.SetData("name", "Cheese burger");
collectionData.SetData("rating", "4 stars");
await client.Collections.Add("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.Add("food", collectionData);
                    

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 -


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

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

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

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

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

collection, err := client.Collections().Get("food", "cheese-burger")
                    

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

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

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 -


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("food", "cheese-burger")
                    

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

await client.Collections.Delete("food", "cheese-burger");
                    
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 Optional
collection string The name of the collection -
entry_id string The id of the entry -
data object The data related to the user -


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 => {:name => "Cheese Burger", :rating => "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();
                    

collection, err := client.Collections().Update("food", "cheese-burger", map[string]interface{}{
	"name":   "Cheese Burger",
	"rating": "1 star",
})
                    

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

var collectionData = new GenericData();
collectionData.SetData("name", "Cheese Burger");
collectionData.SetData("rating", "1 star");
await client.Collections.Update("food", "cheese-burger", collectionData);