:elasticsearch_rails 💚 Pagy

:elasticsearch_rails

:elasticsearch_rails is a SEARCH paginator for ElasticsearchRails search results.

Pagy searches and paginates

You use the pagy_search method in place of the search method.

Model
extend Pagy::Search

Controller
# Get the collection in one of the following ways
search = Article.pagy_search(params[:q])
search = Article.pagy_search(params[:q]).records
search = Article.pagy_search(params[:q]).results
# Paginate it
@pagy, @response = pagy(:elasticsearch_rails, search, **options)

# IMPORTANT: If the Elasticsearch max_result_window is != 10_000, sync it with pagy
@pagy, @response = pagy(:elasticsearch_rails, search, max_result_window: 1_000, ...)

You search and paginate

Pagy creates its object out of your result.

Controller
# Standard response (already paginated)
@response = Article.search(params[:q], from: 0, size: 10, ...)
# Get the pagy object out of it
@pagy = pagy(:elasticsearch_rails, @response, **options)

# IMPORTANT: If the Elasticsearch max_result_window is != 10_000, sync it with pagy
@pagy = pagy(:elasticsearch_rails, @response, max_result_window: 1_000, ...)

Search paginators use the same positional technique as :offset paginators, with shared options and readers.

max_result_window: 1_000

Set it to the actual max_result_window applied by Elasticsearch, to get an accurate pagination count (default 10_000).

search_method: :my_search

Customize the name of the ElasticsearchRails search method to use in active mode (default :search).

limit: 10

Specifies the number of items per page (default: 20).

client_limit: 200

Allow the client to request a :limit up to :client_limit. A higher requested :limit is silently capped.

IMPORTANT If falsey or zero, the client cannot request any :limit.

page: force_page

Set it only to force the current :page. (It is set automatically from the request param)

request: request || hash

Pagy tries to find the Rack::Request at self.request. Set it only when it's not directly available in your code (e.g., Hanami, standalone app, test,...). For example:

hash_request = { base_url: 'http://www.example.com',
                 path:     '/path',
                 params:   { 'param1' => 1234 }, # The string-keyed params hash from the request
                 cookie:   'xyz' }               # The 'pagy' cookie, only for keynav

jsonapi: true

Enables JSON:API-compliant URLs with nested query string (e.g., ?page[number]=2&page[size]=100).

root_key: 'my_root'

Set it to enable nested URLs with nested query string ?my_root[page]=2&my_root[limit]=100. Use it to handle multiple pagination objects in the same request.

page_key: 'my_page'

Set it to change the key string used for the :page in URLs (default 'page').

limit_key: 'my_limit'

Set it to change the key string used for the :limit in URLs (default 'limit').

offset: The OFFSET used in the SQL query.
count: The collection count.
from: The position in the collection of the first item on the page. (Different Pagy classes may use different value types for it).
to: The position in the collection of the last item on the page. (Different Pagy classes may use different value types for it).
last: The last page.
pages: The number of pages.
previous: The previous page.
next: The next page.
page: The current page.
limit: The items per page.
in: The actual items in the page.
records: The fetched records for the current page.
options: The hash of options of the object.

Last updated on 2026-10-03