Refine.Flop (Refine v0.3.0)

Copy Markdown

Adapter for using Flop with Refine.

Translates Flop's filter and pagination parameters into Refine search options. Facet value selection (OR sets within a facet) remains part of Refine's own options, while Flop handles field filters and offset pagination.

Summary

Types

create_facets_table_return()
database_option()
database_options()
facet_config()
facet_configs()
facets_table_config()
flop()
flop_meta()
flop_params()
join_config()
join_configs()
order_by_entry()
order_direction()
postgrex_option()
postgrex_options()
repo()
search_option()
search_options()
search_return()
search_return_data()
sort_nulls()

Functions

search(config, flop_params, opts \\ [])

Runs a Refine search using Flop params, resolving the base query and pagination from opts.

to_search_options(flop_params, opts \\ [])

Translates Flop params into Refine search options.

Types

create_facets_table_return()

@type create_facets_table_return() ::
  {:ok, String.t()}
  | {:error, :column_not_found, String.t()}
  | {:error, :column_names_not_unique}
  | {:error, :facets_table_exists, String.t()}
  | {:error, :identity_column_already_exists, String.t()}
  | {:error, :identity_column_invalid_type, String.t()}
  | {:error, :identity_column_not_found, String.t()}
  | {:error, :invalid_table_name, String.t()}
  | {:error, :table_names_not_unique}
  | {:error, Exception.t()}

database_option()

@type database_option() :: {:repo, repo()} | postgrex_option()

database_options()

@type database_options() :: [database_option()]

facet_config()

@type facet_config() :: %{
  facet_label: String.t() | nil,
  facet_name: String.t(),
  join_table: String.t() | nil,
  label_column: String.t() | nil,
  label_path: String.t() | nil,
  value_column: String.t() | nil,
  value_path: String.t() | nil,
  width_bucket: [integer() | float()] | nil
}

facet_configs()

@type facet_configs() :: [facet_config()]

facets_table_config()

@type facets_table_config() ::
  %{
    add_identity_column_if_not_exists: boolean() | nil,
    facets_table: String.t(),
    facets: facet_configs(),
    identity_column: String.t(),
    joins: join_configs() | nil,
    roaringbitmap_type: String.t() | nil,
    source_table: String.t()
  }
  | keyword()

flop()

@type flop() :: struct()

flop_meta()

@type flop_meta() :: struct()

flop_params()

@type flop_params() :: map()

join_config()

@type join_config() :: %{
  table: String.t(),
  match: String.t(),
  to: String.t(),
  on: String.t() | nil
}

join_configs()

@type join_configs() :: [join_config()]

order_by_entry()

@type order_by_entry() ::
  {String.t(), order_direction()}
  | {String.t(), order_direction(), sort_nulls()}

order_direction()

@type order_direction() :: :asc | :desc

postgrex_option()

@type postgrex_option() :: {:timeout, integer() | :infinity} | {:log, boolean()}

postgrex_options()

@type postgrex_options() :: [postgrex_option()]

repo()

@type repo() :: module()

search_option()

@type search_option() ::
  {:facets, map()}
  | {:limit, integer()}
  | {:offset, integer()}
  | {:order_by, [order_by_entry()]}
  | {:query, Ecto.Query.t()}
  | {:repo, repo()}
  | {:result_fields, [String.t()]}
  | postgrex_option()

search_options()

@type search_options() :: [search_option()]

search_return()

@type search_return() :: {:ok, search_return_data()} | {:error, Exception.t()}

search_return_data()

@type search_return_data() :: %{
  facets: map(),
  rows: [map()],
  total_count: integer(),
  types: map(),
  flop_meta: map() | nil
}

sort_nulls()

@type sort_nulls() :: :first | :last | :default

Functions

search(config, flop_params, opts \\ [])

@spec search(facets_table_config(), flop_params(), search_options()) ::
  search_return()

Runs a Refine search using Flop params, resolving the base query and pagination from opts.

Returns Refine's search result map with an added flop_meta key holding a Flop.Meta struct built from the search's total_count.

Raises if the flop dependency is not available; if a schema cannot be resolved from for or the base query; or if the Flop params are invalid.

to_search_options(flop_params, opts \\ [])

@spec to_search_options(flop_params(), search_options()) :: search_options()

Translates Flop params into Refine search options.

Returns opts with :query set to the Flop-filtered query and :limit / :offset resolved. All other options are passed through.

This does not produce a Flop.Meta struct; use search/3 for that.

Options

  • :for - the Ecto schema backing the Flop params. Required if no :query is given, or if the query's source schema can't be determined.
  • :query - a base Ecto query. Defaults to a query built from :for.
  • :limit and :offset - explicit pagination; takes precedence over Flop's. Must be given together or not at all.

Raises if the flop dependency is not available; if a schema cannot be resolved from for or the base query; or if the Flop params are invalid.