List API
This guide shows the recommended setup for a paginated list query using:
- EnumHelper for reusable enum types in sort inputs and filters
- PagingTypeHelper for standardized list response types
Prerequisites: run rails generate cm_admin:add_graphql first β it creates the Types::Inputs::Base and Types::Enums::Base classes used below. The helpers come from the cm-graphql companion library.
In all examples below, replace
ModelNamewith the model where you want this implemented.
1. Define input types for sortβ
Use EnumHelper for sort direction and model-specific sortable columns.
module Types
module Inputs
class ModelNameSort < Types::BaseInputObject
graphql_name 'ModelNameSortInput'
argument :column, Types::EnumHelpers.enum_from_array(%w[created_at name],
'ModelNameSortColumn'), required: false
argument :direction, Types::Enums::Base::SortDirection, required: false
end
end
end
2. Define input types for filtersβ
Use Types::Inputs::Base::Filter as the base class β it already provides a q field for search and an ids field.
module Types
module Inputs
class ModelNameFilter < Types::Inputs::Base::Filter
graphql_name 'ModelNameFilterInput'
argument :some_fields, [String], required: false
end
end
end
3. Define the list query using PagingTypeHelperβ
module Queries
module ModelName
class List < Queries::BaseQuery
description 'list records on a model'
argument :filters, Types::Inputs::ModelNameFilter, required: false
argument :sort, Types::Inputs::ModelNameSort, required: false
argument :pagination, Types::Inputs::Base::Paging, required: false
type Types::PagingTypeHelper.paging_type_for_model(model: ::ModelName), null: true
def resolve(filters: nil, pagination: nil, sort: nil)
per_page = pagination&.per_page || DEFAULT_PER_PAGE
page = pagination&.page_no || 1
::ModelName.filters(filters).order_by(sort&.column, sort&.direction).list(per_page, page)
end
end
end
end
4. Add the query to your root QueryTypeβ
module Types
class QueryType < Types::BaseObject
field :model_names, resolver: Queries::ModelName::List, description: 'List ModelName records'
end
end
5. Add the required scopes to the modelβ
The query above calls filters and order_by on the model, plus a <field>_filter scope per filter argument:
class ModelName < ApplicationRecord
scope :search_filter, lambda { |query|
return all if query.blank?
where('model_names.name ILIKE ?', "%#{query}%")
}
scope :ids_filter, lambda { |ids|
return all if ids.blank?
where(id: ids)
}
scope :order_by, lambda { |column, direction = 'asc'|
return all if column.blank?
order(column => direction)
}
scope :some_fields_filter, lambda { |some_fields|
return all if some_fields.blank?
where(some_field: some_fields)
}
def self.filters(filters)
return all if filters.blank?
all
.search_filter(filters[:q])
.ids_filter(filters[:ids])
.some_fields_filter(filters[:some_fields])
end
end
6. Query itβ
The finished list query looks like this from a client:
query {
modelNames(
filters: { q: "foo" }
sort: { column: NAME, direction: asc }
pagination: { pageNo: 1, perPage: 20 }
) {
data {
id
}
paging {
currentPage
totalCount
totalPages
}
}
}