README.md in jsonb_accessor-0.2.0 vs README.md in jsonb_accessor-0.3.0
- old
+ new
@@ -1,13 +1,24 @@
# JSONb Accessor
-[](https://travis-ci.org/devmynd/jsonb_accessor)
+[](http://badge.fury.io/rb/jsonb_accessor) [](https://travis-ci.org/devmynd/jsonb_accessor)
Adds typed `jsonb` backed fields as first class citizens to your `ActiveRecord` models. This gem is similar in spirit to [HstoreAccessor](https://github.com/devmynd/hstore_accessor), but the `jsonb` column in PostgreSQL has a few distinct advantages, mostly around nested documents and support for collections.
-**This gem is under heavy development. Please use cautiously and help us with feedback by opening issues for defects and feature requests. The current API is subject to change.**
+## Table of Contents
+* [Installation](#installation)
+* [Usage](#usage)
+* [ActiveRecord Methods Generated for Fields](#activerecord-methods-generated-for-fields)
+* [Validations](#validations)
+* [Single-Table Inheritance](#single-table-inheritance)
+* [Scopes](#scopes)
+* [Migrations](#migrations)
+* [Dependencies](#dependencies)
+* [Development](#development)
+* [Contributing](#contributing)
+
## Installation
Add this line to your application's `Gemfile`:
```ruby
@@ -40,11 +51,11 @@
:options,
:count, # => value type
title: :string,
id_value: :value,
external_id: :integer,
- reviewed_at: :datetime
+ reviewed_at: :date_time
)
end
```
JSONb Accessor accepts both untyped and typed key definitions. Untyped keys are treated as-is and no additional casting is performed. This allows the freedom of dynamic values alongside the power types, which is especially convenient when saving nested form attributes. Typed keys will be cast to their respective values using the same mechanism ActiveRecord uses to coerce standard attribute columns. It's as close to a real column as you can get and the goal is to keep it that way.
@@ -77,33 +88,45 @@
* `restore_field!`
* `field_will_change!`
### Supported Types
-The following types are supported, including typed collections:
+The following types are supported:
-```
-:array,
-:boolean,
-:boolean_array,
-:date,
-:date_array,
-:datetime,
-:datetime_array,
-:decimal,
-:decimal_array,
-:float,
-:float_array,
-:integer,
-:integer_array,
-:string,
-:string_array,
-:time,
-:time_array,
-:value
-```
+* big_integer
+* binary
+* bit
+* bit_varying
+* boolean
+* bytea
+* cidr
+* date
+* date_time
+* decimal
+* decimal_without_scale
+* enum
+* float
+* hstore
+* inet
+* integer
+* json
+* jsonb
+* money
+* point
+* range
+* specialized_string
+* string
+* text
+* time
+* unsigned_integer
+* uuid
+* value
+* vector
+* xml
+Typed arrays are also supported by specifying `:type_array` (i.e. `:float_array`). `:array` is interpreted as an array of `value` types.
+
Support for nested types is also available but experimental at this point. If you must, you may try something like this for nested objects.
```ruby
class Product < ActiveRecord::Base
jsonb_accessor(
@@ -121,14 +144,217 @@
Because this gem promotes attributes nested into the JSON column to first level attributes, most validations should just work. We still have to add some testing and support around this feature but feel free to try and leave us feedback if they're not working as expected.
## Single-Table Inheritance
-You can use it for STI in the same spirit as [hstore_accessor, which is documented here.](https://github.com/devmynd/hstore_accessor#single-table-inheritance).
+One of the big issues with `ActiveRecord` single-table inheritance (STI)
+is sparse columns. Essentially, as sub-types of the original table
+diverge further from their parent more columns are left empty in a given
+table. Postgres' `jsonb` type provides part of the solution in that
+the values in an `jsonb` column does not impose a structure - different
+rows can have different values.
+We set up our table with an `jsonb` field:
+
+```ruby
+# db/migration/<timestamp>_create_players_table.rb
+class CreateVehiclesTable < ActiveRecord::Migration
+ def change
+ create_table :vehicles do |t|
+ t.string :make
+ t.string :model
+ t.integer :model_year
+ t.string :type
+ t.jsonb :data
+ end
+ end
+end
+```
+
+And for our models:
+
+```ruby
+# app/models/vehicle.rb
+class Vehicle < ActiveRecord::Base
+end
+
+# app/models/vehicles/automobile.rb
+class Automobile < Vehicle
+ jsonb_accessor :data,
+ axle_count: :integer,
+ weight: :float
+end
+
+# app/models/vehicles/airplane.rb
+class Airplane < Vehicle
+ jsonb_accessor :data,
+ engine_type: :string,
+ safety_rating: :integer
+end
+```
+
+From here any attributes specific to any sub-class can be stored in the
+`jsonb` column avoiding sparse data. Indices can also be created on
+individual fields in an `jsonb` column.
+
+This approach was originally concieved by Joe Hirn in [this blog
+post](http://www.devmynd.com/blog/2013-3-single-table-inheritance-hstore-lovely-combination).
+
## Scopes
-Coming soon...
+JsonbAccessor currently supports several scopes. Let's say we have a class that looks like this:
+
+```ruby
+class Product < ActiveRecord::Base
+ jsonb_accessor :data,
+ approved: :boolean,
+ name: :string,
+ price: :integer,
+ previous_prices: :integer_array,
+ reviewed_at: :date_time
+end
+```
+
+### General Scopes
+
+#### `<jsonb_field>_contains`
+
+**Description:** returns all records that contain matching attributes in the specified `jsonb` field.
+
+```ruby
+product_1 = Product.create!(name: "foo", approved: true, reviewed_at: 3.days.ago)
+product_2 = Product.create!(name: "bar", approved: true)
+product_3 = Product.create!(name: "foo", approved: false)
+
+Product.data_contains(name: "foo", approved: true) # => [product_1]
+```
+
+**Note:** when including an array attribute, 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.
+
+#### `with_<jsonb_defined_field>`
+
+**Description:** returns all records with the given value in the field. This is defined for all `jsonb_accessor` defined fields. It's a convenience method that allows you to do `Product.with_name("foo")` instead of `Product.data_contains(name: "foo")`.
+
+```ruby
+product_1 = Product.create!(name: "foo")
+product_2 = Product.create!(name: "bar")
+
+Product.with_name("foo") # => [product_1]
+```
+
+**Note:** when including an array attribute, 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.
+
+### Integer, Big Integer, Decimal, and Float Scopes
+
+#### `<jsonb_defined_field>_gt`
+
+**Description:** returns all records with a value that is greater than the argument.
+
+```ruby
+product_1 = Product.create!(price: 10)
+product_2 = Product.create!(price: 11)
+
+Product.price_gt(10) # => [product_2]
+```
+
+#### `<jsonb_defined_field>_gte`
+
+**Description:** returns all records with a value that is greater than or equal to the argument.
+
+```ruby
+product_1 = Product.create!(price: 10)
+product_2 = Product.create!(price: 11)
+product_3 = Product.create!(price: 9)
+
+Product.price_gte(10) # => [product_1, product_2]
+```
+
+#### `<jsonb_defined_field>_lt`
+
+**Description:** returns all records with a value that is less than the argument.
+
+```ruby
+product_1 = Product.create!(price: 10)
+product_2 = Product.create!(price: 11)
+
+Product.price_lt(11) # => [product_1]
+```
+
+#### `<jsonb_defined_field>_lte`
+
+**Description:** returns all records with a value that is less than or equal to the argument.
+
+```ruby
+product_1 = Product.create!(price: 10)
+product_2 = Product.create!(price: 11)
+product_3 = Product.create!(price: 12)
+
+Product.price_lte(11) # => [product_1, product_2]
+```
+
+
+### Boolean Scopes
+
+#### `is_<jsonb_defined_field>`
+
+**Description:** returns all records where the value is `true`.
+
+```ruby
+product_1 = Product.create!(approved: true)
+product_2 = Product.create!(approved: false)
+
+Product.is_approved # => [product_1]
+```
+
+#### `not_<jsonb_defined_field>`
+
+**Description:** returns all records where the value is `false`.
+
+```ruby
+product_1 = Product.create!(approved: true)
+product_2 = Product.create!(approved: false)
+
+Product.not_approved # => [product_2]
+```
+
+### Date, DateTime Scopes
+
+#### `<jsonb_defined_field>_before`
+
+**Description:** returns all records where the value is before the argument. Also supports JSON string arguments.
+
+```ruby
+product_1 = Product.create!(reviewed_at: 3.days.ago)
+product_2 = Product.create!(reviewed_at: 5.days.ago)
+
+Product.reviewed_at_before(4.days.ago) # => [product_2]
+Product.reviewed_at_before(4.days.ago.to_json) # => [product_2]
+```
+
+#### `<jsonb_defined_field>_after`
+
+**Description:** returns all records where the value is after the argument. Also supports JSON string arguments.
+
+```ruby
+product_1 = Product.create!(reviewed_at: 3.days.from_now)
+product_2 = Product.create!(reviewed_at: 5.days.from_now)
+
+Product.reviewed_at_after(4.days.from_now) # => [product_2]
+Product.reviewed_at_after(4.days.from_now.to_json) # => [product_2]
+```
+
+### Array Scopes
+
+#### `<jsonb_defined_fields>_contains`
+
+**Description:** returns all records where the value is contained in the array field.
+
+```ruby
+product_1 = Product.create!(previous_prices: [3])
+product_2 = Product.create!(previous_prices: [4, 5, 6])
+
+Product.previous_prices_contains(5) # => [product_2]
+```
## Migrations
Coming soon...