class Aerospike::Exp::Map

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

Constants

CLEAR
GET_BY_INDEX
GET_BY_INDEX_RANGE
GET_BY_KEY
GET_BY_KEY_INTERVAL
GET_BY_KEY_LIST
GET_BY_KEY_REL_INDEX_RANGE
GET_BY_RANK
GET_BY_RANK_RANGE
GET_BY_VALUE
GET_BY_VALUE_INTERVAL
GET_BY_VALUE_LIST
GET_BY_VALUE_REL_RANK_RANGE
INCREMENT
MODULE
PUT
PUT_ITEMS
REMOVE_BY_INDEX
REMOVE_BY_INDEX_RANGE
REMOVE_BY_KEY
REMOVE_BY_KEY_INTERVAL
REMOVE_BY_KEY_LIST
REMOVE_BY_KEY_REL_INDEX_RANGE
REMOVE_BY_RANK
REMOVE_BY_RANK_RANGE
REMOVE_BY_VALUE
REMOVE_BY_VALUE_INTERVAL
REMOVE_BY_VALUE_LIST
REMOVE_BY_VALUE_REL_RANK_RANGE
REPLACE
REPLACE_ITEMS
SIZE

Public Class Methods

add_read(bin, bytes, ret_type) click to toggle source
# File lib/aerospike/exp/exp_map.rb, line 472
def self.add_read(bin, bytes, ret_type)
  Exp::Module.new(bin, bytes, ret_type, MODULE)
end
add_write(bin, bytes, ctx) click to toggle source
# File lib/aerospike/exp/exp_map.rb, line 463
def self.add_write(bin, bytes, ctx)
  ret_type = if ctx.to_a.empty?
    Exp::Type::MAP
             else
    (ctx[0].id & 0x10) == 0 ? Exp::Type::MAP : Exp::Type::LIST
             end
  Exp::Module.new(bin, bytes, ret_type, MODULE | Exp::MODIFY)
end
clear(bin, ctx: nil) click to toggle source

Create expression that removes all items in map.

# 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) click to toggle source

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

# 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) click to toggle source

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.

# 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) click to toggle source

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))

@param return_type metadata attributes to return. See {MapReturnType} @param value_type expected type of return value @param key map key expression @param bin bin or map value expression @param ctx optional context path for nested CDT

# 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) click to toggle source

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

# 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) click to toggle source

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}).

# 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) click to toggle source

Create expression that selects map items nearest to key and greater by index with a coun. Expression returns selected data specified by return_type (See {MapReturnType}).

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

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

# 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) click to toggle source

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

# 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) click to toggle source

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}).

# 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) click to toggle source

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))

@param return_type metadata attributes to return. See {MapReturnType} @param value value expression @param bin bin or map value expression @param ctx optional context path for nested CDT

# 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) click to toggle source

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

# 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) click to toggle source

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}).

# 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) click to toggle source

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}]

# 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
get_value_type(return_type) click to toggle source
# File lib/aerospike/exp/exp_map.rb, line 476
def self.get_value_type(return_type)
  t = return_type & ~CDT::MapReturnType::INVERTED
  case t
  when CDT::MapReturnType::INDEX, CDT::MapReturnType::REVERSE_INDEX, CDT::MapReturnType::RANK, CDT::MapReturnType::REVERSE_RANK
      # This method only called from expressions that can return multiple integers (ie list).
      Exp::Type::LIST

  when CDT::MapReturnType::COUNT
      Exp::Type::INT

  when CDT::MapReturnType::KEY, CDT::MapReturnType::VALUE
      # This method only called from expressions that can return multiple objects (ie list).
      Exp::Type::LIST

  when CDT::MapReturnType::KEY_VALUE, CDT::MapReturnType::ORDERED_MAP, CDT::MapReturnType::UNORDERED_MAP
      Exp::Type::MAP

  when CDT::MapReturnType::EXISTS
      Exp::Type::BOOL

  else
      raise Exceptions::Aerospike.new(Aerospike::ResultCode::PARAMETER_ERROR, "Invalid MapReturnType: #{return_type}")
  end
end
increment(key, incr, bin, ctx: nil, policy: CDT::MapPolicy::DEFAULT) click to toggle source

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

# 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) click to toggle source
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 entry{11,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 entry{11,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))
# 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) click to toggle source

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

# 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) click to toggle source

Create expression that removes map item identified by index.

# 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) click to toggle source

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

# 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) click to toggle source

Create expression that removes map item identified by key.

# 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) click to toggle source

Create expression that removes map items identified by keys.

# 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) click to toggle source

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.

# 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) click to toggle source

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}]

# 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) click to toggle source

Create expression that removes map item identified by rank.

# 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) click to toggle source

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

# 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) click to toggle source

Create expression that removes map items identified by value.

# 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) click to toggle source

Create expression that removes map items identified by values.

# 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) click to toggle source

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.

# 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, bin, ctx: nil) click to toggle source

Create expression that removes map items nearest to value and greater by relative rank.

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

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

# 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) click to toggle source

Create expression that returns list size.

Examples

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

# 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