{"id":23537311,"url":"https://github.com/jsonb-uy/filter_param","last_synced_at":"2026-01-27T17:44:20.764Z","repository":{"id":239453989,"uuid":"653951524","full_name":"jsonb-uy/filter_param","owner":"jsonb-uy","description":"Filter records using a SCIM Query-inspired filter expression format.","archived":false,"fork":false,"pushed_at":"2024-11-24T16:25:25.000Z","size":216,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-26T20:18:33.321Z","etag":null,"topics":["activerecord","filter","rails","ruby","scim"],"latest_commit_sha":null,"homepage":"","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/jsonb-uy.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-06-15T05:04:29.000Z","updated_at":"2024-11-24T16:25:29.000Z","dependencies_parsed_at":null,"dependency_job_id":"a8a69dc3-f0ff-4f2e-947d-17fac1d106dc","html_url":"https://github.com/jsonb-uy/filter_param","commit_stats":null,"previous_names":["jsonb-uy/filter_param"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jsonb-uy%2Ffilter_param","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jsonb-uy%2Ffilter_param/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jsonb-uy%2Ffilter_param/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jsonb-uy%2Ffilter_param/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jsonb-uy","download_url":"https://codeload.github.com/jsonb-uy/filter_param/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254249241,"owners_count":22039036,"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":["activerecord","filter","rails","ruby","scim"],"created_at":"2024-12-26T03:14:29.027Z","updated_at":"2026-01-27T17:44:15.743Z","avatar_url":"https://github.com/jsonb-uy.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# FilterParam\n\n[![Gem Version](https://badge.fury.io/rb/filter_param.svg)](https://badge.fury.io/rb/filter_param) [![CI](https://github.com/jsonb-uy/filter_param/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/jsonb-uy/filter_param/actions/workflows/ci.yml) [![codecov](https://codecov.io/gh/jsonb-uy/filter_param/graph/badge.svg?token=9242ULA2DC)](https://codecov.io/gh/jsonb-uy/filter_param) [![Maintainability](https://api.codeclimate.com/v1/badges/fb4df56368843000d1fd/maintainability)](https://codeclimate.com/github/jsonb-uy/filter_param/maintainability)\n\n### Record Filtering for apps built on Rails/ActiveRecord \n\nQuickly implement record filtering in your APIs using a filter expression inspired by [SCIM Query](https://datatracker.ietf.org/doc/html/rfc7644#section-3.4.2.2):\n\n```ruby\nhttps://{some origin}/users?filter=first_name eq 'John' and last_name pr and \n  not (active eq false and (birth_date gt '1991-01-01' or birth_date eq null))\n```\n\n**TL;DR** See [ sample usage for Rails here ](#rails-usage). \n\n## Features\n\n* Transpilation of the filter expression into SQL\n* Whitelisting of allowed filter attributes\n* Column name aliasing / expose a different attribute name in the API\n* Pre-processing of filter values/literals\n* Type validation of filter values (e.g., date and datetime literals should be in standard ISO 8601 format)\n* Allows custom filter operators\n* Expression grouping\n* Supports **MySQL**, **PostgreSQL**, and **SQLite**\n* Supports **Rails 6** and above\n\n### Field Filter Operators\n| Operator | Description | Example |\n| ----------- | ----------- | ----------- |\n| `eq` | Equal | name eq 'John' |\n| `eq_ci` | Case-insensitive Equal | name eq_ci 'joHn' |\n| `ne` | Not Equal | name ne 'john' |\n| `co` | Contains | name co 'oh' |\n| `sw ` | Starts With | name sw 'J' |\n| `pr ` | Present (has value) | name pr |\n| `gt` | Greater than | age gt 42 |\n| `ge` | Greater than or equal to | price ge 19.80 |\n| `lt` | Less than | created_at lt '2023-03-01T08:09:00+07:00' |\n| `le` | Less than or equal to | birthdate le '1985-05-01' |\n\n### Logical Operators\n| Operator | Description |\n| ----------- | ----------- |\n| `and` | Logical \"and\" |\n| `or` | Logical \"or\" |\n| `not` | \"Not\" function |\n\n### Grouping Operator\n| Operator | Description |\n| ----------- | ----------- |\n| `()` | Precedence grouping |\n\n### Literals\n| Type | Filter Definition Symbol | Examples |\n|-----------|----------- | ----------- |\n| Boolean| `:boolean` | `true`, `false` |\n| Integer| `:integer` | 40012, 100, 0, -51 |\n| Decimal| `:decimal` | 4002.12, 0.05, -41.13 |\n| String| `:string` | 'foo bar' |\n| Date (ISO format) | `:date` | '2024-12-31' |\n| Timestamp (ISO format) | `:datetime` | '2023-03-01T01:09:01.000Z', '2023-03-01T09:09:00+09:00' |\n| Null | N/A | null |\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'filter_param'\n```\n\nAnd then execute:\n\n```sh\nbundle install\n```\n\nOr install it yourself as:\n\n```sh\ngem install filter_param\n```\n\n## Usage\n### Basic\n\n#### 1. Whitelist/define the filter fields\n\n```ruby\nfitler_param = FilterParam.define do\n                 field :first_name, type: :string\n                 field :last_name, rename: \"family_name\"\n                 field :birth_date, type: :date\n                 field :member_since, type: :datetime\n                 field :active, type: :boolean\n               end\n```\n\n\nThis is is equivalent to:\n\n```ruby\nfilter_param = FilterParam::Definition.new\n                                      .field(:first_name, type: :string)\n                                      .field(:last_name, rename: \"family_name\")\n                                      .field(:birth_date, type: :date)\n                                      .field(:member_since, type: :datetime)\n                                      .field(:active, type: :boolean)\n```\n\n`field` method accepts the filter field name as the first argument. Any other configuration such as `:type` follows the name.\n\n#### 2. Filter records using a filter expression\n\nThe `filter!` method accepts an `ActiveRecord_Relation` and the filter expression string from your API's request parameter. This method then transpiles the filter expression into SQL and returns a new `ActiveRecord_Relation` with the SQL conditions applied.\n\n```ruby\nrel = filter_param.filter!(User.all, \"first_name eq 'John' and last_name pr and not (active eq false and (birth_date gt '1991-01-\n01' or birth_date eq null))\")\n``` \n\nTo see the SQL that will be executed in the ActiveRecord relation:\n\n```ruby\nrel.to_sql\n=\u003e \"SELECT \\\"users\\\".* FROM \\\"users\\\" WHERE (first_name = 'John' AND \n    (family_name IS NOT NULL AND TRIM(family_name) != '') AND \n      NOT (active = 0 AND (birth_date \u003e '1991-01-01' OR birth_date IS NULL)))\"\n```\n\n### Errors\n\n| Class | Description |\n| ----------- | ----------- |\n| `FilterParam::UnknownField` | A filter field in the given filter expression is not whitelisted in the filter definition. |\n| `FilterParam::ParseError` | The given filter expression can't be parsed possibly due to malformed expression or syntax issue. |\n| `FilterParam::InvalidLiteral` | A filter field value in the given filter expression is invalie (e.g., date and datetime should be in ISO 8601 format) |\n| `FilterParam::ExpressionError` | Generic error caused by the given filter expression. |\n| `FilterParam::UnknownType` | Configured `:type` of a filter field in the definition is invalid. |\n\n## Development\n\n1. If testing/developing for MySQL or PG, create the database first:\u003cbr/\u003e\n\n  ###### MySQL\n  ```sh\n  mysql\u003e CREATE DATABASE filter_param;\n  ```\n\n  ###### PostgreSQL\n  ```sh\n  $ createdb filter_param\n  ```\n\n2. After checking out the repo, run `bin/setup` to install dependencies.\n3. Run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment. Use the environment variables below to target the database\u003cbr/\u003e\u003cbr/\u003e\n  \n  By default, SQLite and the latest stable Rails version are used in tests and console. Refer to the environment variables below to change this:\n\n  | Environment Variable | Values | Example |\n  | ----------- | ----------- |----------- |\n  | `DB_ADAPTER` | **Default: :sqlite**. `sqlite`,`mysql2`, or `postgresql` | ```DB_ADAPTER=postgresql bundle exec rspec```\u003cbr/\u003e\u003cbr/\u003e ```DB_ADAPTER=postgresql ./bin/console``` |\n  | `RAILS_VERSION` | **Default: 8-0** \u003cbr/\u003e\u003cbr/\u003e `6-0`,`6-1`,`7-0`,`7-1`, `7-2`, `8-0` |```RAILS_VERSION=8-0 ./bin/setup```\u003cbr/\u003e\u003cbr/\u003e```RAILS_VERSION=8-0 bundle exec rspec```\u003cbr/\u003e\u003cbr/\u003e ```RAILS_VERSION=8-0 ./bin/console```|\n\n\n\u003cbr/\u003e\u003cbr/\u003e\nTo install this gem onto your local machine, run `bundle exec rake install`.\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at https://github.com/jsonb-uy/filter_param.\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjsonb-uy%2Ffilter_param","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjsonb-uy%2Ffilter_param","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjsonb-uy%2Ffilter_param/lists"}