# `Aerospike.Op.Map`
[🔗](https://github.com/luisgabrielroldan/aerospike_driver/blob/v0.3.1/lib/aerospike/op/map.ex#L1)

Map CDT operations for `Aerospike.operate/4`.

These builders create server-side map operations. Pass `ctx:` for nested CDT
paths and `return_type:` for selector operations that can return keys,
values, key/value pairs, counts, ranks, indexes, or existence flags.

# `opts`

```elixir
@type opts() :: [
  ctx: Aerospike.Ctx.t(),
  return_type: return_type(),
  policy: policy(),
  persist_index: boolean()
]
```

Common map operation options.

Supported keys:

* `:ctx` - nested CDT context path from `Aerospike.Ctx`.
* `:return_type` - selector return type from the `return_*` helpers.
* `:policy` - map write policy for put/increment/decrement operations.
* `:persist_index` - persist the index for top-level ordered maps.

# `order`

```elixir
@type order() :: :unordered | :key_ordered | :key_value_ordered | raw_integer()
```

Map order attribute.

# `policy`

```elixir
@type policy() ::
  %{
    optional(:order) => order(),
    optional(:attr) => order(),
    optional(:flags) => write_flags()
  }
  | [order: order(), attr: order(), flags: write_flags()]
```

Map write policy accepted in `opts[:policy]`.

Prefer `:order` for the map order. `:attr` remains accepted for
compatibility. Omitted keys default to `0`.

# `raw_integer`

```elixir
@type raw_integer() :: non_neg_integer() | {:raw, non_neg_integer()}
```

Raw compatibility value for server integer policy constants.

# `return_type`

```elixir
@type return_type() ::
  :none
  | :index
  | :reverse_index
  | :rank
  | :reverse_rank
  | :count
  | :key
  | :value
  | :key_value
  | :exists
  | :unordered_map
  | :ordered_map
  | :inverted
  | [
      :inverted
      | :index
      | :reverse_index
      | :rank
      | :reverse_rank
      | :count
      | :key
      | :value
      | :key_value
      | :exists
      | :unordered_map
      | :ordered_map
    ]
  | raw_integer()
```

Map selector return type.

# `t`

```elixir
@opaque t()
```

Opaque map CDT operation for `Aerospike.operate/4`.

# `write_flag`

```elixir
@type write_flag() :: :default | :create_only | :update_only | :no_fail | :partial
```

Map write policy flag or flags.

# `write_flags`

```elixir
@type write_flags() :: write_flag() | [write_flag()] | raw_integer()
```

# `clear`

```elixir
@spec clear(String.t(), opts()) :: t()
```

Removes all entries from the map.

# `create`

```elixir
@spec create(String.t(), order(), opts()) :: t()
```

Creates a map at the selected context level.

When `ctx:` is omitted, this sets the top-level bin map order. Nested map
creation ignores `persist_index:` because server indexes are top-level only.

# `decrement`

```elixir
@spec decrement(String.t(), term(), term(), opts()) :: t()
```

Decrements the numeric value at `map_key` and returns the final value.

# `get_by_index`

```elixir
@spec get_by_index(String.t(), integer(), opts()) :: t()
```

Returns the entry at `index`, selected by `return_type:`.

# `get_by_index_range`

```elixir
@spec get_by_index_range(String.t(), integer(), integer(), opts()) :: t()
```

Returns `count` entries from `index`, selected by `return_type:`.

# `get_by_index_range_from`

```elixir
@spec get_by_index_range_from(String.t(), integer(), opts()) :: t()
```

Returns entries from `index` through the end, selected by `return_type:`.

# `get_by_key`

```elixir
@spec get_by_key(String.t(), term(), opts()) :: t()
```

Returns the entry for `map_key`, selected by `return_type:`.

# `get_by_key_list`

```elixir
@spec get_by_key_list(String.t(), list(), opts()) :: t()
```

Returns entries matching any key in `keys`, selected by `return_type:`.

# `get_by_key_range`

```elixir
@spec get_by_key_range(String.t(), term(), term(), opts()) :: t()
```

Returns entries with keys in `[begin_key, end_key)`, selected by `return_type:`.

Pass `nil` for an open range boundary.

# `get_by_key_rel_index_range`

```elixir
@spec get_by_key_rel_index_range(String.t(), term(), integer(), opts()) :: t()
```

Returns entries nearest to `map_key` and greater by relative `index`.

# `get_by_key_rel_index_range_count`

```elixir
@spec get_by_key_rel_index_range_count(
  String.t(),
  term(),
  integer(),
  integer(),
  opts()
) :: t()
```

Returns `count` entries nearest to `map_key` and greater by relative `index`.

# `get_by_rank`

```elixir
@spec get_by_rank(String.t(), integer(), opts()) :: t()
```

Returns the entry at `rank`, selected by `return_type:`.

# `get_by_rank_range`

```elixir
@spec get_by_rank_range(String.t(), integer(), integer(), opts()) :: t()
```

Returns `count` entries from `rank`, selected by `return_type:`.

# `get_by_rank_range_from`

```elixir
@spec get_by_rank_range_from(String.t(), integer(), opts()) :: t()
```

Returns entries from `rank` through the highest rank, selected by `return_type:`.

# `get_by_value`

```elixir
@spec get_by_value(String.t(), term(), opts()) :: t()
```

Returns entries equal to `value`, selected by `return_type:`.

# `get_by_value_list`

```elixir
@spec get_by_value_list(String.t(), list(), opts()) :: t()
```

Returns entries matching any value in `values`, selected by `return_type:`.

# `get_by_value_range`

```elixir
@spec get_by_value_range(String.t(), term(), term(), opts()) :: t()
```

Returns entries with values in `[begin_value, end_value)`, selected by `return_type:`.

Pass `nil` for an open range boundary.

# `get_by_value_rel_rank_range`

```elixir
@spec get_by_value_rel_rank_range(String.t(), term(), integer(), opts()) :: t()
```

Returns entries nearest to `value` and greater by relative `rank`.

# `get_by_value_rel_rank_range_count`

```elixir
@spec get_by_value_rel_rank_range_count(
  String.t(),
  term(),
  integer(),
  integer(),
  opts()
) :: t()
```

Returns `count` entries nearest to `value` and greater by relative `rank`.

# `increment`

```elixir
@spec increment(String.t(), term(), term(), opts()) :: t()
```

Increments the numeric value at `map_key` and returns the final value.

# `order_key_ordered`

```elixir
@spec order_key_ordered() :: 1
```

Create maps ordered by key.

# `order_key_value_ordered`

```elixir
@spec order_key_value_ordered() :: 3
```

Create maps ordered by key and value.

# `order_unordered`

```elixir
@spec order_unordered() :: 0
```

Create unordered maps by default.

# `put`

```elixir
@spec put(String.t(), term(), term(), opts()) :: t()
```

Writes one key/value pair and returns the map size.

Pass `policy: [order: order, flags: flags]` to include map order attributes
and write flags in the operation payload.

# `put_items`

```elixir
@spec put_items(String.t(), map(), opts()) :: t()
```

Writes multiple key/value pairs and returns the map size.

Pass `policy: [order: order, flags: flags]` to include map order attributes
and write flags in the operation payload.

# `remove_by_index`

```elixir
@spec remove_by_index(String.t(), integer(), opts()) :: t()
```

Removes the entry at `index`, returning data selected by `return_type:`.

# `remove_by_index_range`

```elixir
@spec remove_by_index_range(String.t(), integer(), integer(), opts()) :: t()
```

Removes `count` entries from `index`, returning selected data.

# `remove_by_index_range_from`

```elixir
@spec remove_by_index_range_from(String.t(), integer(), opts()) :: t()
```

Removes entries from `index` through the end, returning selected data.

# `remove_by_key`

```elixir
@spec remove_by_key(String.t(), term(), opts()) :: t()
```

Removes the entry for `map_key`, returning data selected by `return_type:`.

# `remove_by_key_list`

```elixir
@spec remove_by_key_list(String.t(), list(), opts()) :: t()
```

Removes entries matching any key in `keys`, returning selected data.

# `remove_by_key_range`

```elixir
@spec remove_by_key_range(String.t(), term(), term(), opts()) :: t()
```

Removes entries with keys in `[begin_key, end_key)`, returning selected data.

Pass `nil` for an open range boundary.

# `remove_by_key_rel_index_range`

```elixir
@spec remove_by_key_rel_index_range(String.t(), term(), integer(), opts()) :: t()
```

Removes entries nearest to `map_key` and greater by relative `index`.

# `remove_by_key_rel_index_range_count`

```elixir
@spec remove_by_key_rel_index_range_count(
  String.t(),
  term(),
  integer(),
  integer(),
  opts()
) :: t()
```

Removes `count` entries nearest to `map_key` and greater by relative `index`.

# `remove_by_rank`

```elixir
@spec remove_by_rank(String.t(), integer(), opts()) :: t()
```

Removes the entry at `rank`, returning data selected by `return_type:`.

# `remove_by_rank_range`

```elixir
@spec remove_by_rank_range(String.t(), integer(), integer(), opts()) :: t()
```

Removes `count` entries from `rank`, returning selected data.

# `remove_by_rank_range_from`

```elixir
@spec remove_by_rank_range_from(String.t(), integer(), opts()) :: t()
```

Removes entries from `rank` through the highest rank, returning selected data.

# `remove_by_value`

```elixir
@spec remove_by_value(String.t(), term(), opts()) :: t()
```

Removes entries equal to `value`, returning data selected by `return_type:`.

# `remove_by_value_list`

```elixir
@spec remove_by_value_list(String.t(), list(), opts()) :: t()
```

Removes entries matching any value in `values`, returning selected data.

# `remove_by_value_range`

```elixir
@spec remove_by_value_range(String.t(), term(), term(), opts()) :: t()
```

Removes entries with values in `[begin_value, end_value)`, returning selected data.

Pass `nil` for an open range boundary.

# `remove_by_value_rel_rank_range`

```elixir
@spec remove_by_value_rel_rank_range(String.t(), term(), integer(), opts()) :: t()
```

Removes entries nearest to `value` and greater by relative `rank`.

# `remove_by_value_rel_rank_range_count`

```elixir
@spec remove_by_value_rel_rank_range_count(
  String.t(),
  term(),
  integer(),
  integer(),
  opts()
) :: t()
```

Removes `count` entries nearest to `value` and greater by relative `rank`.

# `return_count`

```elixir
@spec return_count() :: 5
```

Return the selected item count.

# `return_exists`

```elixir
@spec return_exists() :: 13
```

Return whether matching entries exist.

# `return_index`

```elixir
@spec return_index() :: 1
```

Return selected item indexes.

# `return_inverted`

```elixir
@spec return_inverted() :: 65536
```

Invert the selector so it applies outside the matched range.

# `return_key`

```elixir
@spec return_key() :: 6
```

Return selected keys.

# `return_key_value`

```elixir
@spec return_key_value() :: 8
```

Return selected key/value pairs.

# `return_none`

```elixir
@spec return_none() :: 0
```

Return no result for a selector operation.

# `return_ordered_map`

```elixir
@spec return_ordered_map() :: 17
```

Return selected entries as an ordered map.

# `return_rank`

```elixir
@spec return_rank() :: 3
```

Return selected value ranks.

# `return_reverse_index`

```elixir
@spec return_reverse_index() :: 2
```

Return selected reverse indexes, counted from the map end.

# `return_reverse_rank`

```elixir
@spec return_reverse_rank() :: 4
```

Return selected reverse ranks, counted from the highest value.

# `return_unordered_map`

```elixir
@spec return_unordered_map() :: 16
```

Return selected entries as an unordered map.

# `return_value`

```elixir
@spec return_value() :: 7
```

Return selected values.

# `set_policy`

```elixir
@spec set_policy(String.t(), order(), opts()) :: t()
```

Sets the map order attributes.

# `size`

```elixir
@spec size(String.t(), opts()) :: t()
```

Returns the number of entries in the map.

# `write_create_only`

```elixir
@spec write_create_only() :: 1
```

Only create map items that do not already exist.

# `write_default`

```elixir
@spec write_default() :: 0
```

Use default map write behavior.

# `write_no_fail`

```elixir
@spec write_no_fail() :: 4
```

Do not fail the command when a map item is rejected by write flags.

# `write_partial`

```elixir
@spec write_partial() :: 8
```

Commit valid map items even when another item is rejected by write flags.

# `write_update_only`

```elixir
@spec write_update_only() :: 2
```

Only update map items that already exist.

---

*Consult [api-reference.md](api-reference.md) for complete listing*