Search

Copy Markdown

Searches are performed using Refine.search/2.

Refine.search(config, options)

Search filters can be provided through the options parameter:

  • Base query - for example, to list products from a speficic category or to apply a text search.
  • Selected facet values - additional filters that refine the results of the base query.

Options

Without filters

The config parameter is the configuration map previously used to create the facets table - see: Facets table.

If no filter options are provided, all rows from the source table are returned, limited by the default limit value.

Refine.search(config)

Limit and offset

Paginate results with limit and offset.

Refine.search(config,
  base_query: base_query,
  limit: 10,
  offset: 10
)

Default values:

  • limit: 10
  • offset: 0

Filter by base query

The base_query option is an Ecto query applied to the source table to filter or shape the data. If no base query is provided, the source table is queried without additional filters.

Example with where filter and select fields:

base_query = from a in Article,
  where: ilike(a.title, ^"%memory%"),
  select: %{id: a.id, title: a.title},
  
Refine.search(config,
  base_query: base_query
)

You may also provide pagination in the base query:

base_query = from a in Article,
  limit: 10,
  offset: 10
  
Refine.search(config,
  base_query: base_query
)

For more query options, see: Ecto.Query ➚.

Filter by selected facets

The facets option is a map containing the selected values for each facet.

The map keys are facet names (as defined in the configuration), while the values are the selected option values stored in the facets table. Facet values are always strings.

Refine.search(config,
  facets: %{
    draft: ["true"],
    color: ["blue", "red"]
  }
)

If a facet has multiple selected values (here: blue and red), the filter for that facet is applied using an OR operator. In this case, the logic becomes: draft=true AND (color=blue OR color=red).

Limit returned fields

The result_fields option specifies which source fields to include in the result set. Use it to limit the returned data when not using base_query, or to include columns not defined in the source Ecto schema. These values override any select expression defined in base_query.

Refine.search(config,
  result_fields = [:identity, :title]
)

Return value

The success return value is an ok tuple containing a map that is quite similar to an Elasticsearch facets query result ➚:

{:ok,
  %{
    rows: [
      %{
        "draft" => "true",
        "identity" => 1,
        "title" => "Géographie des marges",
        ...
      },
      ...
    ],
    types: %{
      "draft" => "boolean",
      "identity" => "integer",
      "title" => "text",
      ...
    },
    facets: %{
      "draft" => %{
        "buckets" => [
          %{
            "count" => 6,
            "label" => "false",
            "selected" => false,
            "value" => "false"
          },
          %{
            "count" => 4,
            "label" => "true",
            "selected" => false,
            "value" => "true"
          }
        ],
        "label" => "draft"
      },
      ...
    }
  }
}