{"id":13879757,"url":"https://github.com/madeintandem/jsonb_accessor","last_synced_at":"2025-04-08T12:09:25.963Z","repository":{"id":29738516,"uuid":"33281933","full_name":"madeintandem/jsonb_accessor","owner":"madeintandem","description":"Adds typed jsonb backed fields to your ActiveRecord models.","archived":false,"fork":false,"pushed_at":"2024-04-07T11:11:20.000Z","size":554,"stargazers_count":1113,"open_issues_count":4,"forks_count":92,"subscribers_count":31,"default_branch":"master","last_synced_at":"2025-04-01T11:01:58.783Z","etag":null,"topics":["activerecord","jsonb","jsonb-accessor","postgres","query","ruby"],"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/madeintandem.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-04-02T01:14:40.000Z","updated_at":"2025-03-27T12:51:41.000Z","dependencies_parsed_at":"2024-06-18T14:04:48.213Z","dependency_job_id":"e5c76823-31fb-4438-9de1-f1e0376eef17","html_url":"https://github.com/madeintandem/jsonb_accessor","commit_stats":null,"previous_names":["devmynd/jsonb_accessor"],"tags_count":29,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/madeintandem%2Fjsonb_accessor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/madeintandem%2Fjsonb_accessor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/madeintandem%2Fjsonb_accessor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/madeintandem%2Fjsonb_accessor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/madeintandem","download_url":"https://codeload.github.com/madeintandem/jsonb_accessor/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247838444,"owners_count":21004580,"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","jsonb","jsonb-accessor","postgres","query","ruby"],"created_at":"2024-08-06T08:02:31.736Z","updated_at":"2025-04-08T12:09:25.931Z","avatar_url":"https://github.com/madeintandem.png","language":"Ruby","readme":"# JSONb Accessor\n\nCreated by \u0026nbsp;\u0026nbsp;\u0026nbsp; [\u003cimg src=\"https://raw.githubusercontent.com/madeintandem/jsonb_accessor/master/tandem-logo.png\" alt=\"Tandem Logo\" /\u003e](https://www.madeintandem.com/)\n\n[![Gem Version](https://badge.fury.io/rb/jsonb_accessor.svg)](http://badge.fury.io/rb/jsonb_accessor) \u0026nbsp;\u0026nbsp;\u0026nbsp;![CI](https://github.com/madeintandem/jsonb_accessor/actions/workflows/ci.yml/badge.svg) \u003cimg src=\"https://raw.githubusercontent.com/madeintandem/jsonb_accessor/master/json-bee.png\" alt=\"JSONb Accessor Logo\" align=\"right\" /\u003e\n\nAdds typed `jsonb` backed fields as first class citizens to your `ActiveRecord` models. This gem is similar in spirit to [HstoreAccessor](https://github.com/madeintandem/hstore_accessor), but the `jsonb` column in PostgreSQL has a few distinct advantages, mostly around nested documents and support for collections.\n\nIt also adds generic scopes for querying `jsonb` columns.\n\n## ⚠️ Status of this gem\n\nHi, [I](https://github.com/haffla) have taken over this gem a while back as sole maintainer from the original creators who had abandoned it. \nThis gem is in maintance mode now. No active development. Bug reports will be reviewed and worked on promptly. I will also make sure that the\ngem will keep working with new Ruby/Rails versions. But I don't have time to constantly improve the gem and add new features, let alone\ntake care of feature requests. I am happy though to accept PRs that add new features or improve things. Please open an issue before and let's discuss it.\n\n## Table of Contents\n\n- [Installation](#installation)\n- [Usage](#usage)\n- [Scopes](#scopes)\n- [Single-Table Inheritance](#single-table-inheritance)\n- [Dependencies](#dependencies)\n- [Validations](#validations)\n- [Upgrading](#upgrading)\n- [Development](#development)\n- [Contributing](#contributing)\n\n## Installation\n\nAdd this line to your application's `Gemfile`:\n\n```ruby\ngem \"jsonb_accessor\"\n```\n\nAnd then execute:\n\n    $ bundle install\n\n## Usage\n\nFirst we must create a model which has a `jsonb` column available to store data into it:\n\n```ruby\nclass CreateProducts \u003c ActiveRecord::Migration\n  def change\n    create_table :products do |t|\n      t.jsonb :data\n    end\n  end\nend\n```\n\nWe can then declare the `jsonb` fields we wish to expose via the accessor:\n\n```ruby\nclass Product \u003c ActiveRecord::Base\n  jsonb_accessor :data,\n    title: :string,\n    external_id: :integer,\n    reviewed_at: :datetime\nend\n```\n\nAny type the [`attribute` API](http://api.rubyonrails.org/classes/ActiveRecord/Attributes/ClassMethods.html#method-i-attribute) supports. You can also implement your own type by following the example in the `attribute` documentation.\n\nTo pass through options like `default` and `array` to the `attribute` API, just put them in an array.\n\n```ruby\nclass Product \u003c ActiveRecord::Base\n  jsonb_accessor :data,\n    title: [:string, default: \"Untitled\"],\n    previous_titles: [:string, array: true, default: []]\nend\n```\n\nThe `default` option works pretty much as you would expect in practice; if no values are set for the attributes, a hash of the specified default values is saved to the jsonb column.\n\nYou can also pass in a `store_key` option.\n\n```ruby\nclass Product \u003c ActiveRecord::Base\n  jsonb_accessor :data, title: [:string, store_key: :t]\nend\n```\n\nThis allows you to use `title` for your getters and setters, but use `t` as the key in the `jsonb` column.\n\n```ruby\nproduct = Product.new(title: \"Foo\")\nproduct.title #=\u003e \"Foo\"\nproduct.data #=\u003e { \"t\" =\u003e \"Foo\" }\n```\n\n## Scopes\n\nJsonb Accessor provides several scopes to make it easier to query `jsonb` columns. `jsonb_contains`, `jsonb_number_where`, `jsonb_time_where`, and `jsonb_where` are available on all `ActiveRecord::Base` subclasses and don't require that you make use of the `jsonb_accessor` declaration.\n\nIf a class does have a `jsonb_accessor` declaration, then we define one custom scope. So, let's say we have a class that looks like this:\n\n```ruby\nclass Product \u003c ActiveRecord::Base\n  jsonb_accessor :data,\n    name: :string,\n    price: [:integer, store_key: :p],\n    price_in_cents: :integer,\n    reviewed_at: :datetime\nend\n```\n\nJsonb Accessor will add a `scope` to `Product` called like the json column with `_where` suffix, in our case `data_where`.\n\n```ruby\nProduct.all.data_where(name: \"Granite Towel\", price: 17)\n```\n\nSimilarly, it will also add a `data_where_not` `scope` to `Product`.\n\n```ruby\nProduct.all.data_where_not(name: \"Plasma Fork\")\n```\n\nFor number fields you can query using `\u003c` or `\u003e`or use plain english if that's what you prefer.\n\n```ruby\nProduct.all.data_where(price: { \u003c: 15 })\nProduct.all.data_where(price: { \u003c=: 15 })\nProduct.all.data_where(price: { less_than: 15 })\nProduct.all.data_where(price: { less_than_or_equal_to: 15 })\n\nProduct.all.data_where(price: { \u003e: 15 })\nProduct.all.data_where(price: { \u003e=: 15 })\nProduct.all.data_where(price: { greater_than: 15 })\nProduct.all.data_where(price: { greater_than_or_equal_to: 15 })\n\nProduct.all.data_where(price: { greater_than: 15, less_than: 30 })\n```\n\nFor time related fields you can query using `before` and `after`.\n\n```ruby\nProduct.all.data_where(reviewed_at: { before: Time.current.beginning_of_week, after: 4.weeks.ago })\n```\n\nIf you want to search for records within a certain time, date, or number range, just pass in the range (Note: this is just shorthand for the above mentioned `before`/`after`/`less_than`/`less_than_or_equal_to`/`greater_than_or_equal_to`/etc options).\n\n```ruby\nProduct.all.data_where(price: 10..20)\nProduct.all.data_where(price: 10...20)\nProduct.all.data_where(reviewed_at: Time.current..3.days.from_now)\n```\n\nThis scope is a convenient wrapper around the `jsonb_where` `scope` that saves you from having to convert the given keys to the store keys and from specifying the column.\n\n### `jsonb_where`\n\nWorks just like the [`scope` above](#scopes) except that it does not convert the given keys to store keys and you must specify the column name. For example:\n\n```ruby\nProduct.all.jsonb_where(:data, reviewed_at: { before: Time.current }, p: { greater_than: 5 })\n\n# instead of\n\nProduct.all.data_where(reviewed_at: { before: Time.current }, price: { greater_than: 5 })\n```\n\nThis scope makes use of the `jsonb_contains`, `jsonb_number_where`, and `jsonb_time_where` `scope`s.\n\n### `jsonb_where_not`\n\nJust the opposite of `jsonb_where`. Note that this will automatically exclude all records that contain `null` in their jsonb column (the `data` column, in the example below).\n\n```ruby\nProduct.all.jsonb_where_not(:data, reviewed_at: { before: Time.current }, p: { greater_than: 5 })\n```\n\n### `\u003cjsonb_attribute\u003e_order`\n\nOrders your query according to values in the Jsonb Accessor fields similar to ActiveRecord's `order`.\n\n```ruby\nProduct.all.data_order(:price)\nProduct.all.data_order(:price, :reviewed_at)\nProduct.all.data_order(:price, reviewed_at: :desc)\n```\n\nIt will convert your given keys into store keys if necessary.\n\n### `jsonb_order`\n\nAllows you to order by a Jsonb Accessor field.\n\n```ruby\nProduct.all.jsonb_order(:data, :price, :asc)\nProduct.all.jsonb_order(:data, :price, :desc)\n```\n\n### `jsonb_contains`\n\nReturns all records that contain the given JSON paths.\n\n```ruby\nProduct.all.jsonb_contains(:data, title: \"foo\")\nProduct.all.jsonb_contains(:data, reviewed_at: 10.minutes.ago, p: 12) # Using the store key\n```\n\n**Note:** Under the hood, `jsonb_contains` uses the [`@\u003e` operator in Postgres](https://www.postgresql.org/docs/9.5/static/functions-json.html) so when you include an array query, the stored array and the array used for the query do not need to match exactly. For example, when queried with `[1, 2]`, records that have arrays of `[2, 1, 3]` will be returned.\n\n### `jsonb_excludes`\n\nReturns all records that exclude the given JSON paths. Pretty much the opposite of `jsonb_contains`. Note that this will automatically exclude all records that contain `null` in their jsonb column (the `data` column, in the example below).\n\n```ruby\nProduct.all.jsonb_excludes(:data, title: \"foo\")\nProduct.all.jsonb_excludes(:data, reviewed_at: 10.minutes.ago, p: 12) # Using the store key\n```\n\n### `jsonb_number_where`\n\nReturns all records that match the given criteria.\n\n```ruby\nProduct.all.jsonb_number_where(:data, :price_in_cents, :greater_than, 300)\n```\n\nIt supports:\n\n- `\u003e`\n- `\u003e=`\n- `greater_than`\n- `greater_than_or_equal_to`\n- `\u003c`\n- `\u003c=`\n- `less_than`\n- `less_than_or_equal_to`\n\nand it is indifferent to strings/symbols.\n\n### `jsonb_number_where_not`\n\nReturns all records that do not match the given criteria. It's the opposite of `jsonb_number_where`. Note that this will automatically exclude all records that contain `null` in their jsonb column (the `data` column, in the example below).\n\n```ruby\nProduct.all.jsonb_number_where_not(:data, :price_in_cents, :greater_than, 300)\n```\n\n### `jsonb_time_where`\n\nReturns all records that match the given criteria.\n\n```ruby\nProduct.all.jsonb_time_where(:data, :reviewed_at, :before, 2.days.ago)\n```\n\nIt supports `before` and `after` and is indifferent to strings/symbols.\n\n### `jsonb_time_where_not`\n\nReturns all records that match the given criteria. The opposite of `jsonb_time_where`. Note that this will automatically exclude all records that contain `null` in their jsonb column (the `data` column, in the example below).\n\n```ruby\nProduct.all.jsonb_time_where_not(:data, :reviewed_at, :before, 2.days.ago)\n```\n\n## Single-Table Inheritance\n\nOne of the big issues with `ActiveRecord` single-table inheritance (STI)\nis sparse columns. Essentially, as sub-types of the original table\ndiverge further from their parent more columns are left empty in a given\ntable. Postgres' `jsonb` type provides part of the solution in that\nthe values in an `jsonb` column does not impose a structure - different\nrows can have different values.\n\nWe set up our table with an `jsonb` field:\n\n```ruby\n# db/migration/\u003ctimestamp\u003e_create_players.rb\nclass CreateVehicles \u003c ActiveRecord::Migration\n  def change\n    create_table :vehicles do |t|\n      t.string :make\n      t.string :model\n      t.integer :model_year\n      t.string :type\n      t.jsonb :data\n    end\n  end\nend\n```\n\nAnd for our models:\n\n```ruby\n# app/models/vehicle.rb\nclass Vehicle \u003c ActiveRecord::Base\nend\n\n# app/models/vehicles/automobile.rb\nclass Automobile \u003c Vehicle\n  jsonb_accessor :data,\n    axle_count: :integer,\n    weight: :float\nend\n\n# app/models/vehicles/airplane.rb\nclass Airplane \u003c Vehicle\n  jsonb_accessor :data,\n    engine_type: :string,\n    safety_rating: :integer\nend\n```\n\nFrom here any attributes specific to any sub-class can be stored in the\n`jsonb` column avoiding sparse data. Indices can also be created on\nindividual fields in an `jsonb` column.\n\nThis approach was originally conceived by Joe Hirn in [this blog\npost](https://madeintandem.com/blog/2013-3-single-table-inheritance-hstore-lovely-combination/).\n\n## Validations\n\nBecause this gem promotes attributes nested into the JSON column to first level attributes, most validations should just work. Please leave us feedback if they're not working as expected.\n\n## Dependencies\n\n- Ruby \u003e 3. Lower versions are not tested.\n- ActiveRecord \u003e= 6.1\n- Postgres \u003e= 9.4 (in order to use the [jsonb column type](http://www.postgresql.org/docs/9.4/static/datatype-json.html)).\n\n## Upgrading\n\nSee the [upgrade guide](UPGRADE_GUIDE.md).\n\n## Development\n\n### On your local machine\n\nAfter checking out the repo, run `bin/setup` to install dependencies (make sure postgres is running first).\n\nRun `bin/console` for an interactive prompt that will allow you to experiment.\n\n`rake` will run Rubocop and the specs.\n\n### With Docker\n\n```\n# setup\ndocker-compose build\ndocker-compose run ruby rake db:migrate\n# run test suite\ndocker-compose run ruby rake spec\n```\n\n## Contributing\n\n1. [Fork it](https://github.com/madeintandem/jsonb_accessor/fork)\n2. Create your feature branch (`git checkout -b my-new-feature`)\n3. Add tests and changes (run the tests with `rake`)\n4. Commit your changes (`git commit -am 'Add some feature'`)\n5. Push to the branch (`git push origin my-new-feature`)\n6. Create a new Pull Request\n\n## Alternatives\n\n- https://github.com/DmitryTsepelev/store_model 💪\n- https://github.com/palkan/store_attribute ❤️\n- https://github.com/jrochkind/attr_json 🤩\n","funding_links":[],"categories":["Ruby"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmadeintandem%2Fjsonb_accessor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmadeintandem%2Fjsonb_accessor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmadeintandem%2Fjsonb_accessor/lists"}