Class: Aerospike::Exp::Map

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

Overview

Map expression generator. See 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.



141
142
143
144
 
# File 'lib/aerospike/exp/exp_map.rb', line 141

def self.clear(bin, ctx: nil)
  bytes = Exp.pack(ctx, CLEAR)
  return self.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).



398
399
400
401
 
# File 'lib/aerospike/exp/exp_map.rb', line 398

def self.get_by_index(return_type, value_type, index, bin, ctx: nil)
  bytes = Exp.pack(ctx, GET_BY_INDEX, return_type, index)
  return self.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.



405
406
407
408
409
410
411
412
 
# File 'lib/aerospike/exp/exp_map.rb', line 405

def self.get_by_index_range(return_type, index, bin, ctx: nil, count: nil)
  unless count.nil?
    bytes = Exp.pack(ctx, GET_BY_INDEX_RANGE, return_type, index, count)
  else
    bytes = Exp.pack(ctx, GET_BY_INDEX_RANGE, return_type, index)
  end
  return self.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



286
287
288
289
 
# File 'lib/aerospike/exp/exp_map.rb', line 286

def self.get_by_key(return_type, value_type, key, bin, ctx: nil)
  bytes = Exp.pack(ctx, GET_BY_KEY, return_type, key)
  return self.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).



303
304
305
306
 
# File 'lib/aerospike/exp/exp_map.rb', line 303

def self.get_by_key_list(return_type, keys, bin, ctx: nil)
  bytes = Exp.pack(ctx, GET_BY_KEY_LIST, return_type, keys)
  return self.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).



296
297
298
299
 
# File 'lib/aerospike/exp/exp_map.rb', line 296

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)
  return self.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]



319
320
321
322
 
# File 'lib/aerospike/exp/exp_map.rb', line 319

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)
  return self.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).



416
417
418
419
 
# File 'lib/aerospike/exp/exp_map.rb', line 416

def self.get_by_rank(return_type, value_type, rank, bin, ctx: nil)
  bytes = Exp.pack(ctx, GET_BY_RANK, return_type, rank)
  return self.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).



423
424
425
426
427
428
429
430
 
# File 'lib/aerospike/exp/exp_map.rb', line 423

def self.get_by_rank_range(return_type, rank, bin, ctx: nil, count: nil)
  unless count.nil?
    bytes = Exp.pack(ctx, GET_BY_RANK_RANGE, return_type, rank, count)
  else
    bytes = Exp.pack(ctx, GET_BY_RANK_RANGE, return_type, rank)
  end
  return self.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



357
358
359
360
 
# File 'lib/aerospike/exp/exp_map.rb', line 357

def self.get_by_value(return_type, value, bin, ctx: nil)
  bytes = Exp.pack(ctx, GET_BY_VALUE, return_type, value)
  return self.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).



374
375
376
377
 
# File 'lib/aerospike/exp/exp_map.rb', line 374

def self.get_by_value_list(return_type, values, bin, ctx: nil)
  bytes = Exp.pack(ctx, GET_BY_VALUE_LIST, return_type, values)
  return self.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).



367
368
369
370
 
# File 'lib/aerospike/exp/exp_map.rb', line 367

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)
  return self.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]



387
388
389
390
391
392
393
394
 
# File 'lib/aerospike/exp/exp_map.rb', line 387

def self.get_by_value_relative_rank_range(return_type, value, rank, bin, ctx: nil, count: nil)
  unless count.nil?
    bytes = Exp.pack(ctx, GET_BY_VALUE_REL_RANK_RANGE, return_type, value, rank, count)
  else
    bytes = Exp.pack(ctx, GET_BY_VALUE_REL_RANK_RANGE, return_type, value, rank)
  end
  return self.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.



135
136
137
138
 
# File 'lib/aerospike/exp/exp_map.rb', line 135

def self.increment(key, incr, bin, ctx: nil, policy: CDT::MapPolicy::DEFAULT)
  bytes = Exp.pack(ctx, INCREMENT, key, incr, policy.attributes)
  return self.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
101
102
 
# 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)
    else
      if policy.item_command == REPLACE
        # Replace doesn't allow map attributes because it does not create on non-existing key.
        Exp.pack_ctx(packer, ctx)
        packer.write_array_header(3)
        packer.write(policy.item_command)
        key.pack(packer)
        value.pack(packer)
      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
    end
    self.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.



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

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)
    else
      if policy.items_command == REPLACE_ITEMS
        # Replace doesn't allow map attributes because it does not create on non-existing key.
        Exp.pack_ctx(packer, ctx)
        packer.write_array_header(2)
        packer.write(policy.items_command)
        map.pack(packer)
      else
        Exp.pack_ctx(packer, ctx)
        packer.write_array_header(3)
        packer.write(policy.items_command)
        map.pack(packer)
        packer.write(policy.attributes)
      end
    end
    self.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.



230
231
232
233
 
# File 'lib/aerospike/exp/exp_map.rb', line 230

def self.remove_by_index(index, bin, ctx: nil)
  bytes = Exp.pack(ctx, REMOVE_BY_INDEX, CDT::MapReturnType::NONE, index)
  return self.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.



236
237
238
239
240
241
242
243
 
# File 'lib/aerospike/exp/exp_map.rb', line 236

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

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

Create expression that removes map item identified by key.



147
148
149
150
 
# File 'lib/aerospike/exp/exp_map.rb', line 147

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

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

Create expression that removes map items identified by keys.



153
154
155
156
 
# File 'lib/aerospike/exp/exp_map.rb', line 153

def self.remove_by_key_list(keys, bin, ctx: nil)
  bytes = Exp.pack(ctx, REMOVE_BY_KEY_LIST, CDT::MapReturnType::NONE, keys)
  return self.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.



161
162
163
164
 
# File 'lib/aerospike/exp/exp_map.rb', line 161

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)
  return self.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]



176
177
178
179
180
181
182
183
 
# File 'lib/aerospike/exp/exp_map.rb', line 176

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

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

Create expression that removes map item identified by rank.



246
247
248
249
 
# File 'lib/aerospike/exp/exp_map.rb', line 246

def self.remove_by_rank(rank, bin, ctx: nil)
  bytes = Exp.pack(ctx, REMOVE_BY_RANK, CDT::MapReturnType::NONE, rank)
  return self.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



253
254
255
256
257
258
259
260
 
# File 'lib/aerospike/exp/exp_map.rb', line 253

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

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

Create expression that removes map items identified by value.



186
187
188
189
 
# File 'lib/aerospike/exp/exp_map.rb', line 186

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

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

Create expression that removes map items identified by values.



192
193
194
195
 
# File 'lib/aerospike/exp/exp_map.rb', line 192

def self.remove_by_value_list(values, bin, ctx: nil)
  bytes = Exp.pack(ctx, REMOVE_BY_VALUE_LIST, CDT::MapReturnType::NONE, values)
  return self.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.



200
201
202
203
 
# File 'lib/aerospike/exp/exp_map.rb', line 200

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)
  return self.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]



212
213
214
215
 
# File 'lib/aerospike/exp/exp_map.rb', line 212

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)
  return self.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))



267
268
269
270
 
# File 'lib/aerospike/exp/exp_map.rb', line 267

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