{"id":15288838,"url":"https://github.com/ronaldchacon/yaqb","last_synced_at":"2026-01-05T05:47:15.213Z","repository":{"id":56899001,"uuid":"212444571","full_name":"ronaldchacon/yaqb","owner":"ronaldchacon","description":"Yet Another Query Builder","archived":false,"fork":false,"pushed_at":"2022-12-14T08:39:23.000Z","size":60,"stargazers_count":0,"open_issues_count":4,"forks_count":0,"subscribers_count":2,"default_branch":"develop","last_synced_at":"2025-03-02T15:18:10.865Z","etag":null,"topics":["api","filtering","kaminari","pagination","pagy","query-builder","rails","ruby","ruby-on-rails","sorting","will-paginate"],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ronaldchacon.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-10-02T21:27:09.000Z","updated_at":"2020-03-13T02:54:27.000Z","dependencies_parsed_at":"2023-01-28T20:15:39.548Z","dependency_job_id":null,"html_url":"https://github.com/ronaldchacon/yaqb","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ronaldchacon%2Fyaqb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ronaldchacon%2Fyaqb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ronaldchacon%2Fyaqb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ronaldchacon%2Fyaqb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ronaldchacon","download_url":"https://codeload.github.com/ronaldchacon/yaqb/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245217791,"owners_count":20579297,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","filtering","kaminari","pagination","pagy","query-builder","rails","ruby","ruby-on-rails","sorting","will-paginate"],"created_at":"2024-09-30T15:53:21.532Z","updated_at":"2026-01-05T05:47:15.142Z","avatar_url":"https://github.com/ronaldchacon.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Yaqb\n\n#### Yet Another Query Builder\nYaqb is query builder that will filter, sort and paginate your ActiveRecord collections.\n\nIn addition to query building, presenters are used to manage what a consumer of your API can query.\n\n## Installation\n\nIn your Gemfile\n\n```ruby\n# Choose your preferred pagination gem\ngem 'kaminari' # or\ngem 'will_paginate' # or\ngem 'pagy'\n\n# Then add\ngem 'yaqb'\n```\n\nAnd then execute:\n\n    $ bundle\n\nOr install it yourself as:\n\n    $ gem install yaqb\n\n## Configuration\n\nBy default, Yaqb will detect if you are using Kaminari, WillPaginate, or Pagy. If you want to change any of the configurable settings, you may do so:\n\n```ruby\nYaqb.configure do |config|\n  # If for whatever reason you are using multiple pagination gems, you can manually set which gem to use.\n  config.paginator = :kaminari # :will_paginate, :pagy\nend\n```\n\n## Usage\n\n### Controllers\n\nIn your controller, you will need to include the following the module: `Yaqb::Base`\n\n```ruby\nclass ApplicationController \u003c ActionController::Base # or ActionController::API\n  include Yaqb::Base\nend\n\n# And then to use Yaqb\n\nclass BooksController \u003c ApplicationController\n  def index\n    # #orchestrate expects a collection and a presenter.\n    # #orchestrate return a results object meaning you will have access to the following methods:\n    # #scope - This is your collection after being filtered, sorted and paginated\n    # #links - This returns a hash of links based on the paginated results.\n    result = orchestrate(Books.all, BookPresenter)\n\n    # Depending on your serializer you can render your data as so:\n    # BluePrinter gem by procore is used here:\n    render json: BookBlueprint.render(request.scope, root: :data, meta: { links: request.links })\n  end\nend\n```\n\nAt the moment Yaqb will require the following parameters to be passed through:\n\npagination: `page` and `per`\n\nsorting: `sort` and `dir`\n\nfiltering: `q[]`\n\n### Filtering\n\n#### Supported predicates\n\nThe following predicates are available: `eq`, `cont` `notcont` `start` `end` `gt` `lt`\n\nPredicates can be appended to a field set in your Presenter.\n\n#### Parameters\n\nParameters are passed through the param `q[]`.\n\nE.g. To filter by a title containing a word: `q[title_cont]`\n\nE.g. `title_eq` or `created_at_lt`\n\n### Presenters\n\nPresenters will allow you to control what a consumer of your API can sort and filter by.\n\nYour Presenter class will need to inherit from `Yaqb::Presenter`\n\n```ruby\nclass BookPresenter \u003c Yaqb::Presenter\n  sort_by :id, :title, :created_at, :updated_at\n  filter_by :id, :title\nend\n```\n\n### Handling Errors\n\nBy default Yaqb will rescue from any query errors with `QueryBuilderError` and return that error to the consumer\n\nGiven the following API call:\n\n`GET https://api.example.com/v1/books?per=a`\n\nThe following response will be returned\n\n```json\n{\n  \"error\": {\n    \"message\": \"Invalid pagination params. Only numbers are supported for \\\"page\\\" and \\\"per\\\"\",\n    \"invalid_params\": \"per=a\"\n  }\n}\n```\n\n## Development\n\nAfter checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.\n\nTo install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/yaqb. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).\n\n## Code of Conduct\n\nEveryone interacting in the Yaqb project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/yaqb/blob/master/CODE_OF_CONDUCT.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fronaldchacon%2Fyaqb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fronaldchacon%2Fyaqb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fronaldchacon%2Fyaqb/lists"}