Add Items¶

Description¶

This operation adds or updates values and scores in a sorted set.

Method¶

Objective-CSwift

[[[Backendless.shared hive:(NSString *)hiveName] sortedSetStore:(NSString *)keyName]addWithItems:(NSArray<SortedSetItem *> *)items options:(SortedSetItemOptions *)options responseHandler:^(NSInteger)responseHandler errorHandler:^(Fault *)errorHandler];

Backendless.shared.hive(hiveName: String).sortedSetStore(keyName: String).add(items: [SortedSetItem], options: SortedSetItemOptions, responseHandler: ((Int) -> Void)!, errorHandler: ((Fault) -> Void)!)

where:

Argument	Description
`hiveName`	Name of a hive where the operation is performed. String value.
`keyName`	Key name identifying a sorted-set. String value.
`items`	An array of items to add to the sorted set. Each element of the main array, must be a secondary/child array consisting of two parts: score as a number and the assigned value of any type.
`options`	A SortedSetItemOptions object with the structure shown below:

SortedSetItemOptions is an object with the following structure:

Objective-CSwift

@interface SortedSetItemOptions : NSObject

@property (nonatomic) enum DuplicateBehaviour duplicateBehaviour;
@property (nonatomic) enum ScoreUpdateMode scoreUpdateMode;
@property (nonatomic) enum ResultType resultType;

@end

@objcMembers public class SortedSetItemOptions: NSObject {
    public var duplicateBehaviour = DuplicateBehaviour.alwaysAdd
    public var scoreUpdateMode = ScoreUpdateMode.greater
    public var resultType = ResultType.newAdded
}

where:

Argument	Description
`duplicateBehavior`	Optional parameter. Controls how the duplicate values in the sorted set are handled.
`scoreUpdateMode`	Optional parameter. Enables conditional update based on the score of an item.
`resultType`	Optional parameter. Controls how the number of items added or updated is calculated for the return value.

duplicateBehavior is a enum with the structure provided below. The enum can be set to either OnlyUpdate or AlwaysAdd.

Objective-CSwift

typedef SWIFT_ENUM(NSInteger, DuplicateBehaviour, closed) {
  DuplicateBehaviourOnlyUpdate = 0,
  DuplicateBehaviourAlwaysAdd = 1,
};

@objc public enum DuplicateBehaviour: Int, Codable {
    case onlyUpdate
    case alwaysAdd
}

where:

Argument	Description
`OnlyUpdate`	Only values included in the request that already exist in the sorted set will be updated. New items won't be added.
`AlwaysAdd`	Existing items will not modified and new ones from the request are added.

ScoreUpdateMode is a enum with the structure provided below. The enum can be set to either Greater or Less options.

Objective-CSwift

typedef SWIFT_ENUM(NSInteger, ScoreUpdateMode, closed) {
  ScoreUpdateModeGreater = 0,
  ScoreUpdateModeLess = 1,
};

@objc public enum ScoreUpdateMode: Int, Codable {
    case greater
    case less
}

where:

Argument	Description
`Greater`	Existing items in the sorted set are updated if the new score is greater than the current score.
`Less`	Existing items in the sorted set are updated if the new score is less than the current score.

ResultType is a enum with the structure provided below. The enum can be set to either NewAdded or TotalChanged options. Defaults to NewAdded.

Objective-CSwift

typedef SWIFT_ENUM(NSInteger, ResultType, closed) {
  ResultTypeNewAdded = 0,
  ResultTypeTotalChanged = 1,
};

@objc public enum ResultType: Int, Codable {
    case newAdded
    case totalChanged
}

where:

Argument	Description
`NewAdded`	The operation returns the number of newly added items to the sorted set.
`TotalChanged`	The operation returns the number of the modified items.

Return Value¶

The number of added or updated items based on the resultType enum in the request. When resultType enum is set to the NewAdded option, the operation returns the number of newly added items to the sorted set. When resultType enum is set to the TotalChanged option, the operation returns the number of the modified items. If the parameter is not present in the request, the operation defaults to NewAdded.

Example¶

The example below adds the new item [25, "John"] to the "players" sorted set. If the item already exists in the sorted set, it is updated sinceduplicateBehaviour enum parameter is set to the OnlyUpdate option.

Objective-CSwift

SortedSetItem *item1 = [SortedSetItem new];
item1.score = 25
item1.value = @"John"

SortedSetItemOptions *options = [SortedSetItemOptions new];
options.duplicateBehaviour = DuplicateBehaviourOnlyUpdate;
options.scoreUpdateMode = ScoreUpdateModeGreater;
options.resultType = ResultTypeTotalChanged;

[[[Backendless.shared hive:@"leaderboard"] sortedSetStore:@"players"] addWithItems:@[item1, item2] options:options responseHandler:^(NSInteger response) {
    // handle response
} errorHandler:^(Fault *fault) {
    // handle error
}];

let item1 = SortedSetItem()
item1.score = 25
item1.value = "John"

let options = SortedSetItemOptions()
options.duplicateBehaviour = .onlyUpdate
options.scoreUpdateMode = .greater
options.resultType = .totalChanged

Backendless.shared.hive("leaderboard").sortedSetStore("players").add(items: [item1, item2], options: options, responseHandler: { response in
    // handle response
}, errorHandler: { fault in
    // handle error
})

where:

Argument	Description
`"leaderboard"`	Name of a hive in the system.
`"players"`	Name of the sorted set to perform the operation in.

Codeless Reference¶

sorted_set_api_add_key_items

where:

Argument	Description
`hive name`	Name of a hive where the operation is performed.
`key name`	Key name identifying a sorted set.
`items`	A list of containing scores and values to add to the sorted set. Every item in the main list is also a list consisting of two elements - a score and a value.
`duplicate behavior`	Controls how the duplicate values in the sorted set are handled. This parameter has two conditions: `Only Update` - Values included in the request that already exist in the sorted set will be updated. New items won't be added. `Always Add` - Existing items in the sorted set remain unmodified, while the new ones are added.
`score update mode`	Enables conditional update based on the score of an item. This parameter has two conditions: `Greater` - Existing items in the sorted set are updated if the new score is greater than the current score `Less` - Existing items in the sorted set are updated if the new score is less than the current score
`result type`	Controls how the number of items added or updated is calculated for the return value. This parameter has two conditions: `New Added` - When set to this option, the operation returns the number of newly added items to the sorted set. `Total Changed` - When set to this option, the operation returns the number of the modified items.

The operation returns the number of added or updated items based on the result type parameter in the request. When result type is set to the New Added option, the operation returns the number of newly added items to the sorted set. When result type is set to the Total Changed option, the operation returns the number of the modified items. If the parameter is not present in the request, the operation defaults to New Added.

Consider the following Sorted Set storage:
sorted_set_api_example_all_blocks

The example below adds two new score-value pairs [23,"Mike"] and [33,"Peter"] to the "players" sorted set.
sorted_set_api_example_add_key_items

The output will look as shown below after the Codeless logic runs: