키셋 페이지네이션

키셋 페이지네이션 라이브러리는 HAML 기반 뷰와 GitLab 프로젝트 내 REST API에서 사용할 수 있습니다.

keyset 페이지네이션 및 오프셋 기반 페이지네이션과 비교한 내용을 확인할 수 있습니다.

API 개요

시놉시스

Rails 컨트롤러의 ActiveRecord와 함께 사용하는 키셋 페이지네이션: 

cursor = params[:cursor] # 첫 번째 페이지를 요청할 때는 nil
paginator = Project.order(:created_at).keyset_paginate(cursor: cursor, per_page: 20)

paginator.each do |project|
  puts project.name # 최대 20개의 프로젝트 출력
end

사용법

이 라이브러리는 ActiveRecord 관계에 단일 메소드인 #keyset_paginate를 추가합니다.

이는 Kaminari의 paginate 메소드와 정신적으로 유사하지만 구현은 다릅니다.

키셋 페이지네이션은 다음과 같은 간단한 ActiveRecord 쿼리를 위한 구성없이 작동합니다:

  • 단일 열로 정렬합니다.
  • 마지막 열이 기본 키인 두 개의 열로 정렬합니다.

이 라이브러리는 널 가능한 열과 중복되지 않는 열을 감지하고 이에 따라 기본 키를 사용하여 추가적인 정렬을 추가합니다. 이는 키셋 페이지네이션에서 고유한 정렬 값을 기대하기 때문에 필요합니다. 

Project.order(:created_at).keyset_paginate.records # created_at, id를 기준으로 정렬

Project.order(:name).keyset_paginate.records # name, id를 기준으로 정렬

Project.order(:created_at, id: :desc).keyset_paginate.records # created_at, id를 기준으로 정렬

Project.order(created_at: :asc, id: :desc).keyset_paginate.records # created_at, id를 기준으로 정렬(desc)

keyset_paginate 메소드는 특별한 페이지네이터 개체를 반환하며, 로드된 레코드와 다양한 페이지를 요청하기 위한 추가 정보를 포함합니다.

이 메소드는 다음 키워드 인수를 허용합니다:

  • cursor - 다음 페이지를 요청할 때의 인코딩된 정렬 열 값(사용 가능한 경우 nil).
  • per_page - 페이지 당 로드할 레코드 수(기본값 20).
  • keyset_order_options - 키셋 페이지네이션 데이터베이스 쿼리를 작성하는 데 사용되는 추가 옵션(선택 사항).

페이지네이터 개체에는 다음과 같은 메소드가 있습니다:

  • records - 현재 페이지의 레코드를 반환합니다.
  • has_next_page? - 다음 페이지가 있는지 여부를 알려줍니다.
  • has_previous_page? - 이전 페이지가 있는지 여부를 알려줍니다.
  • cursor_for_next_page - 다음 페이지를 요청할 때의 문자열로 인코딩된 값(사용 가능한 경우 nil).
  • cursor_for_previous_page - 이전 페이지를 요청할 때의 문자열로 인코딩된 값(사용 가능한 경우 nil).
  • cursor_for_first_page - 처음 페이지를 요청할 때의 문자열로 인코딩된 값입니다.
  • cursor_for_last_page - 마지막 페이지를 요청할 때의 문자열로 인코딩된 값입니다.
  • 페이지네이터 개체에는 Enumerable 모듈이 포함되어 있으며, 열거 기능을 records 메소드/배열로 위임합니다.

첫 번째 및 두 번째 페이지 가져오는 예: 

paginator = Project.order(:name).keyset_paginate

paginator.to_a # .records와 동일

cursor = paginator.cursor_for_next_page # 다음 페이지용 인코딩된 열 속성

paginator = Project.order(:name).keyset_paginate(cursor: cursor).records # 다음 페이지 로드

페이지 번호를 지원하지 않으므로, 다음 페이지로만 이동할 수 있습니다:

  • 다음 페이지
  • 이전 페이지
  • 마지막 페이지
  • 첫 페이지

paginate_with_strategies를 사용한 REST API에서의 사용법

REST API에서 관계에 paginate_with_strategies 도우미를 사용하여 키셋 페이지네이션 또는 오프셋 페이지네이션을 사용할 수 있습니다. 

  desc '프로젝트와 관련된 항목 가져오기' do
    detail '이 기능은 GitLab 16.1에서 추가되었습니다.'
    success code: 200, model: ::API::Entities::Thing
    failure [
      { code: 401, message: '권한 없음' },
      { code: 403, message: '금지됨' },
      { code: 404, message: '찾을 수 없음' }
    ]
  end
  params do
    use :pagination
    requires :project_id, type: Integer, desc: '프로젝트 ID'
    optional :cursor, type: String, desc: '레코드의 다음 집합을 얻기 위한 커서'
    optional :order_by, type: String, values: %w[id name], default: 'id',
      desc: '정렬 기준 속성'
    optional :sort, type: String, values: %w[asc desc], default: 'desc', desc: '정렬 순서'
  end
  route_setting :authentication
  get ':project_id/things' do
    project = Project.find_by_id(params[:project_id])

    not_found! if project.blank?

    things = project.things

    present paginate_with_strategies(things), with: ::API::Entities::Thing
  end

키셋 페이지네이션을 사용하려면 다음 조건을 충족해야 합니다:

  1. params[:pagination]이 'keyset'을 반환해야 합니다.

  2. params[:order_by] 및 params[:sort]가 모델의 supported_keyset_orderings 클래스 메소드에서 반환된 객체에 모두 표시되어야 합니다. 다음 예에서 Thing은 ID에 의해 오름차순 또는 내림차순으로 정렬할 때 키셋 페이지네이션을 지원합니다. 

    class Thing < ApplicationRecord
  def self.supported_keyset_orderings
   { id: [:asc, :desc] }
  end
end

HAML 뷰에서의 사용법

다음 컨트롤러 동작을 고려해 보겠습니다. 여기서는 이름으로 정렬된 프로젝트를 나열합니다: 

def index
  @projects = Project.order(:name).keyset_paginate(cursor: params[:cursor])
end

HAML 파일에서 레코드를 렌더링할 수 있습니다: 

- if @projects.any?
  - @projects.each do |project|
    .project-container
      = project.name

  = keyset_paginate @projects

성능

키셋 페이지네이션의 성능은 데이터베이스 인덱스 구성 및 ORDER BY 절에서 사용하는 열의 수에 의해 달라집니다.

기본 키(id)로 정렬하는 경우, 생성된 쿼리는 데이터베이스 인덱스에서 기본 키가 포함되어 있기 때문에 효율적입니다.

ORDER BY 절에서 두 개 이상의 열을 사용하는 경우, 생성된 데이터베이스 쿼리를 확인하고 올바른 인덱스 구성이 사용되었는지 확인하는 것이 좋습니다. 자세한 정보는 페이지네이션 가이드 페이지에서 찾을 수 있습니다.

참고: 첫 페이지의 쿼리 성능은 좋아 보일 수 있지만, 쿼리에서 커서 속성이 사용되는 두 번째 페이지는 성능이 좋지 않을 수 있습니다. 첫 번째 페이지와 두 번째 페이지의 성능을 항상 확인하는 것이 좋습니다.

키셋-브레이커(id) 열이 있는 데이터베이스 쿼리 예시: 

SELECT "issues".*
FROM "issues"
WHERE (("issues"."id" > 99
      AND "issues"."created_at" = '2021-02-16 11:26:17.408466')
    OR ("issues"."created_at" > '2021-02-16 11:26:17.408466')
    OR ("issues"."created_at" IS NULL))
ORDER BY "issues"."created_at" DESC NULLS LAST, "issues"."id" DESC
LIMIT 20

PostgreSQL에서 OR 쿼리는 최적화하기 어려우므로 일반적으로 UNION 쿼리를 사용하는 것이 좋습니다. 키셋 페이지네이션 라이브러리는 ORDER BY 절에 여러 열이 포함되어 있는 경우 효율적인 UNION을 생성할 수 있습니다. 이는 Relation#keyset_paginate에 전달된 옵션에서 use_union_optimization: true 옵션을 지정했을 때 트리거됩니다.

예시: 

# 첫 번째 페이지에 대한 간단한 쿼리를 트리거합니다.
paginator1 = Project.order(:created_at, id: :desc).keyset_paginate(per_page: 2, keyset_order_options: { use_union_optimization: true })

cursor = paginator1.cursor_for_next_page

# 두 번째 페이지에 대한 UNION 쿼리를 트리거합니다.
paginator2 = Project.order(:created_at, id: :desc).keyset_paginate(per_page: 2, cursor: cursor, keyset_order_options: { use_union_optimization: true })

puts paginator2.records.to_a # UNION 쿼리

복잡한 주문 구성

공통 ORDER BY 구성은 keyset_paginate 메서드에서 자동으로 처리되므로 수동 구성이 필요하지 않습니다. 주문 객체 구성이 필요한 몇 가지 특별한 경우가 있습니다.

  • NULLS LAST 순서 지정.
  • 함수 기반의 순서 지정.
  • iid와 같은 사용자 정의 tie-breaker 열을 사용한 순서 지정.

이러한 주문 객체는 모델 클래스에서 일반적인 ActiveRecord 스코프로 정의할 수 있으며, 다른 곳(Kaminari, 백그라운드 작업)에서 사용하는 데 제한이 없습니다.

NULLS LAST 순서 지정

다음 스코프를 고려해 보십시오. 

scope = Issue.where(project_id: 10).order(Issue.arel_table[:relative_position].desc.nulls_last)
# SELECT "issues".* FROM "issues" WHERE "issues"."project_id" = 10 ORDER BY relative_position DESC NULLS LAST

scope.keyset_paginate # raises: Gitlab::Pagination::Keyset::UnsupportedScopeOrder: The order on the scope does not support keyset pagination

주문 값이 사용자 정의 SQL 문자열이기 때문에 keyset_paginate 메서드가 에러를 발생시킵니다. 이는 Arel AST 노드가 아니기 때문입니다. keyset 라이브러리는 이러한 유형의 쿼리로부터 구성 값을 자동으로 추론할 수 없습니다.

keyset 페이지네이션을 사용하려면 주문 열에 대한 사용자 정의 주문 객체를 구성해줘야 합니다. 이를 위해 주문 열에 관한 정보를 수집해야 합니다.

  • relative_position에는 중복된 값이 있을 수 있습니다. 왜냐하면 고유한 인덱스가 없기 때문입니다.
  • relative_position에는 null 값을 가질 수 있습니다. 왜냐하면 열에 not null 제약 조건이 없기 때문입니다. 이에 대해 NULL 값을 처음 또는 마지막 결과 집합에서 볼 수 있는지 결정해야 합니다(NULLS LAST).
  • Keyset 페이지네이션에는 고유한 주문 열이 필요하므로 주문 열에 기본 키(id)를 추가해야 합니다.
  • 마지막 페이지로 이동하고 뒤로 페이지네이트하면 실제로 ORDER BY 절이 뒤바뀝니다. 이에 대해 뒤집힌 ORDER BY 절을 제공해야 합니다.

예: 

order = Gitlab::Pagination::Keyset::Order.build([
  # 이러한 속성은 `lib/gitlab/pagination/keyset/column_order_definition.rb` 파일에서 문서화되어 있습니다.
  Gitlab::Pagination::Keyset::ColumnOrderDefinition.new(
    attribute_name: 'relative_position',
    column_expression: Issue.arel_table[:relative_position],
    order_expression: Issue.arel_table[:relative_position].desc.nulls_last,
    reversed_order_expression: Issue.arel_table[:relative_position].asc.nulls_first,
    nullable: :nulls_last,
    order_direction: :desc
  ),
  Gitlab::Pagination::Keyset::ColumnOrderDefinition.new(
    attribute_name: 'id',
    order_expression: Issue.arel_table[:id].asc,
    nullable: :not_nullable
  )
])

scope = Issue.where(project_id: 10).order(order) # 또는 reorder()

scope.keyset_paginate.records # 작동

함수 기반의 순서 지정

다음 예에서는 id를 10배로 곱하고 해당 값으로 정렬합니다. id 열이 고유하므로 하나의 열만 정의합니다. 

order = Gitlab::Pagination::Keyset::Order.build([
  Gitlab::Pagination::Keyset::ColumnOrderDefinition.new(
    attribute_name: 'id_times_ten',
    order_expression: Arel.sql('id * 10').asc,
    nullable: :not_nullable,
    order_direction: :asc,
    add_to_projections: true
  )
])

paginator = Issue.where(project_id: 10).order(order).keyset_paginate(per_page: 5)
puts paginator.records.map(&:id_times_ten)

cursor = paginator.cursor_for_next_page

paginator = Issue.where(project_id: 10).order(order).keyset_paginate(cursor: cursor, per_page: 5)
puts paginator.records.map(&:id_times_ten)

add_to_projections 플래그는 페이지네이터가 SELECT 절에서 열 표현을 노출하도록 지정합니다. 이것은 keyset 페이지네이션에서 레코드에서 마지막 값 추출 방법이 필요하기 때문에 필요합니다.

iid 기반의 순서 지정

이슈를 정렬할 때 데이터베이스는 프로젝트 내에서 고유한 iid 값을 가지도록 합니다. project_id 필터가 있는 경우 단일 열에 의해 정렬하는 것으로 페이징을 작동시킬 수 있습니다. 

order = Gitlab::Pagination::Keyset::Order.build([
  Gitlab::Pagination::Keyset::ColumnOrderDefinition.new(
    attribute_name: 'iid',
    order_expression: Issue.arel_table[:iid].asc,
    nullable: :not_nullable
  )
])

scope = Issue.where(project_id: 10).order(order)

scope.keyset_paginate.records # 작동