# `Aerospike.Filter`
[🔗](https://github.com/luisgabrielroldan/aerospike_driver/blob/v0.3.1/lib/aerospike/filter.ex#L1)

Secondary-index predicate values for query builders.

Use `range/3`, `equal/2`, `contains/3`, `geo_within/2`, or
`geo_contains/2` to build a predicate, then pass it to
`Aerospike.Query.where/2`.

`using_index/2` targets a named index, and `with_ctx/2` carries nested
CDT context for context-aware predicates.

# `collection_index_type`

```elixir
@type collection_index_type() :: :list | :mapkeys | :mapvalues
```

Collection secondary-index kind accepted by `contains/3`.

# `geo_geometry`

```elixir
@type geo_geometry() ::
  String.t()
  | Aerospike.Geo.Point.t()
  | Aerospike.Geo.Polygon.t()
  | Aerospike.Geo.Circle.t()
```

GeoJSON input accepted by geospatial query filters.

Binary inputs are expected to be non-empty GeoJSON strings. Typed
`Aerospike.Geo` values are converted with `Aerospike.Geo.to_json/1`.

# `index_type`

```elixir
@type index_type() ::
  :default | :list | :mapkeys | :mapvalues | :geo_within | :geo_contains
```

Secondary-index filter kind encoded for the query predicate.

`:list`, `:mapkeys`, and `:mapvalues` target CDT collection indexes.
`:geo_within` and `:geo_contains` target geospatial predicates.

# `particle_type`

```elixir
@type particle_type() :: :integer | :string
```

Indexed scalar particle type inferred for integer and string predicates.

# `scalar_value`

```elixir
@type scalar_value() :: integer() | String.t()
```

Scalar value accepted by equality and CDT membership filters.

# `t`

```elixir
@type t() :: %Aerospike.Filter{
  begin: term(),
  bin_name: String.t(),
  ctx: [Aerospike.Ctx.step()] | nil,
  end: term(),
  index_name: String.t() | nil,
  index_type: index_type(),
  particle_type: particle_type()
}
```

Secondary-index query filter consumed by `Aerospike.Query.where/2`.

A query can carry one secondary-index filter. `index_name` is optional and is
set by `using_index/2`; `ctx` is optional nested-CDT context set by
`with_ctx/2`.

# `contains`

```elixir
@spec contains(String.t(), collection_index_type(), scalar_value()) :: t()
```

CDT membership filter for list or map indexes.

`index_type` must match the collection index created for the bin:
`:list`, `:mapkeys`, or `:mapvalues`.

# `equal`

```elixir
@spec equal(String.t(), scalar_value()) :: t()
```

Equality on a bin. The particle type is inferred from the value.

Supports integer and string values. Integer values must fit in Aerospike's
signed int64 range.

# `geo_contains`

```elixir
@spec geo_contains(String.t(), geo_geometry()) :: t()
```

Geo point query for regions containing a GeoJSON point.

Use this with a `:geo2dsphere` index on region data. The point may be a
GeoJSON string or a typed `Aerospike.Geo` value.

# `geo_contains_point`

```elixir
@spec geo_contains_point(String.t(), number(), number()) :: t()
```

Builds a `geo_contains/2` point query from longitude and latitude.

# `geo_within`

```elixir
@spec geo_within(String.t(), geo_geometry()) :: t()
```

Geo region query for points within a GeoJSON region.

Use this with a `:geo2dsphere` index on point data. The region may be a
GeoJSON string or a typed `Aerospike.Geo` value.

# `geo_within_radius`

```elixir
@spec geo_within_radius(String.t(), number(), number(), number()) :: t()
```

Builds a `geo_within/2` circle query from center longitude, latitude, and radius.

# `range`

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

Numeric range on a bin, inclusive.

`begin_val` and `end_val` must fit in Aerospike's signed int64 range.
Raises `ArgumentError` when the bin name is empty, a value is out of range,
or the range is inverted.

# `using_index`

```elixir
@spec using_index(t(), String.t()) :: t()
```

Targets a named secondary index.

Use this when the server has multiple compatible indexes and the query
should address one index explicitly.

# `with_ctx`

```elixir
@spec with_ctx(t(), [Aerospike.Ctx.step()]) :: t()
```

Attaches nested CDT context to the filter.

`ctx` must be a non-empty list of `Aerospike.Ctx` steps that points at the
nested collection value indexed by the server.

---

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