Skip to main content

List API

This guide shows the recommended setup for a paginated list query using:

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 ModelName with 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
}
}
}