Search

Searches are performed on the source table, optionally filtered by a base query and selected facet values. Matching facet values are retrieved from the facets table.

Refine.search(config, facets: %{draft: ["true"]}, limit: 10, offset: 10)

See also: Refine.search/2

The response includes the matching data rows, the available facets and facet options (labels, values and counts) for display, plus facet type information.

Refine.search(config, options)
{:ok,
  %{
    rows: [...],
    facets: %{...},
    types: %{...},
    total_count: 999
  }
}

See Return value ↓ for an example of the shape of this data.

Parameters

• config is the configuration map used to create the facets table. Here it is used to read references to the source and facet tables.
• options may include a base query, selected facet values, and fields to return in the results.

query

Provide a base query, for example to list products from a specific category or apply a text search.

With where filter and select fields:

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

Refine.search(config,
  query: query
)

With select fields from joined tables:

query =
  from article in Article,
    left_join: author_article in AuthorArticle,
    on: article.id == author_article.article_id,
    left_join: author in Author,
    on: author.id == author_article.author_id,
    left_join: role in Role,
    on: role.id == author.role_id,
    select: %{
      title: article.title,
      summary: article.summary,
      author: author.full_name,
      role: role.name
    }

Refine.search(config,
  query: query
)

You may provide pagination attributes in the query attributes:

query = from a in Article,
  limit: 10,
  offset: 10

Refine.search(config,
  query: query
)

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

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 and offset

Paginate results with limit and offset.

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

Default values:

• limit: 10
• offset: 0

result_fields

The result_fields option specifies which fields to include in the result set. Use it to limit the returned columns, or to include fields not defined in the source Ecto schema. When provided, result_fields takes precedence over any select expression in query.

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

repo and timeout

• repo - The Ecto Repo module that contains a Postgres adapter. Omit when the repo is configured globally.
• timeout - Postgrex timeout option.

Return value

The returned map is quite similar to an Elasticsearch facets query result ➚:

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