# Operate, CDT, And Geo

`Aerospike.operate/4` executes a list of server-side operations against one
record. Use it for atomic primitive updates, complex data type operations,
expression operations, bit operations, HyperLogLog operations, and readbacks.

## Primitive Operations

Primitive operation builders live in `Aerospike.Op`.

```elixir
key = Aerospike.key("test", "sessions", "session:1")

{:ok, _metadata} =
  Aerospike.put(:aerospike, key, %{
    "visits" => 1,
    "status" => "new"
  })

{:ok, record} =
  Aerospike.operate(:aerospike, key, [
    Aerospike.Op.add("visits", 1),
    Aerospike.Op.put("status", "active"),
    Aerospike.Op.get("visits")
  ])

record.bins["visits"]
```

## List Operations

List operations live in `Aerospike.Op.List`. Selector operations can choose
return shapes with return-type helpers.

```elixir
key = Aerospike.key("test", "sessions", "session:events")

{:ok, _metadata} =
  Aerospike.put(:aerospike, key, %{"events" => ["created"]})

{:ok, record} =
  Aerospike.operate(:aerospike, key, [
    Aerospike.Op.List.append("events", "opened"),
    Aerospike.Op.List.size("events")
  ])

record.bins["events"]
```

Selector helpers can address list entries by index, rank, or value. Index is
position in the list. Rank is position in value order, so `-1` means the
highest-ranked value. `return_type:` controls whether the server returns
values, indexes, ranks, counts, or an existence flag.

```elixir
{:ok, record} =
  Aerospike.operate(:aerospike, key, [
    Aerospike.Op.List.get_by_index("events", 0,
      return_type: :value
    ),
    Aerospike.Op.List.get_by_rank("events", -1,
      return_type: :value
    ),
    Aerospike.Op.List.get_by_value("events", "opened",
      return_type: :exists
    )
  ])
```

List write policies use mnemonic order and flag values. Defaults are the
safest choice; set policy values only when your application needs ordered-list
or write-flag behavior. Advanced compatibility callers can still pass integer
values, including `{:raw, integer}` for unnamed server values.

```elixir
Aerospike.Op.List.append("events", "clicked", policy: [order: :ordered, flags: :add_unique])
```

## Map Operations

Map operations live in `Aerospike.Op.Map`.

```elixir
key = Aerospike.key("test", "profiles", "user:stats")

{:ok, _metadata} =
  Aerospike.put(:aerospike, key, %{"stats" => %{"views" => 1}})

{:ok, record} =
  Aerospike.operate(:aerospike, key, [
    Aerospike.Op.Map.increment("stats", "views", 1),
    Aerospike.Op.Map.put("stats", "updated_by", "worker-1"),
    Aerospike.Op.Map.get_by_key("stats", "views",
      return_type: :value
    )
  ])

record.bins["stats"]
```

Map selectors can return keys, values, key/value pairs, indexes, ranks, counts,
or existence flags. Key selectors default to keys, value/rank selectors default
to values or key/value pairs depending on the operation; pass `return_type:`
when the desired shape matters.

```elixir
{:ok, record} =
  Aerospike.operate(:aerospike, key, [
    Aerospike.Op.Map.get_by_key("stats", "views",
      return_type: :value
    ),
    Aerospike.Op.Map.get_by_rank("stats", -1,
      return_type: :key_value
    ),
    Aerospike.Op.Map.get_by_value("stats", 1,
      return_type: :key
    )
  ])

record.bins["stats"]
```

Map write policies use mnemonic order and flag values. `:order` controls map
ordering and `:flags` applies write flags when the operation supports them.
Advanced compatibility callers can still pass integer values, including
`{:raw, integer}` for unnamed server values.

```elixir
Aerospike.Op.Map.put_items("stats", %{"likes" => 2},
  policy: [order: :key_ordered, flags: :update_only]
)
```

## Nested CDT Paths

Nested CDT operations use `Aerospike.Ctx` path steps through the `:ctx` option.

```elixir
key = Aerospike.key("test", "profiles", "user:nested")

{:ok, _metadata} =
  Aerospike.put(:aerospike, key, %{
    "profile" => %{"events" => []}
  })

{:ok, _record} =
  Aerospike.operate(:aerospike, key, [
    Aerospike.Op.List.append("profile", "signed-in",
      ctx: [Aerospike.Ctx.map_key("events")]
    )
  ])
```

Context paths can move through maps and lists by key, value, index, or rank.
The operation bin is the top-level CDT bin; each context step navigates inside
that value before the operation runs.

```elixir
key = Aerospike.key("test", "profiles", "user:nested-scores")

{:ok, _metadata} =
  Aerospike.put(:aerospike, key, %{
    "profile" => %{
      "teams" => [
        %{"name" => "red", "scores" => [10, 20]},
        %{"name" => "blue", "scores" => [15]}
      ]
    }
  })

{:ok, record} =
  Aerospike.operate(:aerospike, key, [
    Aerospike.Op.List.append("profile", 25,
      ctx: [
        Aerospike.Ctx.map_key("teams"),
        Aerospike.Ctx.list_index(0),
        Aerospike.Ctx.map_key("scores")
      ]
    ),
    Aerospike.Op.List.get_by_rank("profile", -1,
      ctx: [
        Aerospike.Ctx.map_key("teams"),
        Aerospike.Ctx.list_index(0),
        Aerospike.Ctx.map_key("scores")
      ],
      return_type: :value
    )
  ])

record.bins["profile"]
```

See `Aerospike.Op.List`, `Aerospike.Op.Map`, and `Aerospike.Ctx` for the full
operation reference.

## Bit Operations

Bit operations require Aerospike blob bins. Plain Elixir binaries are encoded
as strings by this client, so seed bit bins with `{:blob, binary}`.

```elixir
key = Aerospike.key("test", "profiles", "user:flags")

{:ok, _metadata} =
  Aerospike.put(:aerospike, key, %{"flags" => {:blob, <<0>>}})

{:ok, record} =
  Aerospike.operate(:aerospike, key, [
    Aerospike.Op.Bit.set("flags", 0, 8, <<0b1010_0000>>),
    Aerospike.Op.Bit.count("flags", 0, 8)
  ])

record.bins["flags"]
```

## HyperLogLog Operations

HyperLogLog operations live in `Aerospike.Op.HLL` and require server support
for HLL bins.

```elixir
key = Aerospike.key("test", "profiles", "visitors")

{:ok, _metadata} = Aerospike.put(:aerospike, key, %{"seed" => 0})

{:ok, record} =
  Aerospike.operate(:aerospike, key, [
    Aerospike.Op.HLL.init("visitors", 14, 0),
    Aerospike.Op.HLL.add("visitors", ["ada", "grace"], 14, 0),
    Aerospike.Op.HLL.get_count("visitors")
  ])

record.bins["visitors"]
```

## Expression Operations

Expression operate helpers live in `Aerospike.Op.Exp` and return or write
server-side expression values.

```elixir
{:ok, record} =
  Aerospike.operate(:aerospike, key, [
    Aerospike.Op.Exp.read("projected", Aerospike.Exp.int_bin("score")),
    Aerospike.Op.Exp.write("score_copy", Aerospike.Exp.int_bin("score"))
  ])

record.bins["projected"]
```

## Geo Values And Queries

Use `Aerospike.Geo` typed values for GeoJSON bins. Geo secondary-index queries
use `Aerospike.Filter.geo_within/2` or `Aerospike.Filter.geo_contains/2`.

```elixir
key = Aerospike.key("test", "places", "pdx")
point = Aerospike.Geo.point(-122.6765, 45.5231)

{:ok, _metadata} = Aerospike.put(:aerospike, key, %{"loc" => point})

{:ok, task} =
  Aerospike.create_index(:aerospike, "test", "places",
    bin: "loc",
    name: "places_loc_geo_idx",
    type: :geo2dsphere
  )

:ok = Aerospike.IndexTask.wait(task)

region = Aerospike.Geo.circle(-122.6765, 45.5231, 10_000.0)

query =
  Aerospike.Query.new("test", "places")
  |> Aerospike.Query.where(Aerospike.Filter.geo_within("loc", region))
  |> Aerospike.Query.max_records(100)

{:ok, records} = Aerospike.query_all(:aerospike, query)
```

Geo filters require matching secondary indexes. `query_all/3` and
`query_page/3` require `query.max_records`.