# `Arcana.Collection`
[🔗](https://github.com/georgeguimaraes/arcana/blob/main/lib/arcana/collection.ex#L1)

Represents a collection of documents for segmentation.

Collections allow you to organize documents by product, country,
or any other grouping criteria. Documents can be filtered by
collection when searching.

# `fetch`

Fetches a collection by name.

Returns `{:ok, collection}` or `{:error, {:unknown_collection, name}}`.

# `get_or_create`

Gets an existing collection by name or creates a new one.

If a description is provided and the collection already exists,
the description is updated only if the existing one is nil or empty.

## Examples

    {:ok, collection} = Collection.get_or_create("products", MyRepo)
    {:ok, collection} = Collection.get_or_create("default", MyRepo)
    {:ok, collection} = Collection.get_or_create("docs", MyRepo, "Official documentation")

# `resolve_id`

Resolves a single collection name to its ID.

Returns `{:ok, nil}` when `name` is `nil` (unscoped) or, in non-strict
mode, when the collection doesn't exist. With `strict?` set, an unknown
name returns `{:error, {:unknown_collection, name}}`.

# `resolve_ids`

Resolves a list of collection names to their IDs.

Returns `{:ok, nil}` for unscoped queries (when collections is `[nil]`),
otherwise `{:ok, ids}`. Unknown names are dropped, so the list can be
empty — callers must treat an empty list as "match nothing", never as
"no filter". With `strict: true`, the first unknown name returns
`{:error, {:unknown_collection, name}}` instead.

---

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