Blockscout
SupportWebsiteGithubDiscord
  • Blockscout Open-Source Explorer
  • 💡About BlockScout
    • Features
      • Ethereum Bytecode Database Microservice
      • Blockscout Redesign
    • Chains Using Blockscout
    • Partners & Integrations
      • RaaS Providers
      • Vera: Verifier Alliance
        • Adding your chain to the Vera database
        • Programmatic verification via the API
    • News & Media
      • Newsletter & Blog
    • Funding
      • L2 Funding Proposal
        • Aux Funding Images
    • Roadmap
  • 🙎Using Blockscout
    • Getting Started
      • Glossary of Terms
      • Main Menu
      • Blocks
      • Transaction Types
      • Beacon Chain Withdrawal Views
    • My Account
      • Watch list
      • Private tags
      • Public tags
      • API keys
      • Custom ABI
      • Verified addresses
        • Copy and Sign Message
      • For developers
    • Dappscout Apps Marketplace
      • DApp Integration
    • Swapscout
      • Earn Merits when using Swapscout
    • Revokescout
    • Autoscout Explorer Launchpad
    • CSV Exports
    • Token Support
      • ERC-1155 Support
    • Merits
      • Streak rewards
      • Activity Pass
      • Leaderboard
      • Badges
      • FAQs
  • 👩‍💻Developer Support
    • For Web3 Developers
    • Link to Blockscout
    • Blockscout APIs
      • Requests & Limits
      • REST API Endpoints
        • Stats API
        • Interpreter API
      • JSON RPC & ETH Compatible RPC Endpoints
        • Account
        • Block
        • Contract
        • Logs
        • Stats
        • Token
        • Transaction
        • ETH RPC API
      • GraphQL in Blockscout
    • Smart Contract Verification
      • Blockscout UI
      • Blockscout smart-contract verification API
      • Hardhat Verification Plugin
        • Sourcify Plugin for Hardhat
      • Foundry Verification
      • Sourcify Verification
      • OpenZeppelin Contract Verification
      • Automate verifications with Catapulta
      • Verification via thirdweb
      • Interacting with Smart Contracts
    • Blockscout SDK
    • Integrate Merits
    • Chainscout chains list
  • 🏃‍♂️Setup and Run Blockscout
    • General Overview
      • Separate Indexer, Web App, and API
      • Umbrella Project Organization
      • Indexer Architecture Overview
      • ShareLock
      • EVM Version Information
    • Requirements
      • General Backend Requirements / Blockscout Backend Prerequisites
      • Backend/Frontend Compatibility Matrix
      • Hardware & Hosting Requirements
      • Database Storage Requirements
      • Client Setting Requirements
      • Node Tracing / JSON RPC Requirements
      • L2 -> L1 JSON-RPC Method Requests
    • ☑️ENV Variables
      • Backend ENVs: Common
      • Backend ENVs: Chain-Specific
      • Backend ENVs: Integrations
      • Frontend ENVs: Common
        • ENVs
        • Deprecated ENVs
      • Deprecated Backend ENVs
        • Previous ENV Variable Home Page
    • Deployment
      • ⭐Manual Deployment Guide
        • Ubuntu Setup
        • MacOS setup
      • ⭐Docker-compose Deployment
      • ⭐Kubernetes Deployment
      • Rollup Deployment
      • 🌟Cosmos-based chains
      • 🍀Upgrade Guide (v7.0 & v8.0)
      • Frontend Migration
        • All-In-One Container
        • Separate Frontend
        • Customized Backend
        • Proxy Setup
        • FAQs
      • Manual Deployment (backend + old UI)
        • Manual cleaning an instance from the previous deployment
      • Terraform Deployment
      • Ansible Deployment (AWS Cloud)
        • Overview
        • Prerequisites
        • AWS Permissions & Settings
          • Creating a Secret Key Pair
          • Login with AWS CLI
          • Creating an AWS certificate for SSL
          • Manually Cleaning Terraform Related Instances
        • Variables
        • Deploying the Blockscout Infrastructure
        • Deploying Blockscout
        • Destroying Provisioned Infrastructure
        • Common Additional Tasks
        • Common Errors and Questions
        • AWS Marketplace (deprecated)
          • Overview
          • CloudFormation Template
          • Prerequisites & Install Parameters
          • Install from AWS Marketplace
          • AWS EC2 archive node setup with OpenEthereum (formerly Parity)
          • Updating & Redeploying in AWS
          • Customizing CSS
    • Microservices
      • Blockscout ENS (BENS) Name Service Integration
      • Smart Contract Verification
    • Configuration Options
      • Admin Panel Usage
      • Automating Restarts
      • Branding Configs
      • Circle CI Updates
      • Charts and Stats
      • CSS Configuration & Presets
      • Exchange Rates
      • Front-end Config Files
      • haproxy Settings for Blockscout.com
      • Internationalization
      • Logger Configs
      • Memory Usage
      • Metrics
      • My Account Settings
      • Sorting and Pagination
      • Tracing
      • Reown Project ID for contract Read/Write
    • Indexing
      • How do I fix indexer timeouts?
      • How do I update memory consumption to fix indexer memory errors?
    • Testing
    • DB schema
  • FAQs
    • User FAQs
    • Developer FAQs
  • 🧩Resources
    • EaaS: Hosting with Blockscout
    • Contributing to Blockscout
    • Bug Bounty Program
    • Media kit
    • Release Notes
      • v5.3.0: 10/23/23
      • v5.2.0: 6/20/23
      • v5.1.0: 2/13/23
      • v5.0.0: 1/11/23
    • Discord Channel
    • Discussion
    • GitHub Repo
Powered by GitBook
LogoLogo

Privacy and Terms

  • Privacy Notice
  • Terms and Conditions

Copyright © Blockscout Limited 2023-2024

On this page
  • Ordering
  • Sorting Parameters
  • Pagination
  • Cursor-Based Pagination
  • Pagination Implementation
  • Example

Was this helpful?

Export as PDF
  1. Setup and Run Blockscout
  2. Configuration Options

Sorting and Pagination

Last updated 1 year ago

Was this helpful?

The sorting module is available for advanced data sorting and pagination. Data can be sorted within a column, via association, or with a dynamic query.

  • The feature was introduced here:

  • Features are implemented here:

  • is located at the bottom of this doc.

Ordering

To order any Ecto schema, use the Explorer.SortingHelper.apply_sorting/3 function. This function requires three arguments:

  • The Ecto query to be sorted (query)

  • User-provided sorting parameters (sorting)

  • Default sorting parameters (default_sorting)

Sorting Parameters

Sorting parameters follow the type Explorer.SortingHelper.sorting_params/0, which can be one of the following tuples:

  • {ordering, column}

  • {ordering, column, binding}

  • {:dynamic, column, ordering, Ecto.Query.dynamic_expr()}

Where:

  • ordering can be :asc, :asc_nulls_first, :asc_nulls_last, :desc, :desc_nulls_first, or :desc_nulls_last.

  • column is an atom representing the column name to sort by.

  • binding is an atom denoting the association or binding to use for the column.

Pagination

Pagination is handled by the Explorer.SortingHelper.page_with_sorting/4 function in conjunction with ordering. It uses the provided paging_options along with the sorting parameters to return a paginated query.

We use cursor based pagination because blockchain data may be quite large. After merging default and user provided sorting options we generate a dynamic query with a recursive condition for each column.

Blockscout employs cursor-based pagination for efficient handling of large blockchain datasets. This approach is facilitated by the Explorer.SortingHelper.page_with_sorting/4 function, which integrates sorting parameters with pagination options.

Cursor-Based Pagination

Cursor-based pagination is particularly suitable for blockchain data due to its potential size and frequent data updates. This method ensures that the same records are not retrieved more than once, even if new data is inserted between requests.

Pagination Implementation

The page_with_sorting function accepts the following arguments:

  1. The Ecto query object.

  2. Paging options that specify the cursor position and the page size.

  3. User-provided sorting parameters.

  4. Default sorting parameters.

By combining the default and user-provided sorting options, a dynamic query is constructed. This includes 'where' conditions that are applied recursively for each column involved in the sorting. This ensures that the pagination cursor moves accurately through the sorted records.

Using this function, developers can create paginated endpoints that respond quickly and consistently, even with the ever-growing amount of blockchain data.

Example

@default_sorting [
  desc_nulls_last: :circulating_market_cap,
  desc_nulls_last: :fiat_value,
  desc_nulls_last: :holder_count,
  asc: :name,
  asc: :contract_address_hash
]

...

@doc """
Lists the top `t:__MODULE__.t/0`'s'.
"""
@spec list_top(String.t() | nil, [
        Chain.paging_options()
        | {:sorting, SortingHelper.sorting_params()}
        | {:token_type, [String.t()]}
      ]) :: [Token.t()]
def list_top(filter, options \\ []) do
  paging_options = Keyword.get(options, :paging_options, Chain.default_paging_options())
  token_type = Keyword.get(options, :token_type, nil)
  sorting = Keyword.get(options, :sorting, [])

  query = from(t in Token, preload: [:contract_address])

  sorted_paginated_query =
    query
    |> apply_filter(token_type)
    |> SortingHelper.apply_sorting(sorting, @default_sorting)
    |> SortingHelper.page_with_sorting(paging_options, sorting, @default_sorting)

  filtered_query =
    case filter && filter !== "" && Search.prepare_search_term(filter) do
      {:some, filter_term} ->
        sorted_paginated_query
        |> where(fragment("to_tsvector('english', symbol || ' ' || name) @@ to_tsquery(?)", ^filter_term))

      _ ->
        sorted_paginated_query
    end

  filtered_query
  |> Chain.select_repo(options).all()
end

User-provided sorting is obtained from the query parameters of a REST API call through the tokens_sorting/1 function:

@spec tokens_sorting(%{required(String.t()) => String.t()}) :: [{:sorting, SortingHelper.sorting_params()}]
def tokens_sorting(%{"sort" => sort_field, "order" => order}) do
  [sorting: do_tokens_sorting(sort_field, order)]
end

def tokens_sorting(_), do: []

defp do_tokens_sorting("fiat_value", "asc"), do: [asc_nulls_first: :fiat_value]
defp do_tokens_sorting("fiat_value", "desc"), do: [desc_nulls_last: :fiat_value]
defp do_tokens_sorting("holder_count", "asc"), do: [asc_nulls_first: :holder_count]
defp do_tokens_sorting("holder_count", "desc"), do: [desc_nulls_last: :holder_count]
defp do_tokens_sorting("circulating_market_cap", "asc"), do: [asc_nulls_first: :circulating_market_cap]
defp do_tokens_sorting("circulating_market_cap", "desc"), do: [desc_nulls_last: :circulating_market_cap]
defp do_tokens_sorting(_, _), do: []

This function converts query parameters into sorting parameters understood by the sorting module.

🏃‍♂️
https://github.com/blockscout/blockscout/pull/8611
https://github.com/blockscout/blockscout/blob/master/apps/explorer/lib/explorer/sorting_helper.ex
An Example