# Facets table configuration

The configuration map is the central instruction set for creating and searching facets. It is used to create the facets table and populate it from the source table.
It also functions as a unique identifier for other functions such as search and merge.

Example configuration:

```elixir
config = %{
  facets_table: "articles_facets",
  source_table: "articles",
  add_identity_column_if_not_exists: true,
  identity_column: "identity",
  facets: [
    %{facet_name: "draft"}
  ]
}
```

This configuration will:

- Create the facets table `articles_facets`.
- Add an integer identity column named `identity` to `articles`, if no valid integer ID column already exists (controlled by `add_identity_column_if_not_exists`).
- Populate facets table `articles_facets` with one row per distinct value in the `draft` column of `articles`, storing the value, its label, and a precomputed bitmap of matching article identities.

## facets_table

_Required_

The name of the facets table, with an optional database schema prefix.

**Examples**

- "articles_facets"
- "catalog.articles_facets"

## source_table

_Required_

The name of the source table, with an optional database schema prefix.

**Examples**

- "articles"
- "catalog.articles"

## identity_column

_Required_

The name of the column in the source table that uniquely identifies each row. It is used to reference source rows in the bitmap data.

This column must be of an integer type - a regular integer or a Postgres identity column.
Uniqueness must be enforced by a `PRIMARY KEY` or `UNIQUE` constraint.

If the source table does not yet have such a column, one can be added by passing
config option [add_identity_column_if_not_exists](#add_identity_column_if_not_exists).

## facets

_Required_

A list of facet configuration entries that describe which source columns are used to read facet values and labels.

See [Facets configuration](facets_configuration.md)

## joins

A list of join table configuration entries.

See [Joins configuration](joins_configuration.md)

## add_identity_column_if_not_exists

Adds an auto-increment identity column to the source table, using the column name provided via config option `identity_column`.

This step is skipped if a valid identity column already exists, either:

- An identity column is already present in the source table - see [option identity_column](#identity_column).
- When `create_facets_table/2` is called a second time - so the identity column is already present.

## roaringbitmap_type

Either:

- "roaringbitmap" (default)
- "roaringbitmap64"

See [pg_roaringbitmap ➚](https://github.com/ChenHuajun/pg_roaringbitmap) for details.