@type create_facets_table_return() ::
  {:ok, String.t()}
  | {:error, :column_not_found, 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_distinct}
  | {:error, :facets_table_exists, String.t()}
  | {:error, Exception.t()}

@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
}

@type facet_configs() :: [facet_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_spec()] | nil,
    roaringbitmap_type: String.t() | nil,
    source_table: String.t()
  }
  | keyword()

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

@type join_triggers() :: %{
  required(String.t()) => %{
    trigger: String.t(),
    trigger_fn: String.t(),
    delete_trigger: String.t()
  }
}

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

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

@type postgrex_options() :: [timeout: integer() | :infinity, log: boolean()]

@type repo() :: module()

@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_options()

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

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

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

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