# `Selecto.Jsonb`

JSONB column support with dot notation for filtering and selection.

Provides structured JSONB column definitions with schemas that enable:
- Dot notation access: `"attributes.color"` → `attributes->>'color'`
- Type-aware comparisons with automatic casting
- Contains/exists operations for JSONB-specific queries
- Nested object and array support

## Domain Configuration

    columns: %{
      "attributes" => %{
        type: :jsonb,
        schema: %{
          "color" => %{type: :string, required: true},
          "size" => %{type: :string, enum: ["small", "medium", "large"]},
          "weight" => %{type: :decimal},
          "dimensions" => %{
            type: :object,
            schema: %{
              "length" => %{type: :decimal},
              "width" => %{type: :decimal}
            }
          },
          "tags" => %{type: :array, items: %{type: :string}}
        }
      }
    }

## Filtering Examples

    # Equality on JSONB path
    Selecto.filter(selecto, {"attributes.color", "red"})

    # Comparison operators
    Selecto.filter(selecto, {"attributes.weight", {:gt, 10.0}})

    # JSONB contains
    Selecto.filter(selecto, {"attributes", {:jsonb_contains, %{"color" => "red"}}})

    # Array contains
    Selecto.filter(selecto, {"attributes.tags", {:contains, "featured"}})

    # Key exists
    Selecto.filter(selecto, {"attributes.warranty", :exists})

# `build_array_contains`

Build a JSONB array contains check expression.

## Examples

    iex> build_array_contains("attributes", ["tags"], "featured")
    ~s("attributes"->'tags' ? 'featured')

    iex> build_array_contains("attributes", ["tags"], ["featured", "new"])
    ~s("attributes"->'tags' ?| array['featured','new'])

# `build_array_contains_all`

Build a JSONB array contains all check expression.

## Examples

    iex> build_array_contains_all("attributes", ["tags"], ["featured", "new"])
    ~s("attributes"->'tags' ?& array['featured','new'])

# `build_contains`

Build a JSONB containment check expression.

## Examples

    iex> build_contains("attributes", %{"color" => "red"})
    ~s("attributes" @> '{"color":"red"}'::jsonb)

# `build_extraction`

Build a PostgreSQL JSONB extraction expression.

## Options
  - `:as_text` - Use `->>` for text extraction (default: true for leaf values)
  - `:cast` - Cast to specific type after extraction

## Examples

    iex> build_extraction("attributes", ["color"], as_text: true)
    ~s("attributes"->>'color')

    iex> build_extraction("attributes", ["dimensions", "length"], cast: :decimal)
    ~s(("attributes"#>>'{dimensions,length}')::numeric)

# `build_key_exists`

Build a JSONB key exists check expression.

## Examples

    iex> build_key_exists("attributes", "color")
    ~s("attributes" ? 'color')

    iex> build_key_exists("attributes", ["dimensions", "length"])
    ~s("attributes"->'dimensions' ? 'length')

# `get_path_schema`

Get the JSONB schema for a path within a column.

Returns the schema definition for the nested field, or nil if not defined.

# `jsonb_column?`

Check if a column is a JSONB type in the domain.

# `parse_field_reference`

Parse a field reference that may contain JSONB dot notation.

Returns `{:jsonb, column, path}` if it's a JSONB path, or `{:regular, field}` otherwise.

## Examples

    iex> parse_field_reference("attributes.color", domain)
    {:jsonb, "attributes", ["color"]}

    iex> parse_field_reference("attributes.dimensions.length", domain)
    {:jsonb, "attributes", ["dimensions", "length"]}

    iex> parse_field_reference("name", domain)
    {:regular, "name"}

# `pg_cast_for_type`

Determine the PostgreSQL cast type for a JSONB schema type.

---

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