Get Values By Score Range

Description

This operation returns values for a range of scores.

Method

Objective-CSwift

[[[Backendless.shared hive:(NSString *)hiveName] sortedSetStore:(NSString *)keyName] getRangeByScoreWithOptions:(RangeByScoreOptions *)options responseHandler:^(NSArray *)responseHandler errorHandler:^(Fault *)errorHandler];

Backendless.shared.hive(hiveName: String).sortedSetStore(keyName: String).getRangeByScore(options: RangeByScoreOptions, responseHandler: (([Any]) -> 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.
options	Is the RangeByScoreOptions object, consisting of parameters that control the behavior of this operation. See the description below.

RangeByScoreOptions is an object with the structure provided below:

Objective-CSwift

@interface RangeByScoreOptions : NSObject

@property (nonatomic) double minScore;
@property (nonatomic) double maxScore;
@property (nonatomic) enum SortedSetBound minBound;
@property (nonatomic) enum SortedSetBound maxBound;
@property (nonatomic) NSInteger offset;
@property (nonatomic) NSInteger count;
@property (nonatomic) BOOL reverse;
@property (nonatomic) BOOL withScores;

@end

@objcMembers public class RangeByScoreOptions: NSObject {
    public var minScore = 0.0
    public var maxScore = 0.0
    public var minBound = SortedSetBound.include
    public var maxBound = SortedSetBound.include
    public var offset = 0
    public var count = 20
    public var reverse = false
    public var withScores = false
}

where:

Argument	Description
minScore/maxScore	Optional parameters. Score values between which the items are requested. To control whether the specified values are included or excluded from the range, use the minBound/maxBound parameters(See the SortedSetBound enum below).
minBound/maxBound	Optional parameter. Is a enum containing parameters that control the presence of the first and last values in the range. See the description below this table.
offset	Optional parameter. Sets a zero-based index/position from which to retrieve the items. For example, if the resulting set contains 10 items, then by setting the offset parameter to 2, the first 2 values in the range will be skipped, while the remaining 8 returned in the response.
count	Optional parameter. If not set, defaults to 20. Sets the number of items to include in the response. Maximum supported value is 10000.
reverse	Optional parameter. When this parameter is not present, it defaults to false. When set to false, items in the specified sorted set are sorted in ascending order of their scores.  When set to true, items are sorted in descending order of their scores.
withScores	Optional parameter. When set to true, then the scores are returned along with the values. Otherwise, when set to false, the scores are not returned. When the parameter is not present, it defaults to false.

SortedSetBound is a enum with the structure shown below. The enum can be set to one of the following options: Include, Exclude or Infinity.

Objective-CSwift

typedef SWIFT_ENUM(NSInteger, SortedSetBound, closed) {
  SortedSetBoundInclude = 0,
  SortedSetBoundExclude = 1,
  SortedSetBoundInfinity = 2,
};

@objc public enum SortedSetBound: Int, Codable {
    case include
    case exclude
    case infinity
}

where:

Argument	Description
Include	Includes value specified in the corresponding minScore/maxScore parameter into the range.
Exclude	Excludes value specified in the corresponding minScore/maxScore parameter from the range.
Infinity	Ignores the corresponding minScore/maxScore parameter and includes all consecutive score values that come before/after the defined score range. For example, if minBound is set to Infinity and maxScore is set to 5, the query will include all values with scores less than 5.

Return Value

When the withScores parameter is set to true, the return value is an array of score-value pairs. Each pair is also an array of two elements - the score and the value.

Example

The example below returns all values in the range of scores between 0 and 3.

Consider the following sorted set data:

The example below returns values in the range of scores between 0 (inclusively) and to 3 (exclusively).

• Since the withScores parameter is set to true, the keys are returned alongside with the corresponding scores.
• Since the reverse parameter is set to true, the items are sorted by rank in descending order.
• The count parameter is set to 3, indicating that the service should return 3 items in the response.
• The offset parameter is set to 2, the returned items are included from the second (zero-based) position.

Objective-CSwift

RangeByScoreOptions *options = [RangeByScoreOptions new];
options.minScore = 0;
options.maxScore = 3;
options.minBound = SortedSetBoundInclude;
options.maxBound = SortedSetBoundExclude;
options.offset = 2;
options.count = 3;
options.reverse = true;
options.withScores = true;

[[[Backendless.shared hive:@"leaderboard"] sortedSetStore:@"players"] getRangeByScoreWithOptions:options responseHandler:^(NSArray<SortedSetItem *> *response) {
    // handle response
} errorHandler:^(Fault *fault) {
    // handle error
}];

let options = RangeByScoreOptions()
options.minScore = 0
options.maxScore = 3
options.minBound = .include
options.maxBound = .exclude
options.offset = 2
options.count = 3
options.reverse = true
options.withScores = true


Backendless.shared.hive("leaderboard").sortedSetStore("players").getRangeByScore(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 a sorted set where the operation takes place.

Response

[  
  [  
    2.45,  
    "Ken"  
  ],  
  [  
    2.3,  
    "Frank"  
  ],  
  [  
    2.25,  
    "Ana"  
  ]  
]

If the withScores parameter is set to false or is not present, the response does not include the scores:

[  
  "Ken",  
  "Frank",  
  "Ana"  
]

Codeless Reference

where:

Argument	Description
hive name	Name of a hive where the operation is performed.
key name	Key name identifying a sorted set.
min/max score	Score values between which the items are requested. To control whether the specified values are included or excluded from the range, use the min/max bound parameters.
min/max bound	Parameters that control the presence of the first and last values in the range. Each of these parameters has three options: Include - Includes value specified in the corresponding min score/max score parameter into the range. Exclude - Excludes value specified in the corresponding min score/max score parameter from the range. Infinity - Ignores the corresponding min score/max score parameter and includes all consecutive score values that come before/after the defined score range. For example, if min bound is set to Infinity and max score is set to 5, the query will include all values with scores less than 5. These parameters default to Include.
offset	Sets a zero-based index/position from which to retrieve the items. For example, if the resulting set contains 10 items, then by setting the offset parameter to 2, the first 2 values in the range will be skipped, while the remaining 8 returned in the response.
page size	If not set, defaults to 20. Sets the number of items to include in the response. Maximum supported value is 10000.
with score	When set to true, then the scores are returned along with the values. Otherwise, when set to false, the scores are not returned. When the parameter is not present, it defaults to false.
reverse	When set to true, items are sorted in ascending order. If set to false, items are sorted in descending order.

When the with score parameter is set to true, the return value is a list of score-value pairs. Each pair is also a list of two elements - the score and the value. When the with scores parameter is set to false, the return value is a list of values.

Consider the following Sorted Set storage:


The example below returns values in the range of scores between 0 (inclusively) and to 5 (inclusively).

• Since the with score parameter is set to true, the keys are returned alongside with the corresponding scores.
• Since the reverse parameter is set to true, the items are sorted by rank in descending order.
• The page size parameter is set to 3, indicating that the service should return 3 items in the response.
• The offset parameter is set to 1, the returned items are included from the first (zero-based) position.

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