# `ExDisco.Search`
[🔗](https://github.com/bo1ta/ex_disco/blob/main/lib/ex_disco/search.ex#L1)

Global search across the entire Discogs database.

The search API allows you to search for artists, releases, masters, and labels
using various filters. Results are returned in a paginated `ExDisco.Page`
containing raw maps that you can map to typed structs if needed.

## Search Types

- `:artist` — Search for artists
- `:release` — Search for releases (specific versions)
- `:master` — Search for masters (abstract works)
- `:label` — Search for record labels

## Common Filters

- `:q` — General text search
- `:title` — Search by title/name
- `:artist` — Search by artist name
- `:label` — Search by record label
- `:year` — Filter by release year
- `:genre` — Filter by genre
- `:format` — Filter by format (Vinyl, CD, etc.)
- `:per_page` — Results per page (default: 50)
- `:page` — Page number

## Examples

Search for an artist:

    {:ok, page} = ExDisco.Search.query([type: :artist, q: "Rhadoo"])
    Enum.each(page.items, &IO.inspect(&1["title"]))

Search releases with filters:

    {:ok, results} = ExDisco.Search.query([
      type: :release,
      title: "Thriller",
      artist: "Michael Jackson",
      year: 1982
    ])

# `filter_key`

```elixir
@type filter_key() ::
  :q
  | :title
  | :artist
  | :label
  | :album
  | :catno
  | :type
  | :barcode
  | :format
  | :year
  | :genre
  | :style
  | :track
  | :contributor
  | :sort
  | :sort_order
  | :page
  | :per_page
```

# `filters`

```elixir
@type filters() :: [{filter_key(), String.t() | integer()}]
```

# `query_type`

```elixir
@type query_type() :: :release | :master | :artist | :label
```

# `query`

```elixir
@spec query(filters()) :: {:ok, ExDisco.Page.t(map())} | {:error, ExDisco.Error.t()}
```

Search the Discogs database with filters.

Searches across the database using various filter parameters. Returns a
paginated `ExDisco.Page` of raw result maps (not typed structs). You can map
each result to a struct if needed.

The `:type` filter is usually required to specify what you're searching for.

## Examples

    iex> ExDisco.Search.query([type: :artist, q: "Rhadoo"])
    {:ok, %ExDisco.Page{items: [%{"id" => 123, "title" => "Rhadoo", ...}], page: 1}}

    iex> ExDisco.Search.query([type: :release, title: "Thriller", year: 1982])
    {:ok, %ExDisco.Page{items: [%{"id" => 456, "title" => "Thriller", ...}]}}

    iex> ExDisco.Search.query([type: :label, q: "Defected"])
    {:ok, %ExDisco.Page{items: [%{"id" => 789, "title" => "Defected", ...}]}}

---

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