Search

Copy Markdown

Searches are performed on the source table, filtered by a base query and/or selected facet values. Facet matches are read from the facets table.

The returned data includes the matching rows, column types, and available facets and facet options for use in the user interface.

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

See Return value for some more details.

Parameters

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

  • The options parameter may include a base query, selected facet values, and fields to return in the results. If no options are provided, all rows from the source table are returned, limited by the default limit value.

    Refine.search(config)

See also: Refine.search/2

Options

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.

Joined tables

result_fields only works with fields from the source table. When selecting fields from joined tables, use Ecto.Query.select/3 on the query instead.

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

repo and timeout

  • repo: The Ecto Repo module that contains a Postgres adapter. This can be omitted when the repo is configured globally - see: Installation.
  • timeout: Postgrex timeout.

Return value

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

{:ok,
  %{
    total_count: 999,
    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"
      },
      ...
    }
  }
}