Class: Aerospike::Exp::Map

Inherits:
Object
  • Object
show all
Defined in:
lib/aerospike/exp/exp_map.rb

Overview

Map expression generator. See Aerospike::Exp.

The bin expression argument in these methods can be a reference to a bin or the result of another expression. Expressions that modify bin values are only used for temporary expression evaluation and are not permanently applied to the bin.

Map modify expressions return the bin’s value. This value will be a map except when the map is nested within a list. In that case, a list is returned for the map modify expression.

All maps maintain an index and a rank. The index is the item offset from the start of the map, for both unordered and ordered maps. The rank is the sorted index of the value component. Map supports negative indexing for index and rank.

Index examples:

Index 0: First item in map. Index 4: Fifth item in map. Index -1: Last item in map. Index -3: Third to last item in map. Index 1 Count 2: Second and third items in map. Index -3 Count 3: Last three items in map. Index -5 Count 4: Range between fifth to last item to second to last item inclusive.

Rank examples:

Rank 0: Item with lowest value rank in map. Rank 4: Fifth lowest ranked item in map. Rank -1: Item with highest ranked value in map. Rank -3: Item with third highest ranked value in map. Rank 1 Count 2: Second and third lowest ranked items in map. Rank -3 Count 3: Top three ranked items in map.

Nested expressions are supported by optional CTX context arguments. Example:

bin = key1={key11=9,key12=4, key2=key21=3,key22=5} Set map value to 11 for map key “key21” inside of map key “key2”. Get size of map key2. MapExp.size(mapBin(“bin”), CTX.mapKey(Value.get(“key2”)) result = 2

Class Method Summary collapse

Class Method Details

.clear(bin, ctx: nil) ⇒ Object

Create expression that removes all items in map.



137
138
139
140
 
# File 'lib/aerospike/exp/exp_map.rb', line 137

def self.clear(bin, ctx: nil)
  bytes = Exp.pack(ctx, CLEAR)
  add_write(bin, bytes, ctx)
end

.get_by_index(return_type, value_type, index, bin, ctx: nil) ⇒ Object

Create expression that selects map item identified by index and returns selected data specified by return_type (See MapReturnType).



394
395
396
397
 
# File 'lib/aerospike/exp/exp_map.rb', line 394

def self.get_by_index(return_type, value_type, index, bin, ctx: nil)
  bytes = Exp.pack(ctx, GET_BY_INDEX, return_type, index)
  add_read(bin, bytes, value_type)
end

.get_by_index_range(return_type, index, bin, ctx: nil, count: nil) ⇒ Object

Create expression that selects map items starting at specified index to the end of map and returns selected data specified by return_type (See MapReturnType) limited by count if provided.



401
402
403
404
405
406
407
408
 
# File 'lib/aerospike/exp/exp_map.rb', line 401

def self.get_by_index_range(return_type, index, bin, ctx: nil, count: nil)
  bytes = if count.nil?
    Exp.pack(ctx, GET_BY_INDEX_RANGE, return_type, index)
          else
    Exp.pack(ctx, GET_BY_INDEX_RANGE, return_type, index, count)
          end
  add_read(bin, bytes, get_value_type(return_type))
end

.get_by_key(return_type, value_type, key, bin, ctx: nil) ⇒ Object

Create expression that selects map item identified by key and returns selected data specified by return_type.

Examples

# Map bin “a” contains key “B” Exp.gt(

MapExp.getByKey(CDT::MapReturnType::COUNT, Exp::Type::INT, Exp.val("B"), Exp.mapBin("a")),
Exp.val(0))

Parameters:

  • return_type —

    metadata attributes to return. See MapReturnType

  • value_type —

    expected type of return value

  • key —

    map key expression

  • bin —

    bin or map value expression

  • ctx (defaults to: nil) —

    optional context path for nested CDT



282
283
284
285
 
# File 'lib/aerospike/exp/exp_map.rb', line 282

def self.get_by_key(return_type, value_type, key, bin, ctx: nil)
  bytes = Exp.pack(ctx, GET_BY_KEY, return_type, key)
  add_read(bin, bytes, value_type)
end

.get_by_key_list(return_type, keys, bin, ctx: nil) ⇒ Object

Create expression that selects map items identified by keys and returns selected data specified by return_type (See MapReturnType).



299
300
301
302
 
# File 'lib/aerospike/exp/exp_map.rb', line 299

def self.get_by_key_list(return_type, keys, bin, ctx: nil)
  bytes = Exp.pack(ctx, GET_BY_KEY_LIST, return_type, keys)
  add_read(bin, bytes, get_value_type(return_type))
end

.get_by_key_range(return_type, key_begin, key_end, bin, ctx: nil) ⇒ Object

Create expression that selects map items identified by key range (key_begin inclusive, key_end exclusive). If key_begin is nil, the range is less than key_end. If key_end is nil, the range is greater than equal to key_begin.

Expression returns selected data specified by return_type (See MapReturnType).



292
293
294
295
 
# File 'lib/aerospike/exp/exp_map.rb', line 292

def self.get_by_key_range(return_type, key_begin, key_end, bin, ctx: nil)
  bytes = Exp::List.pack_range_operation(GET_BY_KEY_INTERVAL, return_type, key_begin, key_end, ctx)
  add_read(bin, bytes, get_value_type(return_type))
end

.get_by_key_relative_index_range(return_type, key, index, bin, ctx: nil, count: nil) ⇒ Object

Create expression that selects map items nearest to key and greater by index with a count limit if provided. Expression returns selected data specified by return_type (See MapReturnType).

Examples for ordered map [0=17,4=2,5=15,9=10]:

(value,index,count) = [selected items] (5,0,1) = [5=15] (5,1,2) = [9=10] (5,-1,1) = [4=2] (3,2,1) = [9=10] (3,-2,2) = [0=17]



315
316
317
318
 
# File 'lib/aerospike/exp/exp_map.rb', line 315

def self.get_by_key_relative_index_range(return_type, key, index, bin, ctx: nil)
  bytes = Exp.pack(ctx, GET_BY_KEY_REL_INDEX_RANGE, return_type, key, index)
  add_read(bin, bytes, get_value_type(return_type))
end

.get_by_rank(return_type, value_type, rank, bin, ctx: nil) ⇒ Object

Create expression that selects map item identified by rank and returns selected data specified by return_type (See MapReturnType).



412
413
414
415
 
# File 'lib/aerospike/exp/exp_map.rb', line 412

def self.get_by_rank(return_type, value_type, rank, bin, ctx: nil)
  bytes = Exp.pack(ctx, GET_BY_RANK, return_type, rank)
  add_read(bin, bytes, value_type)
end

.get_by_rank_range(return_type, rank, bin, ctx: nil, count: nil) ⇒ Object

Create expression that selects map items starting at specified rank to the last ranked item and returns selected data specified by return_type (See MapReturnType).



419
420
421
422
423
424
425
426
 
# File 'lib/aerospike/exp/exp_map.rb', line 419

def self.get_by_rank_range(return_type, rank, bin, ctx: nil, count: nil)
  bytes = if count.nil?
    Exp.pack(ctx, GET_BY_RANK_RANGE, return_type, rank)
          else
    Exp.pack(ctx, GET_BY_RANK_RANGE, return_type, rank, count)
          end
  add_read(bin, bytes, get_value_type(return_type))
end

.get_by_value(return_type, value, bin, ctx: nil) ⇒ Object

Create expression that selects map items identified by value and returns selected data specified by return_type.

Examples

# Map bin “a” contains value “BBB” Exp.gt(

MapExp.getByValue(CDT::MapReturnType::COUNT, Exp.val("BBB"), Exp.mapBin("a")),
Exp.val(0))

Parameters:

  • return_type —

    metadata attributes to return. See MapReturnType

  • value —

    value expression

  • bin —

    bin or map value expression

  • ctx (defaults to: nil) —

    optional context path for nested CDT



353
354
355
356
 
# File 'lib/aerospike/exp/exp_map.rb', line 353

def self.get_by_value(return_type, value, bin, ctx: nil)
  bytes = Exp.pack(ctx, GET_BY_VALUE, return_type, value)
  add_read(bin, bytes, get_value_type(return_type))
end

.get_by_value_list(return_type, values, bin, ctx: nil) ⇒ Object

Create expression that selects map items identified by values and returns selected data specified by return_type (See MapReturnType).



370
371
372
373
 
# File 'lib/aerospike/exp/exp_map.rb', line 370

def self.get_by_value_list(return_type, values, bin, ctx: nil)
  bytes = Exp.pack(ctx, GET_BY_VALUE_LIST, return_type, values)
  add_read(bin, bytes, get_value_type(return_type))
end

.get_by_value_range(return_type, valueBegin, valueEnd, bin, ctx: nil) ⇒ Object

Create expression that selects map items identified by value range (valueBegin inclusive, valueEnd exclusive) If valueBegin is nil, the range is less than valueEnd. If valueEnd is nil, the range is greater than equal to valueBegin.

Expression returns selected data specified by return_type (See MapReturnType).



363
364
365
366
 
# File 'lib/aerospike/exp/exp_map.rb', line 363

def self.get_by_value_range(return_type, valueBegin, valueEnd, bin, ctx: nil)
  bytes = Exp::List.pack_range_operation(GET_BY_VALUE_INTERVAL, return_type, valueBegin, valueEnd, ctx)
  add_read(bin, bytes, get_value_type(return_type))
end

.get_by_value_relative_rank_range(return_type, value, rank, bin, ctx: nil, count: nil) ⇒ Object

Create expression that selects map items nearest to value and greater by relative rank (with a count limit if passed). Expression returns selected data specified by return_type (See MapReturnType).

Examples for map [4=2,9=10,5=15,0=17]:

(value,rank) = [selected items] (11,1) = [0=17] (11,-1) = [9=10,5=15,0=17]



383
384
385
386
387
388
389
390
 
# File 'lib/aerospike/exp/exp_map.rb', line 383

def self.get_by_value_relative_rank_range(return_type, value, rank, bin, ctx: nil, count: nil)
  bytes = if count.nil?
    Exp.pack(ctx, GET_BY_VALUE_REL_RANK_RANGE, return_type, value, rank)
          else
    Exp.pack(ctx, GET_BY_VALUE_REL_RANK_RANGE, return_type, value, rank, count)
          end
  add_read(bin, bytes, get_value_type(return_type))
end

.increment(key, incr, bin, ctx: nil, policy: CDT::MapPolicy::DEFAULT) ⇒ Object

Create expression that increments values by incr for all items identified by key. Valid only for numbers.



131
132
133
134
 
# File 'lib/aerospike/exp/exp_map.rb', line 131

def self.increment(key, incr, bin, ctx: nil, policy: CDT::MapPolicy::DEFAULT)
  bytes = Exp.pack(ctx, INCREMENT, key, incr, policy.attributes)
  add_write(bin, bytes, ctx)
end

.put(key, value, bin, ctx: nil, policy: CDT::MapPolicy::DEFAULT) ⇒ Object

Create expression that writes key/value item to a map bin. The ‘bin’ expression should either reference an existing map bin or be a expression that returns a map.

Examples

# Add entry11,22 to existing map bin. e = Exp.build(MapExp.put(MapPolicy.Default, Exp.val(11), Exp.val(22), Exp.mapBin(binName))) client.operate(key, ExpOperation.write(binName, e, Exp::WriteFlags::DEFAULT)) ctx, # Combine entry11,22 with source map’s first index entry and write resulting map to target map bin. e = Exp.build(

MapExp.put(MapPolicy.Default, Exp.val(11), Exp.val(22),
  MapExp.getByIndexRange(CDT::MapReturnType::KEY_VALUE, Exp.val(0), Exp.val(1), Exp.mapBin(sourceBinName)))
)

client.operate(key, ExpOperation.write(target_bin_name, e, Exp::WriteFlags::DEFAULT))



73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
 
# File 'lib/aerospike/exp/exp_map.rb', line 73

def self.put(key, value, bin, ctx: nil, policy: CDT::MapPolicy::DEFAULT)
  Packer.use do |packer|
    if policy.flags != 0
      Exp.pack_ctx(packer, ctx)
      packer.write_array_header(5)
      packer.write(PUT)
      key.pack(packer)
      value.pack(packer)
      packer.write(policy.attributes)
      packer.write(policy.flags)
    elsif policy.item_command == REPLACE
      Exp.pack_ctx(packer, ctx)
      packer.write_array_header(3)
      packer.write(policy.item_command)
      key.pack(packer)
      value.pack(packer)
    # Replace doesn't allow map attributes because it does not create on non-existing key.
    else
        Exp.pack_ctx(packer, ctx)
        packer.write_array_header(4)
        packer.write(policy.item_command)
        key.pack(packer)
        value.pack(packer)
        packer.write(policy.attributes)
    end
    add_write(bin, packer.bytes, ctx)
  end
end

.put_items(map, bin, ctx: nil, policy: CDT::MapPolicy::DEFAULT) ⇒ Object

Create expression that writes each map item to a map bin.



103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
 
# File 'lib/aerospike/exp/exp_map.rb', line 103

def self.put_items(map, bin, ctx: nil, policy: CDT::MapPolicy::DEFAULT)
  Packer.use do |packer|
    if policy.flags != 0
      Exp.pack_ctx(packer, ctx)
      packer.write_array_header(4)
      packer.write(PUT_ITEMS)
      map.pack(packer)
      packer.write(policy.attributes)
      packer.write(policy.flags)
    elsif policy.items_command == REPLACE_ITEMS
      Exp.pack_ctx(packer, ctx)
      packer.write_array_header(2)
      packer.write(policy.items_command)
      map.pack(packer)
    # Replace doesn't allow map attributes because it does not create on non-existing key.
    else
        Exp.pack_ctx(packer, ctx)
        packer.write_array_header(3)
        packer.write(policy.items_command)
        map.pack(packer)
        packer.write(policy.attributes)
    end
    add_write(bin, packer.bytes, ctx)
  end
end

.remove_by_index(index, bin, ctx: nil) ⇒ Object

Create expression that removes map item identified by index.



226
227
228
229
 
# File 'lib/aerospike/exp/exp_map.rb', line 226

def self.remove_by_index(index, bin, ctx: nil)
  bytes = Exp.pack(ctx, REMOVE_BY_INDEX, CDT::MapReturnType::NONE, index)
  add_write(bin, bytes, ctx)
end

.remove_by_index_range(index, bin, ctx: nil, count: nil) ⇒ Object

Create expression that removes “count” map items starting at specified index limited by count if provided.



232
233
234
235
236
237
238
239
 
# File 'lib/aerospike/exp/exp_map.rb', line 232

def self.remove_by_index_range(index, bin, ctx: nil, count: nil)
  bytes = if count.nil?
    Exp.pack(ctx, REMOVE_BY_INDEX_RANGE, CDT::MapReturnType::NONE, index)
          else
    Exp.pack(ctx, REMOVE_BY_INDEX_RANGE, CDT::MapReturnType::NONE, index, count)
          end
  add_write(bin, bytes, ctx)
end

.remove_by_key(key, bin, ctx: nil) ⇒ Object

Create expression that removes map item identified by key.



143
144
145
146
 
# File 'lib/aerospike/exp/exp_map.rb', line 143

def self.remove_by_key(key, bin, ctx: nil)
  bytes = Exp.pack(ctx, REMOVE_BY_KEY, CDT::MapReturnType::NONE, key)
  add_write(bin, bytes, ctx)
end

.remove_by_key_list(keys, bin, ctx: nil) ⇒ Object

Create expression that removes map items identified by keys.



149
150
151
152
 
# File 'lib/aerospike/exp/exp_map.rb', line 149

def self.remove_by_key_list(keys, bin, ctx: nil)
  bytes = Exp.pack(ctx, REMOVE_BY_KEY_LIST, CDT::MapReturnType::NONE, keys)
  add_write(bin, bytes, ctx)
end

.remove_by_key_range(key_begin, key_end, bin, ctx: nil) ⇒ Object

Create expression that removes map items identified by key range (key_begin inclusive, key_end exclusive). If key_begin is nil, the range is less than key_end. If key_end is nil, the range is greater than equal to key_begin.



157
158
159
160
 
# File 'lib/aerospike/exp/exp_map.rb', line 157

def self.remove_by_key_range(key_begin, key_end, bin, ctx: nil)
  bytes = Exp::List.pack_range_operation(REMOVE_BY_KEY_INTERVAL, CDT::MapReturnType::NONE, key_begin, key_end, ctx)
  add_write(bin, bytes, ctx)
end

.remove_by_key_relative_index_range(key, index, bin, ctx: nil, count: nil) ⇒ Object

Create expression that removes map items nearest to key and greater by index with a count limit if provided.

Examples for map [0=17,4=2,5=15,9=10]:

(value,index,count) = [removed items] (5,0,1) = [5=15] (5,1,2) = [9=10] (5,-1,1) = [4=2] (3,2,1) = [9=10] (3,-2,2) = [0=17]



172
173
174
175
176
177
178
179
 
# File 'lib/aerospike/exp/exp_map.rb', line 172

def self.remove_by_key_relative_index_range(key, index, bin, ctx: nil, count: nil)
  bytes = if count.nil?
    Exp.pack(ctx, REMOVE_BY_KEY_REL_INDEX_RANGE, CDT::MapReturnType::NONE, key, index)
          else
    Exp.pack(ctx, REMOVE_BY_KEY_REL_INDEX_RANGE, CDT::MapReturnType::NONE, key, index, count)
          end
  add_write(bin, bytes, ctx)
end

.remove_by_rank(rank, bin, ctx: nil) ⇒ Object

Create expression that removes map item identified by rank.



242
243
244
245
 
# File 'lib/aerospike/exp/exp_map.rb', line 242

def self.remove_by_rank(rank, bin, ctx: nil)
  bytes = Exp.pack(ctx, REMOVE_BY_RANK, CDT::MapReturnType::NONE, rank)
  add_write(bin, bytes, ctx)
end

.remove_by_rank_range(rank, bin, ctx: nil, count: nil) ⇒ Object

Create expression that removes “count” map items starting at specified rank. If count is not provided, all items until the last ranked item will be removed



249
250
251
252
253
254
255
256
 
# File 'lib/aerospike/exp/exp_map.rb', line 249

def self.remove_by_rank_range(rank, bin, ctx: nil, count: nil)
  bytes = if count.nil?
    Exp.pack(ctx, REMOVE_BY_RANK_RANGE, CDT::MapReturnType::NONE, rank)
          else
    Exp.pack(ctx, REMOVE_BY_RANK_RANGE, CDT::MapReturnType::NONE, rank, count)
          end
  add_write(bin, bytes, ctx)
end

.remove_by_value(value, bin, ctx: nil) ⇒ Object

Create expression that removes map items identified by value.



182
183
184
185
 
# File 'lib/aerospike/exp/exp_map.rb', line 182

def self.remove_by_value(value, bin, ctx: nil)
  bytes = Exp.pack(ctx, REMOVE_BY_VALUE, CDT::MapReturnType::NONE, value)
  add_write(bin, bytes, ctx)
end

.remove_by_value_list(values, bin, ctx: nil) ⇒ Object

Create expression that removes map items identified by values.



188
189
190
191
 
# File 'lib/aerospike/exp/exp_map.rb', line 188

def self.remove_by_value_list(values, bin, ctx: nil)
  bytes = Exp.pack(ctx, REMOVE_BY_VALUE_LIST, CDT::MapReturnType::NONE, values)
  add_write(bin, bytes, ctx)
end

.remove_by_value_range(valueBegin, valueEnd, bin, ctx: nil) ⇒ Object

Create expression that removes map items identified by value range (valueBegin inclusive, valueEnd exclusive). If valueBegin is nil, the range is less than valueEnd. If valueEnd is nil, the range is greater than equal to valueBegin.



196
197
198
199
 
# File 'lib/aerospike/exp/exp_map.rb', line 196

def self.remove_by_value_range(valueBegin, valueEnd, bin, ctx: nil)
  bytes = Exp::List.pack_range_operation(REMOVE_BY_VALUE_INTERVAL, CDT::MapReturnType::NONE, valueBegin, valueEnd, ctx)
  add_write(bin, bytes, ctx)
end

.remove_by_value_relative_rank_range(value, rank, count, bin, ctx: nil) ⇒ Object

Create expression that removes map items nearest to value and greater by relative rank with a count limit.

Examples for map [4=2,9=10,5=15,0=17]:

(value,rank,count) = [removed items] (11,1,1) = [0=17] (11,-1,1) = [9=10]



208
209
210
211
 
# File 'lib/aerospike/exp/exp_map.rb', line 208

def self.remove_by_value_relative_rank_range(value, rank, bin, ctx: nil)
  bytes = Exp.pack(ctx, REMOVE_BY_VALUE_REL_RANK_RANGE, CDT::MapReturnType::NONE, value, rank)
  add_write(bin, bytes, ctx)
end

.size(bin, ctx: nil) ⇒ Object

Create expression that returns list size.

Examples

# Map bin “a” size > 7 Exp.gt(MapExp.size(mapBin(“a”)), Exp.val(7))



263
264
265
266
 
# File 'lib/aerospike/exp/exp_map.rb', line 263

def self.size(bin, ctx: nil)
  bytes = Exp.pack(ctx, SIZE)
  add_read(bin, bytes, Exp::Type::INT)
end