Facets table

Copy Markdown

The facets table is created from a configuration map and populated from the source table. It stores one row per distinct option value per facet, containing the option value, display label, and a precomputed bitmap of matching source table identities.

Configuration

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 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.

Options

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.

facets

Required

A list of maps (one per facet). See Facet configuration

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.
  • When create_facets_table/2 is called a second time - so the identity column is already present.

roaringbitmap_type

Either "roaringbitmap" (default) or "roaringbitmap64". See pg_roaringbitmap ➚ for details.

Create the facets table

Create the facets table with either

config = %{...}

Refine.create_facets_table_if_not_exists(config,
  repo: MyApp.Repo,
)

Option repo can be omitted when it is set globally in the application environment:

config = %{...}

Refine.create_facets_table_if_not_exists(config)

The resulting facets table will look something like this:

| facet_name | chunk_id     | option_value | option_label | facet_label | bitmaps       |
| [PK] text  | [PK] integer | [PK] text    | jsonb        | jsonb       | roaringbitmap |
| ---------- | ------------ | ------------ | ------------ | ----------- | ------------- |
| draft      | 0            | false        | "false"      | "draft"     | \x3a300...006 |
| draft      | 0            | true         | "true"       | "draft"     | \x3a300...007 |

Notes

  • Generated values in column option_value are always strings.
  • Generated values in columns option_label and facet_label are JSON and may contain either strings (the default) or maps (when the label contains JSON objects).