Facet configuration

This page describes the facets options inside the facets table configuration options.

Minimal example:

config = %{
  ...
  facets: [
    %{
      facet_name: "role"
    }
  ]
}

The facets option lets you configure which source columns are used to read facet values and labels.

For each facet, you can:

Specify the source column from which to read option values.
Specify the source column from which to read option labels.
Extract option values and labels from arrays - see Array values.
Extract option values and labels from JSON objects - see JSON data.
Group entries into distinct categories - see Buckets.

Required

The name identifier of the facet.

Assumes that a column with this name exists in the source table - values will be read from that column. Otherwise, use config option value_column to read data from a different source column (and in that case the facet name may be an arbitrary, descriptive name).

In frontend, the facet label describes the set of facet options. In this example "System Status":

System Status
-------------
[x] Approved
[ ] Draft

The facet label is usually a string, but it can also be extracted from a JSON object - useful when providing translations without having to implement an interface text lookup function.

With a string value

Writes a static text to the facet_label column.

Examples

Source table

| id           | state    | state_label    |
| [PK] integer | text     | text           |
| ------------ | -------- | -------------- |
| 1            | draft    | Draft          |
| 2            | approved | Approved       |

Facet configuration

config = %{
  ...
  facets: [
    %{
      facet_name: "state",
      label_column: "state_label",
      facet_label: "System Status"
    }
  ]
}

Facets table (simplified)

| facet_name | option_value | option_label | facet_label     |
| ---------- | ------------ | ------------ | --------------- |
| status     | draft        | "Draft"      | "System Status" |
| status     | approved     | "Approved"   | "System Status" |

With a JSON value

Wrties a static JSON object to the facet_label column.

Examples

Source table

| id           | state    | state_label    |
| [PK] integer | text     | text           |
| ------------ | -------- | -------------- |
| 1            | draft    | Draft          |
| 2            | approved | Approved       |

Facet configuration

config = %{
  ...
  facets: [
    %{
      facet_name: "state",
      label_column: "state_label",
      facet_label: %{en: "Status", de: "Zustand"}
    }
  ]
}

Facets table (simplified)

| facet_name | option_value | option_label | facet_label                       |
| ---------- | ------------ | ------------ | --------------------------------- |
| status     | draft        | "Draft"      | {"en": "Status", "de": "Zustand"} |
| status     | approved     | "Approved"   | {"en": "Status", "de": "Zustand"} |

value_column

By default, values are read from the source column corresponding to the facet name. Use value_column to specify a different source column.

Examples

Source table

| id           | state    |
| [PK] integer | text     |
| ------------ | -------- |
| 1            | draft    |
| 2            | approved |

Facet configuration

config = %{
  ...
  facets: [
    %{
      facet_name: "status",
      value_column: "state"
    }
  ]
}

Facets table (simplified)

| facet_name | option_value | option_label |
| ---------- | ------------ | ------------ |
| status     | draft        | "draft"      |
| status     | approved     | "approved"   |

label_column

By default, labels are read from the value column. Use label_column to specify a different source column.

Examples

Source table

| id           | state    | state_label    |
| [PK] integer | text     | text           |
| ------------ | -------- | -------------- |
| 1            | draft    | Draft          |
| 2            | approved | Approved       |

Facet configuration

config = %{
  ...
  facets: [
    %{
      facet_name: "state",
      label_column: "state_label"
    }
  ]
}

Facets table (simplified)

| facet_name | option_value | option_label |
| ---------- | ------------ | ------------ |
| status     | draft        | "Draft"      |
| status     | approved     | "Approved"   |

value_path

Extracts the value from a JSON object.

The path is a comma-separated string of keys and/or indexes. For example:

"value"
"path,to,value"
"path,to,value,1"

The last example corresponds to an array value in a nested object:

{
  "path": {
    "to": {
      "value": ["dummy", ["memory", "oral-history", "interdisciplinary"]]
    }
  }
}

For applications of value_path, see: JSON data

Examples

Source table

| id           | word_count     |
| [PK] integer | jsonb          |
| ------------ | -------------- |
| 1            | {"value": 999} |

Facet configuration

config = %{
  ...
  facets: [
    %{
      facet_name: "word_count",
      value_path: "value"
    }
  ]
}

Facets table (simplified)

| facet_name | option_value | option_label |
| ---------- | ------------ | ------------ |
| word_count | 999          | "999"        |

label_path

Extracts the label from a JSON object.

Without option label_path, the label is created from the value at value_path.

See also value_path
For applications of label_path, see: JSON data

Examples

Source table

| id           | role                                   |
| [PK] integer | jsonb                                  |
| ------------ | -------------------------------------- |
| 1            | {"value": "editor", "label": "Editor"} |

Facet configuration

config = %{
  ...
  facets: [
    %{
      facet_name: "role",
      value_path: "value",
      label_path: "label"
    }
  ]
}

Facets table (simplified)

| facet_name | option_value | option_label |
| ---------- | ------------ | ------------ |
| role       | editor       | "Editor"     |

buckets

Buckets divide numeric and date entries into discrete categories. For example: movies released between 2010 and 2020, or prices ranging from EUR 20 to 50.

Use config option buckets with an array of numeric, date or timestamp values to define the bucket boundaries for the option values. Facet option values are grouped into intervals defined by these boundaries, and labels are generated for each bucket. The generated bucket label will overwrite any other label options.

Sorted bucket values

Bucket values are automatically sorted by Refine, so input values do not need to be ordered.

Numbers

Facet configuration setting:

buckets: [0, 1000, 2000]

Generates the following bucket numbers and labels (if resources match all bins):

| Bucket number | Label         |
| ------------- | ------------- |
| 0             | "< 0"         |
| 1             | "0 - 1000"    |
| 2             | "1000 - 2000" |
| 3             | "> 2000"      |

Dates

Facet configuration setting:

buckets: [~D[1950-01-01], ~D[1960-01-01], ~D[1970-01-01]]

Generates the following bucket numbers and labels (if resources match all bins):

| Bucket number | Label                     |
| ------------- | ------------------------- |
| 0             | "< 1950-01-01"            |
| 1             | "1950-01-01 - 1960-01-01" |
| 2             | "1960-01-01 - 1970-01-01" |
| 3             | "> 1970-01-01"            |

Timestamps and intervals

Facet configuration setting:

buckets: [
  "now()",
  "now() - INTERVAL '1 day'",
  "now() - INTERVAL '1 week'",
  "now() - INTERVAL '1 month'",
  "now() - INTERVAL '1 year'"
]

Generates the following bucket numbers and labels (if resources match all bins):

| Bucket number | Label                                       |
| ------------- | ------------------------------------------- |
| 1             | "2025-01-01 00:00:00 - 2025-12-01 00:00:00" |
| 1             | "2025-12-01 00:00:00 - 2025-12-25 00:00:00" |
| 2             | "> 2026-01-01 00:00:00"                     |

The date-times will, of course, be different in reality.

Instead of using now(), you may also use:

current_date
Specific dates (as date strings). Dates need to be wrapped in single quotes and contain a ::date type suffix.

Example with PostgreSQL variable current_date:

buckets: [
  "current_date",
  "current_date - INTERVAL '1 day'",
  "current_date - INTERVAL '1 week'",
  "current_date - INTERVAL '1 month'",
  "current_date - INTERVAL '1 year'"
]

Example with specific dates:

day = ~D[2026-01-01] |> to_string()
pg_date = "'#{day}'::date"

buckets: [
  "#{pg_date}",
  "#{pg_date} - INTERVAL '1 day'",
  "#{pg_date} - INTERVAL '1 week'",
  "#{pg_date} - INTERVAL '1 month'",
  "#{pg_date} - INTERVAL '1 year'"
]

Examples

With option value_column

Fetches the numeric value to be bucketed from the source table column.

Source table

| id           | word_count |
| [PK] integer | integer    |
| ------------ | ---------- |
| 1            | 1400       |
| 2            | 200        |
| 3            | 9000       |

Facet configuration

config = %{
  ...
  facets: [
    %{
      facet_name: "word_count",
      buckets: [0, 1000, 2000, 3000],
    }
  ]
}

Facets table (simplified)

| facet_name | option_value | option_label  |
| ---------- | ------------ | ------------- |
| word_count | 1            | "0 - 1000"    |
| word_count | 2            | "1000 - 2000" |
| word_count | 4            | "> 3000"      |

With option value_path

Fetches the numeric value to be bucketed from the specified key in the source table JSON column.

Source table

| id           | word_count      |
| [PK] integer | jsonb           |
| ------------ | --------------- |
| 1            | {"value": 1400} |
| 2            | {"value": 200}  |
| 3            | {"value": 9000} |

Facet configuration

config = %{
  ...
  facets: [
    %{
      facet_name: "word_count",
      value_path: "value",
      buckets: [0, 1000, 2000, 3000],
    }
  ]
}

Facets table (simplified)

| facet_name | option_value | option_label  |
| ---------- | ------------ | ------------- |
| word_count | 1            | "0 - 1000"    |
| word_count | 2            | "1000 - 2000" |
| word_count | 4            | "> 3000"      |

Array values

If the value column is an array, its elements are expanded into separate rows.

The following data source formats are supported:

Value column contains arrays
Both value and label columns contain arrays
Value column contains arrays and label column contains JSON

Value column contains arrays

Examples

Source table

| id           | tags             |
| [PK] integer | text[]           |
| ------------ | ---------------- |
| 1            | {history,memory} |

Facet configuration

config = %{
  ...
  facets: [
    %{
      facet_name: "tags"
    }
  ]
}

Facets table (simplified)

| facet_name | option_value | option_label |
| ---------- | ------------ | ------------ |
| tags       | history      | "history"    |
| tags       | memory       | "memory"     |

Both value and label columns contain arrays

If both the value and label columns are arrays, they are treated as parallel arrays and expanded positionally using ordinality.

Examples

Source table

| [PK] integer | text[]           | text[]           |
| id           | tags             | tag_labels       |
| ------------ | ---------------- | ---------------- |
| 1            | {history,memory} | {History,Memory} |

Facet configuration

config = %{
  ...
  facets: [
    %{
      facet_name: "tags",
      label_column: "tag_labels"
    }
  ]
}

Facets table (simplified)

| facet_name | option_value | option_label |
| ---------- | ------------ | ------------ |
| tags       | history      | "History"    |
| tags       | memory       | "Memory"     |

Value column contains arrays and label column contains JSON

The label column may contain JSON data, for example a lookup map for translations.

Examples

Source table

| id           | tags            | tag_translations                                   |
| [PK] integer | text[]          | jsonb                                              |
| ------------ | --------------- | -------------------------------------------------- |
| 1            | {books,history} | {                                                  |
|              |                 |   "books": {"de": "Bücher", "en": "Books"},        |
|              |                 |   "history": {"de": "Geschichte", "en": "History"} |
|              |                 | }                                                  |

Facet configuration

config = %{
  ...
  facets: [
    %{
      facet_name: "tags",
      label_column: "tag_translations"
    }
  ]
}

Facets table (simplified)

| facet_name | option_value | option_label                          |
| ---------- | ------------ | ------------------------------------- |
| tags       | books        | {"de": "Bücher", "en": "Books"}       |
| tags       | history      | {"de": "Geschichte", "en": "History"} |

JSON data

Source data stored in JSON format can be extracted and used as facet option values and labels in several different ways. Depending on the structure of the JSON data, facet option values and labels can be derived directly, paired explicitly, or mapped from arrays and key-value objects.

The following data source formats are supported:

Value entry
Value and label entry
Value array
Parallel value and label arrays
Label as key-value map

Value entry

Use the option value_path to extract the value from the JSON object.

Value and label entry

When both option value and label are present in the JSON data, use config option label_path to extract the label from the JSON.

Value array

If value is a JSON array, its elements are expanded into separate rows.

Examples

Source table

| id           | tags                             |
| [PK] integer | jsonb                            |
| ------------ | -------------------------------- |
| 1            | {"value": ["history", "memory"]} |

Facet configuration

Use facet option value_path to fetch the value from from the JSON column.

config = %{
  ...
  facets: [
    %{
      facet_name: "tags",
      value_path: "value"
    }
  ]
}

Facets table (simplified)

| facet_name | option_value | option_label |
| ---------- | ------------ | ------------ |
| tags       | history      | "history"    |
| tags       | memory       | "memory"     |

Parallel value and label arrays

If both value and label are JSON arrays, they are treated as parallel arrays. Each value is paired with the label at the same position.

Examples

Source table

| id           | tags                              |
| [PK] integer | jsonb                             |
| ------------ | --------------------------------- |
| 1            | {                                 |
|              |   "value": ["history", "memory"], |
|              |   "label": ["History", "Memory"]  |
|              | }                                 |

Facet configuration

Use facet options value_path and label_path to extract the values and labels from both JSON arrays:

config = %{
  ...
  facets: [
    %{
      facet_name: "tags",
      value_path: "value",
      label_path: "label"
    }
  ]
}

Facets table (simplified)

| facet_name | option_value | option_label |
| ---------- | ------------ | ------------ |
| tags       | history      | "History"    |
| tags       | memory       | "Memory"     |

Label as key-value map

If value is a JSON array and label is a JSON map, each value is used as a key to look up its corresponding label.

Examples

Source table

| id           | languages                                    |
| [PK] integer | jsonb                                        |
| ------------ | -------------------------------------------- |
| 1            | {"value": ["de", "en", "fr"],                |
|              |  "label": {"de": "German", "en": "English",  |
|              |            "fr": "French"}}                  |

Facet configuration

Use config options value_path and label_path to extract the values from the JSON array and the labels from the JSON object:

config = %{
  ...
  facets: [
    %{
      facet_name: "languages",
      value_path: "value",
      label_path: "label"
    }
  ]
}

Facets table (simplified)

| facet_name | option_value | option_label |
| ---------- | ------------ | ------------ |
| languages  | de           | "German"     |
| languages  | en           | "English"    |
| languages  | fr           | "French"     |

← Previous Page Facets table

Next Page → Search