dynamoid 3.2.0 → 3.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 193003bce5df92dae1a2ad3a4f94345bc610193b0da7692eb6f722231e1becae
-  data.tar.gz: 36fb0bdea8126c6fd9af32343ad5d0ebe87ca92d01caab17fb9fe87aa74d07a6
+  metadata.gz: 26990dd042447eeba355601d0c7eb3657bcc482e80d00c1da5602d2f82765504
+  data.tar.gz: 76e1778155fb8a7a1d3135d4886d9e7caf1a07b72263fc38d9162ae946d5dab1
 SHA512:
-  metadata.gz: 3c53982905e1e487db42f0497f682e4a62b33d8adf1b1b7079e98f5d1635e338396aa62bef467483406ab558d4ad66a2a285ac72c90d5f278530026fbcb96fa1
-  data.tar.gz: 2d8e83e5ea4ba495ac6ec37c7178b8f77db4d0b2e33210c698ef00f8f92f1762672df3ca64c70e053f173d040e2abafe01bdd0c850499f65523fb9a50c2f0a7b
+  metadata.gz: 2aadf93639577566ed5dd9dadff596316f3d22384f5d7dabd0e06aa49992d3a58e824a8c150002c3a39d6e42f7b2b17c4f383bda2c145f4d05e1d56bf21a5e54
+  data.tar.gz: 14801f95c8cd1a241d2b1522b05a1e7af307822cef50e4515502f641027ade16aaf750a099801a2f2e4e379b15a4cd96e78f84754278db37d2e6fcdaab57b242

data/CHANGELOG.md

@@ -1,10 +1,120 @@
 # HEAD
 
-## Breaking
+## Features
+
+## Improvements
+
+## Fixes
+
+
+---
+
+
+
+# 3.6.0 / 2020-07-13
+
+
+## Features
+
+* [#458](https://github.com/Dynamoid/dynamoid/pull/458) Added `binary` field type
+* [#459](https://github.com/Dynamoid/dynamoid/pull/459) Added `log_formatter` config option and changed default logging format
+
+## Improvements
+
+* [#423](https://github.com/Dynamoid/dynamoid/pull/423) Added warning when generated for a field methods override existing ones
+* [#429](https://github.com/Dynamoid/dynamoid/pull/429) Added `raise_error` option for `find` method
+* [#440](https://github.com/Dynamoid/dynamoid/pull/440) Optimized performance of `first` method when there are only conditions on key attribute in a query (@mrkamel)
+* [#445](https://github.com/Dynamoid/dynamoid/pull/445) Support `limit` parameter in `first` method (@mrkamel)
+* [#450](https://github.com/Dynamoid/dynamoid/pull/450) Got rid of `null-logger` gem to make Dynamoid dependencies license suitable for commercial use (@yakjuly)
+* [#454](https://github.com/Dynamoid/dynamoid/pull/454) Added block argument to `create`/`create!` methods
+* [#456](https://github.com/Dynamoid/dynamoid/pull/456) Detect when `find` method requires a range key argument and raise `Dynamoid::Errors::MissingRangeKey` exception if it's missing
+* YARD documentation:
+  * added missing documentation so now all the public methods are documented
+  * hid all the private methods and classes
+
+## Fixes
+
+* [#425](https://github.com/Dynamoid/dynamoid/pull/425) Fixed typos in the README.md file (@omarsotillo)
+* [#432](https://github.com/Dynamoid/dynamoid/pull/432) Support tables that use "hash_key" as their partition key name (@remomueller)
+* [#434](https://github.com/Dynamoid/dynamoid/pull/434) Support tables that have attribute with name "range_value"
+* [#453](https://github.com/Dynamoid/dynamoid/pull/453) Fixed issue with using `type` attribute as a GSI hash key
+
+---
+
+
+
+# 3.5.0 / 2020-04-04
+
+
+## Features
+* Feature: [#405](https://github.com/Dynamoid/dynamoid/pull/405) Added `update!` class method (@UrsaDK)
+* Feature: [#408](https://github.com/Dynamoid/dynamoid/pull/408) Added `ActiveSupport` load hook on `Dynamoid` load (@aaronmallen)
+* Feature: [#422](https://github.com/Dynamoid/dynamoid/pull/422) Added `.pluck` method
+
+## Fixes:
+* Fix: [#410](https://github.com/Dynamoid/dynamoid/pull/410) Fixed creating GSI when table uses on-demand capacity provisioning (@icy-arctic-fox)
+* Fix: [#414](https://github.com/Dynamoid/dynamoid/pull/414) Fixed lazy table creation
+* Fix: [#415](https://github.com/Dynamoid/dynamoid/pull/415) Fixed RubyDoc comment (@walkersumida)
+* Fix: [#420](https://github.com/Dynamoid/dynamoid/pull/420) Fixed `#persisted?` for deleted/destroyed models
+
+## Improvements:
+* Improvement: [#416](https://github.com/Dynamoid/dynamoid/pull/416) Improved speed of Adapter's `truncate` method. It now uses `#batch_delete_item` method (@TheSmartnik)
+* Improvement: [#421](https://github.com/Dynamoid/dynamoid/pull/421) Added `touch: false` option of the #save method
+* Improvement: [#423](https://github.com/Dynamoid/dynamoid/pull/423) Added warning when generated for a field methods override existing ones
+
+---
+
+
+
+# 3.4.1
+
+## Fixes
+* Fix: [#398](https://github.com/Dynamoid/dynamoid/pull/398) Fix broken configuration
+
+---
+
+
+
+# 3.4.0
+
+## Features
+* Feature: [#386](https://github.com/Dynamoid/dynamoid/pull/386) Disable timestamps fields on a table level with new
+  table option `timestamps`
+* Feature: [#387](https://github.com/Dynamoid/dynamoid/pull/387) Add TTL support with table option `expires`
+* Feature: [#393](https://github.com/Dynamoid/dynamoid/pull/393) Support pre-configured credentials with new config
+  option `credentials` (@emmajhyde)
+* Feature: [#397](https://github.com/Dynamoid/dynamoid/pull/397) Configure on-demand table capacity mode with `capacity_mode` option
 
 ## Improvements
+* Improvement: [#388](https://github.com/Dynamoid/dynamoid/pull/388) Minor memory optimization - don't allocate excessive
+  hash (@arjes)
+
+## Fixes
+
+* Fix: [#382](https://github.com/Dynamoid/dynamoid/pull/382) Fixed deprecation warning about `Module#parent_name` in Rails 6 (@tmandke)
+* Fix: Typos in Readme.md (@romeuhcf)
+
+---
+
+
+
+# 3.3.0
+
+## Features
+
+* Feature: [#374](https://github.com/Dynamoid/dynamoid/pull/374) Add `#project` query method to load only specified fields
+
+## Improvements
+
+* Improvement: [#359](https://github.com/Dynamoid/dynamoid/pull/359) Add support of `NULL` and `NOT_NULL` operators
+* Improvement: [#360](https://github.com/Dynamoid/dynamoid/pull/360) Add `store_attribute_with_nil_value` config option
+* Improvement: [#368](https://github.com/Dynamoid/dynamoid/pull/368) Support Rails 6 (RC1)
 
 ## Fixes
+* Fix: [#357](https://github.com/Dynamoid/dynamoid/pull/357) Fix synchronous table creation issue
+* Fix: [#362](https://github.com/Dynamoid/dynamoid/pull/362) Fix issue with selecting Global Secondary Index (@atyndall)
+* Fix: [#368](https://github.com/Dynamoid/dynamoid/pull/368) Repair `#previous_changes` method from Dirty API
+* Fix: [#373](https://github.com/Dynamoid/dynamoid/pull/373) Fix threadsafety of loading `Dynamoid::Adapter` (@tsub)
 
 ---
 

data/README.md

@@ -9,26 +9,36 @@
 ![GitHub](https://img.shields.io/github/license/Dynamoid/dynamoid.svg)
 
 Dynamoid is an ORM for Amazon's DynamoDB for Ruby applications. It
-provides similar functionality to ActiveRecord and improves on
-Amazon's existing
+provides similar functionality to ActiveRecord and improves on Amazon's
+existing
 [HashModel](http://docs.amazonwebservices.com/AWSRubySDK/latest/AWS/Record/HashModel.html)
 by providing better searching tools and native association support.
 
-DynamoDB is not like other document-based databases you might know, and is very different indeed from relational databases. It sacrifices anything beyond the simplest relational queries and transactional support to provide a fast, cost-efficient, and highly durable storage solution. If your database requires complicated relational queries and transaction support, then this modest Gem cannot provide them for you, and neither can DynamoDB. In those cases you would do better to look elsewhere for your database needs.
+DynamoDB is not like other document-based databases you might know, and
+is very different indeed from relational databases. It sacrifices
+anything beyond the simplest relational queries and transactional
+support to provide a fast, cost-efficient, and highly durable storage
+solution. If your database requires complicated relational queries and
+transaction support, then this modest Gem cannot provide them for you,
+and neither can DynamoDB. In those cases you would do better to look
+elsewhere for your database needs.
 
-But if you want a fast, scalable, simple, easy-to-use database (and a Gem that supports it) then look no further!
+But if you want a fast, scalable, simple, easy-to-use database (and a
+Gem that supports it) then look no further!
 
 ## Installation
 
-Installing Dynamoid is pretty simple. First include the Gem in your Gemfile:
+Installing Dynamoid is pretty simple. First include the Gem in your
+Gemfile:
 
 ```ruby
 gem 'dynamoid'
 ```
-## Prerequisities
+## Prerequisites
 
-Dynamoid depends on the aws-sdk, and this is tested on the current version of aws-sdk (~> 3), rails (>= 4).
-Hence the configuration as needed for aws to work will be dealt with by aws setup.
+Dynamoid depends on the aws-sdk, and this is tested on the current
+version of aws-sdk (~> 3), rails (>= 4). Hence the configuration as
+needed for aws to work will be dealt with by aws setup.
 
 ### AWS SDK Version Compatibility
 
@@ -51,45 +61,73 @@ For example, to configure AWS access:
 Create `config/initializers/aws.rb` as follows:
 
 ```ruby
+Aws.config.update({
+  region: 'us-west-2',
+  credentials: Aws::Credentials.new('REPLACE_WITH_ACCESS_KEY_ID', 'REPLACE_WITH_SECRET_ACCESS_KEY'),
+})
+```
 
-  Aws.config.update({
-    region: 'us-west-2',
-    credentials: Aws::Credentials.new('REPLACE_WITH_ACCESS_KEY_ID', 'REPLACE_WITH_SECRET_ACCESS_KEY'),
-  })
+Alternatively, if you don't want Aws connection settings to be
+overwritten for you entire project, you can specify connection settings
+for Dynamoid only, by setting those in the `Dynamoid.configure` clause:
 
+```ruby
+require 'dynamoid'
+Dynamoid.configure do |config|
+  config.access_key = 'REPLACE_WITH_ACCESS_KEY_ID'
+  config.secret_key = 'REPLACE_WITH_SECRET_ACCESS_KEY'
+  config.region = 'us-west-2'
+end
 ```
 
-Alternatively, if you don't want Aws connection settings to be overwritten for you entire project, you can specify connection settings for Dynamoid only, by setting those in the `Dynamoid.configure` clause:
+Additionally, if you would like to pass in pre-configured AWS credentials
+(e.g. you have an IAM role credential, you configure your credentials
+elsewhere in your project, etc.), you may do so:
 
 ```ruby
-  require 'dynamoid'
-  Dynamoid.configure do |config|
-    config.access_key = 'REPLACE_WITH_ACCESS_KEY_ID'
-    config.secret_key = 'REPLACE_WITH_SECRET_ACCESS_KEY'
-    config.region = 'us-west-2'
-  end
+require 'dynamoid'
+
+credentials = Aws::AssumeRoleCredentials.new(
+    region: region,
+    access_key_id: key,
+    secret_access_key: secret,
+    role_arn: role_arn,
+    role_session_name: 'our-session'
+  )
+
+Dynamoid.configure do |config|
+  config.region = 'us-west-2',
+  config.credentials = credentials
+end
 ```
 
 For a full list of the DDB regions, you can go
 [here](http://docs.aws.amazon.com/general/latest/gr/rande.html#ddb_region).
 
-Then you need to initialize Dynamoid config to get it going. Put code similar to this somewhere (a Rails initializer would be a great place for this if you're using Rails):
+Then you need to initialize Dynamoid config to get it going. Put code
+similar to this somewhere (a Rails initializer would be a great place
+for this if you're using Rails):
 
 ```ruby
-  require 'dynamoid'
-  Dynamoid.configure do |config|
-    config.namespace = 'dynamoid_app_development' # To namespace tables created by Dynamoid from other tables you might have. Set to nil to avoid namespacing.
-    config.endpoint = 'http://localhost:3000' # [Optional]. If provided, it communicates with the DB listening at the endpoint. This is useful for testing with [Amazon Local DB] (http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Tools.DynamoDBLocal.html).
-  end
+require 'dynamoid'
+Dynamoid.configure do |config|
+  # To namespace tables created by Dynamoid from other tables you might have.
+  # Set to nil to avoid namespacing.
+  config.namespace = 'dynamoid_app_development'
+
+  # [Optional]. If provided, it communicates with the DB listening at the endpoint.
+  # This is useful for testing with [DynamoDB Local] (http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Tools.DynamoDBLocal.html).
+  config.endpoint = 'http://localhost:3000'
+end
 ```
 
 ### Ruby & Rails Compatibility
 
 Dynamoid supports Ruby >= 2.3 and Rails >= 4.2.
 
-Its compatibility is tested against following Ruby versions: 2.3.8,
-2.4.5, 2.5.3 and 2.6.1, JRuby versions 9.1.17.0 and 9.2.6.0 and
- against Rails versions: 4.2.x, 5.0.x, 5.1.x and 5.2.x.
+Its compatibility is tested against following Ruby versions: 2.3, 2.4,
+2.5 and 2.6, JRuby 9.2.8.0 and against Rails versions: 4.2, 5.0, 5.1,
+5.2 and 6.0.
 
 ## Setup
 
@@ -99,12 +137,15 @@ You *must* include `Dynamoid::Document` in every Dynamoid model.
 class User
   include Dynamoid::Document
 
+  # fields declaration
 end
 ```
 
 ### Table
 
-Dynamoid has some sensible defaults for you when you create a new table, including the table name and the primary key column. But you can change those if you like on table creation.
+Dynamoid has some sensible defaults for you when you create a new table,
+including the table name and the primary key column. But you can change
+those if you like on table creation.
 
 ```ruby
 class User
@@ -114,29 +155,85 @@ class User
 end
 ```
 
-These fields will not change an existing table: so specifying a new read_capacity and write_capacity here only works correctly for entirely new tables. Similarly, while Dynamoid will look for a table named `awesome_users` in your namespace, it won't change any existing tables to use that name; and if it does find a table with the correct name, it won't change its hash key, which it expects will be `user_id`. If this table doesn't exist yet, however, Dynamoid will create it with these options.
+These fields will not change an existing table: so specifying a new
+read_capacity and write_capacity here only works correctly for entirely
+new tables. Similarly, while Dynamoid will look for a table named
+`awesome_users` in your namespace, it won't change any existing tables
+to use that name; and if it does find a table with the correct name, it
+won't change its hash key, which it expects will be `user_id`. If this
+table doesn't exist yet, however, Dynamoid will create it with these
+options.
 
-### Fields
+There is a basic support of DynamoDB's [Time To Live (TTL)
+mechanism](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/TTL.html).
+If you declare a field as TTL field - it will be initialised if doesn't
+have value yet. Default value is current time + specified seconds.
+
+```ruby
+class User
+  include Dynamoid::Document
+
+  table expires: { field: :ttl, after: 60 }
+
+  field :ttl, :integer
+end
+```
 
-You'll have to define all the fields on the model and the data type of each field. Every field on the object must be included here; if you miss any they'll be completely bypassed during DynamoDB's initialization and will not appear on the model objects.
+Field used to store expiration time (e.g. `ttl`) should be declared
+explicitly and should have numeric type (`integer`, `number`) only.
+`datetime` type is also possible but only if it's stored as number
+(there is a way to store time as a string also).
 
-By default, fields are assumed to be of type `:string`. Other built-in types are
-`:integer`, `:number`, `:set`, `:array`, `:map`, `:datetime`, `date`, `:boolean`, `:raw` and `:serialized`.
-`array` and `map` match List and Map DynamoDB types respectively.
-`raw` type means you can store Ruby Array, Hash, String and numbers.
-If built-in types do not suit you, you can use a custom field type represented by an arbitrary class, provided that the class supports a compatible serialization interface.
-The primary use case for using a custom field type is to represent your business logic with high-level types, while ensuring portability or backward-compatibility of the serialized representation.
+It's also possible to override a global option `Dynamoid::Config.timestamps`
+on a table level:
+
+```ruby
+table timestamps: false
+```
+
+This option controls generation of timestamp fields
+`created_at`/`updated_at`.
+
+It's also possible to override table capacity mode configured globally
+with table level option `capacity_mode`. Valid values are
+`:provisioned`, `:on_demand` and `nil`:
+
+```ruby
+table capacity_mode: :on_demand
+```
+
+If table capacity mode is on-demand, another related table-level options
+`read_capacity` and `write_capacity` will be ignored.
+
+### Fields
+
+You'll have to define all the fields on the model and the data type of
+each field. Every field on the object must be included here; if you miss
+any they'll be completely bypassed during DynamoDB's initialization and
+will not appear on the model objects.
+
+By default, fields are assumed to be of type `string`. Other built-in
+types are `integer`, `number`, `set`, `array`, `map`, `datetime`,
+`date`, `boolean`, `binary`, `raw` and `serialized`. `array` and
+`map` match List and Map DynamoDB types respectively. `raw` type means
+you can store Ruby Array, Hash, String and numbers. If built-in types do
+not suit you, you can use a custom field type represented by an
+arbitrary class, provided that the class supports a compatible
+serialization interface.  The primary use case for using a custom field
+type is to represent your business logic with high-level types, while
+ensuring portability or backward-compatibility of the serialized
+representation.
 
 #### Note on boolean type
 
 The boolean fields are stored as DynamoDB boolean values by default.
 Dynamoid can store boolean values as strings as well - `'t'` and `'f'`.
-So if you want to change default format of boolean field you can easily
-achieve this with `store_as_native_boolean` field option:
+So if you want to change the default format of boolean field you can
+easily achieve this with `store_as_native_boolean` field option:
 
 ```ruby
 class Document
-  include DynamoId::Document
+  include Dynamoid::Document
 
   field :active, :boolean, store_as_native_boolean: false
 end
@@ -144,11 +241,13 @@ end
 
 #### Note on date type
 
-By default date fields are persisted as days count since 1 January 1970 like UNIX time. If you prefer dates to be stored as ISO-8601 formatted strings instead then set `store_as_string` to `true`
+By default date fields are persisted as days count since 1 January 1970
+like UNIX time. If you prefer dates to be stored as ISO-8601 formatted
+strings instead then set `store_as_string` to `true`
 
 ```ruby
 class Document
-  include DynamoId::Document
+  include Dynamoid::Document
 
   field :sent_on, :date, store_as_string: true
 end
@@ -156,51 +255,58 @@ end
 
 #### Note on datetime type
 
-By default datetime fields are persisted as UNIX timestamps with millisecond precision in DynamoDB. If you prefer datetimes to be stored as ISO-8601 formatted strings instead then set `store_as_string` to `true`
+By default datetime fields are persisted as UNIX timestamps with
+millisecond precision in DynamoDB. If you prefer datetimes to be stored
+as ISO-8601 formatted strings instead then set `store_as_string` to
+`true`
 
 ```ruby
 class Document
-  include DynamoId::Document
+  include Dynamoid::Document
 
   field :sent_at, :datetime, store_as_string: true
 end
 ```
 
-**WARNING:** Fields in numeric format are stored with nanoseconds as a fraction part and precision could be lost.
-That's why `datetime` field in numeric format shouldn't be used as a range key.
+**WARNING:** Fields in numeric format are stored with nanoseconds as a
+fraction part and precision could be lost. That's why `datetime` field
+in numeric format shouldn't be used as a range key.
 
-You have two options if you need to use a `datetime` field as a range key:
+You have two options if you need to use a `datetime` field as a range
+key:
 * string format
-* store `datetime` values without milliseconds e.g. cut them
-  manually with `change` method - `Time.now.change(usec: 0)`
+* store `datetime` values without milliseconds (e.g. cut
+  them manually with `change` method - `Time.now.change(usec: 0)`
 
 #### Note on set type
 
 `Dynamoid`'s type `set` is stored as DynamoDB's Set attribute type.
-DynamoDB supports only Set of strings, numbers and binary.
-Moreover Set *must* contain elements of the same type only.
+DynamoDB supports only Set of strings, numbers and binary. Moreover Set
+*must* contain elements of the same type only.
 
-In order to use some other `Dynamoid`'s types you can specify `of` option
-to declare the type of set elements.
+In order to use some other `Dynamoid`'s types you can specify `of`
+option to declare the type of set elements.
 
 As a result of that DynamoDB limitation, in Dynamoid only the following
 scalar types are supported (note: does not support `boolean`):
-`integer`, `number`, `date`, `datetime`, `serializable` and custom types.
+`integer`, `number`, `date`, `datetime`, `serializable` and custom
+types.
 
 ```ruby
 class Document
-  include DynamoId::Document
+  include Dynamoid::Document
 
   field :tags, :set, of: :integer
 end
 ```
 
-It's possible to specify field options like `store_as_string` for `datetime` field
-or `serializer` for `serializable` field for `set` elements type:
+It's possible to specify field options like `store_as_string` for
+`datetime` field or `serializer` for `serializable` field for `set`
+elements type:
 
 ```ruby
 class Document
-  include DynamoId::Document
+  include Dynamoid::Document
 
   field :values, :set, of: { serialized: { serializer: JSON } }
   field :dates, :set, of: { date: { store_as_string: true } }
@@ -209,12 +315,14 @@ end
 ```
 
 DynamoDB doesn't allow empty strings in fields configured as `set`.
-Abiding by this restriction, when `Dynamoid` saves a document it removes all empty strings in set fields.
+Abiding by this restriction, when `Dynamoid` saves a document it removes
+all empty strings in set fields.
 
 #### Note on array type
 
 `Dynamoid`'s type `array` is stored as DynamoDB's List attribute type.
-It can contain elements of different types (in contrast to Set attribute type).
+It can contain elements of different types (in contrast to Set attribute
+type).
 
 If you need to store in array field elements of `datetime`, `date`,
 `serializable` or some custom type, which DynamoDB doesn't support
@@ -222,7 +330,7 @@ natively, you should specify element type with `of` option:
 
 ```ruby
 class Document
-  include DynamoId::Document
+  include Dynamoid::Document
 
   field :dates, :array, of: :date
 end
@@ -230,7 +338,8 @@ end
 
 #### Magic Columns
 
-You get magic columns of `id` (`string`), `created_at` (`datetime`), and `updated_at` (`datetime`) for free.
+You get magic columns of `id` (`string`), `created_at` (`datetime`), and
+`updated_at` (`datetime`) for free.
 
 ```ruby
 class User
@@ -248,11 +357,12 @@ end
 
 #### Default Values
 
-You can optionally set a default value on a field using either a plain value or a lambda:
+You can optionally set a default value on a field using either a plain
+value or a lambda:
 
 ```ruby
-  field :actions_taken, :integer, default: 0
-  field :joined_at, :datetime, default: -> { Time.now }
+field :actions_taken, :integer, default: 0
+field :joined_at, :datetime, default: -> { Time.now }
 ```
 
 #### Custom Types
@@ -260,64 +370,68 @@ You can optionally set a default value on a field using either a plain value or
 To use a custom type for a field, suppose you have a `Money` type.
 
 ```ruby
-  class Money
-    # ... your business logic ...
+class Money
+  # ... your business logic ...
 
-    def dynamoid_dump
-      'serialized representation as a string'
-    end
+  def dynamoid_dump
+    'serialized representation as a string'
+  end
 
-    def self.dynamoid_load(serialized_str)
-      # parse serialized representation and return a Money instance
-      Money.new(1.23)
-    end
+  def self.dynamoid_load(serialized_str)
+    # parse serialized representation and return a Money instance
+    Money.new(1.23)
   end
+end
 
-  class User
-    include Dynamoid::Document
+class User
+  include Dynamoid::Document
 
-    field :balance, Money
-  end
+  field :balance, Money
+end
 ```
 
-If you want to use a third-party class (which does not support `#dynamoid_dump` and `.dynamoid_load`)
-as your field type, you can use an adapter class providing `.dynamoid_dump` and `.dynamoid_load` class methods
-for your third-party class.  (`.dynamoid_load` can remain the same from the previous example; here we just
-add a level of indirection for serializing.)  Example:
+If you want to use a third-party class (which does not support
+`#dynamoid_dump` and `.dynamoid_load`) as your field type, you can use
+an adapter class providing `.dynamoid_dump` and `.dynamoid_load` class
+methods for your third-party class. `.dynamoid_load` can remain the same
+from the previous example; here we just add a level of indirection for
+serializing. Example:
 
 ```ruby
-  # Third-party Money class
-  class Money; end
+# Third-party Money class
+class Money; end
 
-  class MoneyAdapter
-    def self.dynamoid_load(money_serialized_str)
-      Money.new(1.23)
-    end
+class MoneyAdapter
+  def self.dynamoid_load(money_serialized_str)
+    Money.new(1.23)
+  end
 
-    def self.dynamoid_dump(money_obj)
-      money_obj.value.to_s
-    end
+  def self.dynamoid_dump(money_obj)
+    money_obj.value.to_s
   end
+end
 
-  class User
-    include Dynamoid::Document
+class User
+  include Dynamoid::Document
 
-    field :balance, MoneyAdapter
-  end
+  field :balance, MoneyAdapter
+end
 ```
 
-Lastly, you can control the data type of your custom-class-backed field at the DynamoDB level.
-This is especially important if you want to use your custom field as a numeric range or for
-number-oriented queries. By default custom fields are persisted as a string attribute, but
-your custom class can override this with a `.dynamoid_field_type` class method, which would
-return either `:string` or `:number`.
+Lastly, you can control the data type of your custom-class-backed field
+at the DynamoDB level. This is especially important if you want to use
+your custom field as a numeric range or for number-oriented queries. By
+default custom fields are persisted as a string attribute, but your
+custom class can override this with a `.dynamoid_field_type` class
+method, which would return either `:string` or `:number`.
 
-DynamoDB may support some other attribute types that are not yet supported by Dynamoid.
+DynamoDB may support some other attribute types that are not yet
+supported by Dynamoid.
 
 ### Sort key
 
-Along with partition key table may have a sort key. In order to declare it in a model
-`range` class method should be used:
+Along with partition key table may have a sort key. In order to declare
+it in a model `range` class method should be used:
 
 ```ruby
 class Post
@@ -331,9 +445,15 @@ Second argument, type, is optional. Default type is `string`.
 
 ### Associations
 
-Just like in ActiveRecord (or your other favorite ORM), Dynamoid uses associations to create links between models.
+Just like in ActiveRecord (or your other favorite ORM), Dynamoid uses
+associations to create links between models.
 
-The only supported associations (so far) are `has_many`, `has_one`, `has_and_belongs_to_many`, and `belongs_to`. Associations are very simple to create: just specify the type, the name, and then any options you'd like to pass to the association. If there's an inverse association either inferred or specified directly, Dynamoid will update both objects to point at each other.
+The only supported associations (so far) are `has_many`, `has_one`,
+`has_and_belongs_to_many`, and `belongs_to`. Associations are very
+simple to create: just specify the type, the name, and then any options
+you'd like to pass to the association. If there's an inverse association
+either inferred or specified directly, Dynamoid will update both objects
+to point at each other.
 
 ```ruby
 class User
@@ -348,7 +468,6 @@ class User
   belongs_to :group, foreign_key: :group_id
   has_one :role
   has_and_belongs_to_many :friends, inverse_of: :friending_users
-
 end
 
 class Address
@@ -357,11 +476,18 @@ class Address
   # ...
 
   belongs_to :user # Automatically links up with the user model
-
 end
 ```
 
-Contrary to what you'd expect, association information is always contained on the object specifying the association, even if it seems like the association has a foreign key. This is a side effect of DynamoDB's structure: it's very difficult to find foreign keys without an index. Usually you won't find this to be a problem, but it does mean that association methods that build new models will not work correctly -- for example, `user.addresses.new` returns an address that is not associated to the user. We'll be correcting this ~soon~ maybe someday, if we get a pull request.
+Contrary to what you'd expect, association information is always
+contained on the object specifying the association, even if it seems
+like the association has a foreign key. This is a side effect of
+DynamoDB's structure: it's very difficult to find foreign keys without
+an index. Usually you won't find this to be a problem, but it does mean
+that association methods that build new models will not work correctly -
+for example, `user.addresses.new` returns an address that is not
+associated to the user. We'll be correcting this ~soon~ maybe someday,
+if we get a pull request.
 
 ### Validations
 
@@ -378,9 +504,12 @@ class User
 end
 ```
 
-To see more usage and examples of ActiveModel validations, check out the [ActiveModel validation documentation](http://api.rubyonrails.org/classes/ActiveModel/Validations.html).
+To see more usage and examples of ActiveModel validations, check out the
+[ActiveModel validation
+documentation](http://api.rubyonrails.org/classes/ActiveModel/Validations.html).
 
-If you want to bypass model validation, pass `validate: false` to `save` call:
+If you want to bypass model validation, pass `validate: false` to `save`
+call:
 
 ```ruby
 model.save(validate: false)
@@ -388,7 +517,9 @@ model.save(validate: false)
 
 ### Callbacks
 
-Dynamoid also employs ActiveModel callbacks. Right now, callbacks are defined on ```save```, ```update```, ```destroy```, which allows you to do ```before_``` or ```after_``` any of those.
+Dynamoid also employs ActiveModel callbacks. Right now, callbacks are
+defined on `save`, `update`, `destroy`, which allows you to do `before_`
+or `after_` any of those.
 
 ```ruby
 class User
@@ -404,7 +535,8 @@ end
 
 ### STI
 
-Dynamoid supports STI (Single Table Inheritance) like Active Record does. You need just specify `type` field in a base class. Example:
+Dynamoid supports STI (Single Table Inheritance) like Active Record
+does. You need just specify `type` field in a base class. Example:
 
 ```ruby
 class Animal
@@ -421,12 +553,13 @@ end
 cat = Cat.create(name: 'Morgan')
 animal = Animal.find(cat.id)
 animal.class
-#=>  Cat
+#=> Cat
 ```
 
-If you already have DynamoDB tables and `type` field already exists and has its own semantic it leads to conflict.
-It's possible to tell Dynamoid to use another field (even not existing)
-instead of `type` one with `inheritance_field` table option:
+If you already have DynamoDB tables and `type` field already exists and
+has its own semantic it leads to conflict. It's possible to tell
+Dynamoid to use another field (even not existing) instead of `type` one
+with `inheritance_field` table option:
 
 ```ruby
 class Car
@@ -443,8 +576,9 @@ c.my_new_type
 
 ### Type casting
 
-Dynamid supports type casting and tryes to do it in the most convinient way.
-Values for all fields (except custom type) are coerced to declared field types.
+Dynamid supports type casting and tries to do it in the most convenient
+way. Values for all fields (except custom type) are coerced to declared
+field types.
 
 Some obvious rules are used, e.g.:
 
@@ -468,18 +602,29 @@ document.integer_field = true
 # => 1
 ```
 
-If time zone isn't specified for `datetime` value - application time zone is used.
+If time zone isn't specified for `datetime` value - application time
+zone is used.
 
 To access field value before type casting following method could be
-used: `attributes_before_type_cast` and `read_attribute_before_type_cast`.
+used: `attributes_before_type_cast` and
+`read_attribute_before_type_cast`.
 
-There is `<name>_before_type_cast` method for every field in a model as well.
+There is `<name>_before_type_cast` method for every field in a model as
+well.
+
+### Dirty API
+
+Dynamoid supports Dirty API which equivalents to [Rails 5.2
+`ActiveModel::Dirty`](https://api.rubyonrails.org/v5.2/classes/ActiveModel/Dirty.html).
+There is only one limitation - change in place of field isn't detected
+automatically.
 
 ## Usage
 
 ### Object Creation
 
-Dynamoid's syntax is generally very similar to ActiveRecord's. Making new objects is simple:
+Dynamoid's syntax is generally very similar to ActiveRecord's. Making
+new objects is simple:
 
 ```ruby
 u = User.new(name: 'Josh')
@@ -487,13 +632,15 @@ u.email = 'josh@joshsymonds.com'
 u.save
 ```
 
-Save forces persistence to the datastore: a unique ID is also assigned, but it is a string and not an auto-incrementing number.
+Save forces persistence to the datastore: a unique ID is also assigned,
+but it is a string and not an auto-incrementing number.
 
 ```ruby
 u.id # => '3a9f7216-4726-4aea-9fbc-8554ae9292cb'
 ```
 
-To use associations, you use association methods very similar to ActiveRecord's:
+To use associations, you use association methods very similar to
+ActiveRecord's:
 
 ```ruby
 address = u.addresses.create
@@ -520,7 +667,8 @@ Querying can be done in one of three ways:
 
 ```ruby
 Address.find(address.id)              # Find directly by ID.
-Address.where(city: 'Chicago').all    # Find by any number of matching criteria... though presently only "where" is supported.
+Address.where(city: 'Chicago').all    # Find by any number of matching criteria...
+                                      # Though presently only "where" is supported.
 Address.find_by_city('Chicago')       # The same as above, but using ActiveRecord's older syntax.
 ```
 
@@ -530,11 +678,16 @@ And you can also query on associations:
 u.addresses.where(city: 'Chicago').all
 ```
 
-But keep in mind Dynamoid -- and document-based storage systems in general -- are not drop-in replacements for existing relational databases. The above query does not efficiently perform a conditional join, but instead finds all the user's addresses and naively filters them in Ruby. For large associations this is a performance hit compared to relational database engines.
+But keep in mind Dynamoid - and document-based storage systems in
+general - are not drop-in replacements for existing relational
+databases. The above query does not efficiently perform a conditional
+join, but instead finds all the user's addresses and naively filters
+them in Ruby. For large associations this is a performance hit compared
+to relational database engines.
 
 **WARNING:** There is a limitation of conditions passed to `where`
 method. Only one condition for some particular field could be specified.
-The last one only will be applyed and others will be ignored. E.g. in
+The last one only will be applied and others will be ignored. E.g. in
 examples:
 
 ```ruby
@@ -544,64 +697,102 @@ User.where(name: 'Mike').where('name.begins_with': 'Ed')
 
 the first one will be ignored and the last one will be used.
 
+**Warning:** There is a caveat with filtering documents by `nil` value
+attribute. By default Dynamoid ignores attributes with `nil` value and
+doesn't store them in a DynamoDB document. This behavior could be
+changed with `store_attribute_with_nil_value` config option.
+
+If Dynamoid ignores `nil` value attributes `null`/`not_null` operators
+should be used in query:
+
+```ruby
+Address.where('postcode.null': true)
+Address.where('postcode.not_null': true)
+```
+
+If Dynamoid keeps `nil` value attributes `eq`/`ne` operators should be
+used instead:
+
+```ruby
+Address.where('postcode': nil)
+Address.where('postcode.ne': nil)
+```
+
 #### Limits
 
 There are three types of limits that you can query with:
 
-1. `record_limit` - The number of evaluated records that are returned by the query.
-2. `scan_limit` - The number of scanned records that DynamoDB will look at before returning.
-3. `batch_size` - The number of records requested to DynamoDB per underlying request, good for large queries!
+1. `record_limit` - The number of evaluated records that are returned by
+   the query.
+2. `scan_limit` - The number of scanned records that DynamoDB will look
+   at before returning.
+3. `batch_size` - The number of records requested to DynamoDB per
+   underlying request, good for large queries!
 
-Using these in various combinations results in the underlying requests to be made in the smallest size possible and
-the query returns once `record_limit` or `scan_limit` is satisfied. It will attempt to batch whenever possible.
+Using these in various combinations results in the underlying requests
+to be made in the smallest size possible and the query returns once
+`record_limit` or `scan_limit` is satisfied. It will attempt to batch
+whenever possible.
 
-You can thus limit the number of evaluated records, or select a record from which to start in order to support pagination.
+You can thus limit the number of evaluated records, or select a record
+from which to start in order to support pagination.
 
 ```ruby
 Address.record_limit(5).start(address) # Only 5 addresses starting at `address`
 ```
-Where `address` is an instance of the model or a hash `{the_model_hash_key: 'value', the_model_range_key: 'value'}`:
-Keep in mind that if you are passing a hash to `.start()` you need to explicitly define all required keys in it including range keys, depending on table or secondary indexes signatures, otherwise you'll get an `Aws::DynamoDB::Errors::ValidationException` either for `Exclusive Start Key must have same size as table's key schema` or `The provided starting key is invalid`
-
-If you are potentially running over a large data set and this is especially true when using certain filters, you may
-want to consider limiting the number of scanned records (the number of records DynamoDB infrastructure looks through
-when evaluating data to return):
+Where `address` is an instance of the model or a hash
+`{the_model_hash_key: 'value', the_model_range_key: 'value'}`. Keep in
+mind that if you are passing a hash to `.start()` you need to explicitly
+define all required keys in it including range keys, depending on table
+or secondary indexes signatures, otherwise you'll get an
+`Aws::DynamoDB::Errors::ValidationException` either for `Exclusive Start
+Key must have same size as table's key schema` or `The provided starting
+key is invalid`
+
+If you are potentially running over a large data set and this is
+especially true when using certain filters, you may want to consider
+limiting the number of scanned records (the number of records DynamoDB
+infrastructure looks through when evaluating data to return):
 
 ```ruby
 Address.scan_limit(5).start(address) # Only scan at most 5 records and return what's found starting from `address`
 ```
 
-For large queries that return many rows, Dynamoid can use AWS' support for requesting documents in batches:
+For large queries that return many rows, Dynamoid can use AWS' support
+for requesting documents in batches:
 
 ```ruby
 # Do some maintenance on the entire table without flooding DynamoDB
-Address.all(batch_size: 100).each { |address| address.do_some_work; sleep(0.01) }
+Address.batch(100).each { |address| address.do_some_work; sleep(0.01) }
 Address.record_limit(10_000).batch(100).each { … } # Batch specified as part of a chain
 ```
 
-The implication of batches is that the underlying requests are done in the batch sizes to make the request and responses
-more manageable. Note that this batching is for `Query` and `Scans` and not `BatchGetItem` commands.
+The implication of batches is that the underlying requests are done in
+the batch sizes to make the request and responses more manageable. Note
+that this batching is for `Query` and `Scans` and not `BatchGetItem`
+commands.
 
 #### DynamoDB pagination
 
-At times it can be useful to rely on DynamoDB [low-level pagination](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Query.html#Query.Pagination)
-instead of fixed pages sizes. Each page results in a single Query or Scan call
-to DyanmoDB, but returns an unknown number of records.
+At times it can be useful to rely on DynamoDB [low-level
+pagination](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Query.html#Query.Pagination)
+instead of fixed pages sizes. Each page results in a single Query or
+Scan call to DynamoDB, but returns an unknown number of records.
 
-Access to the native DynamoDB pages can be obtained via the `find_by_pages`
-method, which yields arrays of records.
+Access to the native DynamoDB pages can be obtained via the
+`find_by_pages` method, which yields arrays of records.
 
 ```ruby
 Address.find_by_pages do |addresses, metadata|
 end
 ```
 
-Each yielded pages returns page metadata as the second argument, which is a hash
-including a key `:last_evaluated_key`. The value of this key can be used for
-the `start` method to fetch the next page of records.
+Each yielded pages returns page metadata as the second argument, which
+is a hash including a key `:last_evaluated_key`. The value of this key
+can be used for the `start` method to fetch the next page of records.
 
-This way it can be used for instance to implement efficiently
-pagination in web-application:
+This way it can be used for instance to implement efficiently pagination
+in web-applications:
 
 ```ruby
 class UserController < ApplicationController
@@ -620,8 +811,9 @@ end
 
 #### Sort Conditions and Filters
 
-You are able to optimize query with condition for sort key. Following operators are available: `gt`, `lt`, `gte`, `lte`,
-`begins_with`, `between` as well as equality:
+You are able to optimize query with condition for sort key. Following
+operators are available: `gt`, `lt`, `gte`, `lte`, `begins_with`,
+`between` as well as equality:
 
 ```ruby
 Address.where(latitude: 10212)
@@ -633,18 +825,57 @@ Address.where('city.begins_with': 'Lon')
 Address.where('latitude.between': [10212, 20000])
 ```
 
-You are able to filter results on the DynamoDB side and specify conditions for non-key fields.
-Following operators are available: `in`, `contains`, `not_contains`:
+You are able to filter results on the DynamoDB side and specify
+conditions for non-key fields. Following additional operators are
+available: `in`, `contains`, `not_contains`, `null`, `not_null`:
 
 ```ruby
 Address.where('city.in': ['London', 'Edenburg', 'Birmingham'])
 Address.where('city.contains': ['on'])
 Address.where('city.not_contains': ['ing'])
+Address.where('postcode.null': false)
+Address.where('postcode.not_null': true)
+```
+
+**WARNING:** Please take into account that `NULL` and `NOT_NULL`
+operators check attribute presence in a document, not value. So if
+attribute `postcode`'s value is `NULL`, `NULL` operator will return
+false because attribute exists even if has `NULL` value.
+
+#### Selecting some specific fields only
+
+It could be done with `project` method:
+
+```ruby
+class User
+  include Dynamoid::Document
+  field :name
+end
+
+User.create(name: 'Alex')
+user = User.project(:name).first
+
+user.id         # => nil
+user.name       # => 'Alex'
+user.created_at # => nil
+```
+
+Returned models with have filled specified fields only.
+
+Several fields could be specified:
+
+```ruby
+user = User.project(:name, :created_at)
 ```
 
 ### Consistent Reads
 
-Querying supports consistent reading. By default, DynamoDB reads are eventually consistent: if you do a write and then a read immediately afterwards, the results of the previous write may not be reflected. If you need to do a consistent read (that is, you need to read the results of a write immediately) you can do so, but keep in mind that consistent reads are twice as expensive as regular reads for DynamoDB.
+Querying supports consistent reading. By default, DynamoDB reads are
+eventually consistent: if you do a write and then a read immediately
+afterwards, the results of the previous write may not be reflected. If
+you need to do a consistent read (that is, you need to read the results
+of a write immediately) you can do so, but keep in mind that consistent
+reads are twice as expensive as regular reads for DynamoDB.
 
 ```ruby
 Address.find(address.id, consistent_read: true)  # Find an address, ensure the read is consistent.
@@ -653,21 +884,25 @@ Address.where(city: 'Chicago').consistent.all    # Find all addresses where the
 
 ### Range Finding
 
-If you have a range index, Dynamoid provides a number of additional other convenience methods to make your life a little easier:
+If you have a range index, Dynamoid provides a number of additional
+other convenience methods to make your life a little easier:
 
 ```ruby
 User.where("created_at.gt": DateTime.now - 1.day).all
 User.where("created_at.lt": DateTime.now - 1.day).all
 ```
 
-It also supports `gte` and `lte`. Turning those into symbols and allowing a Rails SQL-style string syntax is in the works. You can only have one range argument per query, because of DynamoDB's inherent limitations, so use it sensibly!
+It also supports `gte` and `lte`. Turning those into symbols and
+allowing a Rails SQL-style string syntax is in the works. You can only
+have one range argument per query, because of DynamoDB inherent
+limitations, so use it sensibly!
 
 
 ### Updating
 
 In order to update document you can use high level methods
-`#update_attributes`, `#update_attribute` and `.update`.
-They run validation and collbacks.
+`#update_attributes`, `#update_attribute` and `.update`. They run
+validation and callbacks.
 
 ```ruby
 Address.find(id).update_attributes(city: 'Chicago')
@@ -677,18 +912,18 @@ Address.update(id, { city: 'Chicago' }, if: { deliverable: true })
 ```
 
 There are also some low level methods `#update`, `.update_fields` and
-`.upsert`. They don't run validation and callbacks (except `#update` - it
-runs `update` callbacks). All of them support conditional updates.
+`.upsert`. They don't run validation and callbacks (except `#update` -
+it runs `update` callbacks). All of them support conditional updates.
 `#upsert` will create new document if document with specified `id`
 doesn't exist.
 
 ```ruby
-Adderess.find(id).update do |i|
+Address.find(id).update do |i|
   i.set city: 'Chicago'
   i.add latitude: 100
   i.delete set_of_numbers: 10
 end
-Adderess.find(id).update(if: { deliverable: true }) do |i|
+Address.find(id).update(if: { deliverable: true }) do |i|
   i.set city: 'Chicago'
 end
 Address.update_fields(id, city: 'Chicago')
@@ -699,8 +934,8 @@ Address.upsert(id, { city: 'Chicago' }, if: { deliverable: true })
 
 ### Deleting
 
-In order to delete some items `delete_all` method should be used.
-Any callback wont be called. Items delete in efficient way in batch.
+In order to delete some items `delete_all` method should be used. Any
+callback won't be called. Items delete in efficient way in batch.
 
 ```ruby
 Address.where(city: 'London').delete_all
@@ -721,17 +956,24 @@ class User
 end
 ```
 
-There are following options:
+There are the following options:
 * `hash_key` - is used as hash key of an index,
 * `range_key` - is used as range key of an index,
-* `projected_attributes` - list of fields to store in an index or has a predefiled value `:keys_only`, `:all`; `:keys_only` is a default,
-* `name` - an index will be created with this name when a table is created; by default name is generated and contains table name and keys names,
-* `read_capacity` - is used when table creates and used as an index capacity; by default equals `Dynamoid::Config.read_capacity`,
-* `write_capacity` - is used when table creates and used as an index capacity; by default equals `Dynamoid::Config.write_capacity`
+* `projected_attributes` - list of fields to store in an index or has a
+  predefined value `:keys_only`, `:all`; `:keys_only` is a default,
+* `name` - an index will be created with this name when a table is
+  created; by default name is generated and contains table name and keys
+  names,
+* `read_capacity` - is used when table created and used as an index
+  capacity; by default equals `Dynamoid::Config.read_capacity`,
+* `write_capacity` - is used when table created and used as an index
+  capacity; by default equals `Dynamoid::Config.write_capacity`
 
 The only mandatory option is `name`.
 
-**WARNING:** In order to use global secondary index in `Document.where` implicitly you need to have all the attributes of the original table in the index and declare it with option `projected_attributes: :all`:
+**WARNING:** In order to use global secondary index in `Document.where`
+implicitly you need to have all the attributes of the original table in
+the index and declare it with option `projected_attributes: :all`:
 
 ```ruby
 class User
@@ -741,13 +983,16 @@ class User
 end
 ```
 
-There is only one implicit way to query Global and Local Secondary Indexes (GSI/LSI).
+There is only one implicit way to query Global and Local Secondary
+Indexes (GSI/LSI).
 
 #### Implicit
 
-The second way implicitly uses your GSI through the `where` clauses and deduces the index based on the query fields
-provided. Another added benefit is that it is built into query chaining so you can use all the methods used in normal
-querying. The explicit way from above would be rewritten as follows:
+The second way implicitly uses your GSI through the `where` clauses and
+deduces the index based on the query fields provided. Another added
+benefit is that it is built into query chaining so you can use all the
+methods used in normal querying. The explicit way from above would be
+rewritten as follows:
 
 ```ruby
 where(dynamo_primary_key_column_name => dynamo_primary_key_value,
@@ -755,57 +1000,118 @@ where(dynamo_primary_key_column_name => dynamo_primary_key_value,
   .scan_index_forward(false)
 ```
 
-The only caveat with this method is that because it is also used for general querying, it WILL NOT use a GSI unless it
-explicitly has defined `projected_attributes: :all` on the GSI in your model. This is because GSIs that do not have all
-attributes projected will only contain the index keys and therefore will not return objects with fully resolved field
-values. It currently opts to provide the complete results rather than partial results unless you've explicitly looked up
-the data.
+The only caveat with this method is that because it is also used for
+general querying, it WILL NOT use a GSI unless it explicitly has defined
+`projected_attributes: :all` on the GSI in your model. This is because
+GSIs that do not have all attributes projected will only contain the
+index keys and therefore will not return objects with fully resolved
+field values. It currently opts to provide the complete results rather
+than partial results unless you've explicitly looked up the data.
 
-*Future TODO could involve implementing `select` in chaining as well as resolving the fields with a second query against
-the table since a query against GSI then a query on base table is still likely faster than scan on the base table*
+*Future TODO could involve implementing `select` in chaining as well as
+resolving the fields with a second query against the table since a query
+against GSI then a query on base table is still likely faster than scan
+on the base table*
 
 ## Configuration
 
 Listed below are all configuration options.
 
-* `adapter` - usefull only for the gem developers to switch to a new adapter. Default and the only available value is `aws_sdk_v3`
-* `namespace` - prefix for table names, default is `dynamoid_#{application_name}_#{environment}` for Rails application and `dynamoid` otherwise
-* `logger` - by default it's a `Rails.logger` in Rails application and `stdout` otherwise. You can disable logging by setting `nil` or `false` values. Set `true` value to use defaults
-* `access_key` - DynamoDb custom credentials for AWS, override global AWS credentials if they present
-* `secret_key` - DynamoDb custom credentials for AWS, override global AWS credentials if they present
-* `region` - DynamoDb custom credentials for AWS, override global AWS credentials if they present
-* `batch_size` - when you try to load multiple items at once with `batch_get_item` call Dynamoid loads them not with one api call but piece by piece. Default is 100 items
-* `read_capacity` - is used at table or indices creation. Default is 100 (units)
-* `write_capacity` - is used at table or indices creation. Default is 20 (units)
+* `adapter` - useful only for the gem developers to switch to a new
+  adapter. Default and the only available value is `aws_sdk_v3`
+* `namespace` - prefix for table names, default is
+  `dynamoid_#{application_name}_#{environment}` for Rails application
+  and `dynamoid` otherwise
+* `logger` - by default it's a `Rails.logger` in Rails application and
+  `stdout` otherwise. You can disable logging by setting `nil` or
+  `false` values. Set `true` value to use defaults
+* `access_key` - DynamoDb custom access key for AWS credentials, override global
+  AWS credentials if they're present
+* `secret_key` - DynamoDb custom secret key for AWS credentials, override global
+  AWS credentials if they're present
+* `credentials` - DynamoDb custom pre-configured credentials, override global
+  AWS credentials if they're present
+* `region` - DynamoDb custom credentials for AWS, override global AWS
+  credentials if they're present
+* `batch_size` - when you try to load multiple items at once with
+* `batch_get_item` call Dynamoid loads them not with one api call but
+  piece by piece. Default is 100 items
+* `capacity_mode` - used at a table creation and means whether a table
+  read/write capacity mode will be on-demand or provisioned. Allowed
+  values are `:on_demand` and `:provisioned`. Default value is `nil` which
+  means provisioned mode will be used.
+* `read_capacity` - is used at table or indices creation. Default is 100
+  (units)
+* `write_capacity` - is used at table or indices creation. Default is 20
+  (units)
 * `warn_on_scan` - log warnings when scan table. Default is `true`
-* `endpoint` - if provided, it communicates with the DynamoDB listening at the endpoint. This is useful for testing with [Amazon Local DB]
-* `identity_map` - ensures that each object gets loaded only once by keeping every loaded object in a map. Looks up objects using the map when referring to them. Isn't thread safe. Default is `false`.
+* `endpoint` - if provided, it communicates with the DynamoDB listening
+  at the endpoint. This is useful for testing with
+  [DynamoDB Local](http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Tools.DynamoDBLocal.html)
+* `identity_map` - ensures that each object gets loaded only once by
+  keeping every loaded object in a map. Looks up objects using the map
+  when referring to them. Isn't thread safe. Default is `false`.
   `Use Dynamoid::Middleware::IdentityMap` to clear identity map for each HTTP request
-* `timestamps` - by default Dynamoid sets `created_at` and `updated_at` fields for model at creation and updating. You can disable this behavior by setting `false` value
-* `sync_retry_max_times` - when Dynamoid creates or deletes table synchronously it checks for completion specified times. Default is 60 (times). It's a bit over 2 minutes by default
-* `sync_retry_wait_seconds` - time to wait between retries. Default is 2 (seconds)
-* `convert_big_decimal` - if `true` then Dynamoid converts numbers stored in `Hash` in `raw` field to float. Default is `false`
-* `models_dir` - `dynamoid:create_tables` rake task loads DynamoDb models from this directory. Default is `./app/models`.
-* `application_timezone` - Dynamoid converts all `datetime` fields to specified time zone when loads data from the storage.
-  Acceptable values - `:utc`, `:local` (to use system time zone) and time zone name e.g. `Eastern Time (US & Canada)`. Default is `utc`
-* `dynamodb_timezone` - When a datetime field is stored in string format Dynamoid converts it to specified time zone when saves a value to the storage.
-  Acceptable values - `:utc`, `:local` (to use system time zone) and time zone name e.g. `Eastern Time (US & Canada)`. Default is `utc`
-* `store_datetime_as_string` - if `true` then Dynamoid stores :datetime fields in ISO 8601 string format. Default is `false`
-* `store_date_as_string` - if `true` then Dynamoid stores :date fields in ISO 8601 string format. Default is `false`
-* `store_boolean_as_native` - if `true` Dynamoid stores boolean fields as native DynamoDB
-  boolean values. Otherwise boolean fields are stored as string values
-`'t'` and `'f'`. Default is true
-* `backoff` - is a hash: key is a backoff strategy (symbol), value is parameters for the strategy. Is used in batch operations. Default id `nil`
-* `backoff_strategies`: is a hash and contains all available strategies. Default is { constant: ..., exponential: ...}
-* `http_continue_timeout`: The number of seconds to wait for a 100-continue HTTP response before sending the request body. Default option value is `nil`. If not specified effected value is `1`
-* `http_idle_timeout`: The number of seconds an HTTP connection is allowed to sit idble before it is considered stale. Default option value is `nil`. If not specified effected value is `5`
-* `http_open_timeout`: The number of seconds to wait when opening a HTTP session. Default option value is `nil`. If not specified effected value is `15`
-* `http_read_timeout`:The number of seconds to wait for HTTP response data. Default option value is `nil`. If not specified effected value is `60`
+* `timestamps` - by default Dynamoid sets `created_at` and `updated_at`
+  fields for model creation and updating. You can disable this
+  behavior by setting `false` value
+* `sync_retry_max_times` - when Dynamoid creates or deletes table
+  synchronously it checks for completion specified times. Default is 60
+  (times). It's a bit over 2 minutes by default
+* `sync_retry_wait_seconds` - time to wait between retries. Default is 2
+  (seconds)
+* `convert_big_decimal` - if `true` then Dynamoid converts numbers
+  stored in `Hash` in `raw` field to float. Default is `false`
+* `store_attribute_with_nil_value` - if `true` Dynamoid keeps attribute
+  with `nil` value in a document. Otherwise Dynamoid removes it while
+  saving a document. Default is `nil` which equals behaviour with `false`
+  value.
+* `models_dir` - `dynamoid:create_tables` rake task loads DynamoDb
+  models from this directory. Default is `./app/models`.
+* `application_timezone` - Dynamoid converts all `datetime` fields to
+  specified time zone when loads data from the storage.
+  Acceptable values - `:utc`, `:local` (to use system time zone) and
+  time zone name e.g. `Eastern Time (US & Canada)`. Default is `utc`
+* `dynamodb_timezone` - When a datetime field is stored in string format
+  Dynamoid converts it to specified time zone when saves a value to the
+  storage. Acceptable values - `:utc`, `:local` (to use system time
+  zone) and time zone name e.g. `Eastern Time (US & Canada)`. Default is
+  `utc`
+* `store_datetime_as_string` - if `true` then Dynamoid stores :datetime
+  fields in ISO 8601 string format. Default is `false`
+* `store_date_as_string` - if `true` then Dynamoid stores :date fields
+  in ISO 8601 string format. Default is `false`
+* `store_boolean_as_native` - if `true` Dynamoid stores boolean fields
+  as native DynamoDB boolean values. Otherwise boolean fields are stored
+  as string values `'t'` and `'f'`. Default is true
+* `backoff` - is a hash: key is a backoff strategy (symbol), value is
+  parameters for the strategy. Is used in batch operations. Default id
+  `nil`
+* `backoff_strategies`: is a hash and contains all available strategies.
+  Default is { constant: ..., exponential: ...}
+* `log_formatter`: overrides default AWS SDK formatter. There are
+  several canned formatters: `Aws::Log::Formatter.default`,
+  `Aws::Log::Formatter.colored` and `Aws::Log::Formatter.short`. Please
+  look into `Aws::Log::Formatter` AWS SDK documentation in order to
+  provide own formatter.
+* `http_continue_timeout`: The number of seconds to wait for a
+  100-continue HTTP response before sending the request body. Default
+  option value is `nil`. If not specified effected value is `1`
+* `http_idle_timeout`: The number of seconds an HTTP connection is
+  allowed to sit idle before it is considered stale. Default option
+  value is `nil`. If not specified effected value is `5`
+* `http_open_timeout`: The number of seconds to wait when opening a HTTP
+  session. Default option value is `nil`. If not specified effected
+  value is `15`
+* `http_read_timeout`:The number of seconds to wait for HTTP response
+  data. Default option value is `nil`. If not specified effected value
+  is `60`
 
 
 ## Concurrency
 
-Dynamoid supports basic, ActiveRecord-like optimistic locking on save operations. Simply add a `lock_version` column to your table like so:
+Dynamoid supports basic, ActiveRecord-like optimistic locking on save
+operations. Simply add a `lock_version` column to your table like so:
 
 ```ruby
 class MyTable
@@ -817,23 +1123,38 @@ class MyTable
 end
 ```
 
-In this example, all saves to `MyTable` will raise an `Dynamoid::Errors::StaleObjectError` if a concurrent process loaded, edited, and saved the same row. Your code should trap this exception, reload the row (so that it will pick up the newest values), and try the save again.
+In this example, all saves to `MyTable` will raise an
+`Dynamoid::Errors::StaleObjectError` if a concurrent process loaded,
+edited, and saved the same row. Your code should trap this exception,
+reload the row (so that it will pick up the newest values), and try the
+save again.
 
-Calls to `update` and `update!` also increment the `lock_version`, however they do not check the existing value. This guarantees that a update operation will raise an exception in a concurrent save operation, however a save operation will never cause an update to fail. Thus, `update` is useful & safe only for doing atomic operations (e.g. increment a value, add/remove from a set, etc), but should not be used in a read-modify-write pattern.
+Calls to `update` and `update!` also increment the `lock_version`,
+however, they do not check the existing value. This guarantees that a
+update operation will raise an exception in a concurrent save operation,
+however a save operation will never cause an update to fail. Thus,
+`update` is useful & safe only for doing atomic operations (e.g.
+increment a value, add/remove from a set, etc), but should not be used
+in a read-modify-write pattern.
 
 
 ### Backoff strategies
 
 
-You can use several methods that run efficiently in batch mode like `.find_all` and `.import`. It affects `Query` and `Scan` operations as well.
+You can use several methods that run efficiently in batch mode like
+`.find_all` and `.import`. It affects `Query` and `Scan` operations as
+well.
 
-The backoff strategy will be used when, for any reason, some items could not be processed as part of a batch mode command.
-Operations will be re-run to process these items.
+The backoff strategy will be used when, for any reason, some items could
+not be processed as part of a batch mode command. Operations will be
+re-run to process these items.
 
-Exponential backoff is the recommended way to handle throughput limits exceeding and throttling on the table.
+Exponential backoff is the recommended way to handle throughput limits
+exceeding and throttling on the table.
 
-There are two built-in strategies - constant delay and truncated binary exponential backoff.
-By default no backoff is used but you can specify one of the built-in ones:
+There are two built-in strategies - constant delay and truncated binary
+exponential backoff. By default no backoff is used but you can specify
+one of the built-in ones:
 
 ```ruby
 Dynamoid.configure do |config|
@@ -846,7 +1167,8 @@ end
 
 ```
 
-You can just specify strategy without any arguments to use default presets:
+You can just specify strategy without any arguments to use default
+presets:
 
 ```ruby
 Dynamoid.configure do |config|
@@ -854,7 +1176,7 @@ Dynamoid.configure do |config|
 end
 ```
 
-You can use your own strategy in following way:
+You can use your own strategy in the following way:
 
 ```ruby
 Dynamoid.configure do |config|
@@ -871,10 +1193,11 @@ end
 
 There are a few Rake tasks available out of the box:
 
-  * `rake dynamoid:create_tables`
-  * `rake dynamoid:ping`
+* `rake dynamoid:create_tables`
+* `rake dynamoid:ping`
 
-In order to use them in non-Rails application they should be required explicitly:
+In order to use them in non-Rails application they should be required
+explicitly:
 
 ```ruby
 # Rakefile
@@ -883,12 +1206,14 @@ Rake::Task.define_task(:environment)
 require 'dynamoid/tasks'
 ```
 
-The Rake tasks depend on `:environment` task so it should be declared
-as well.
+The Rake tasks depend on `:environment` task so it should be declared as
+well.
 
 ## Test Environment
 
-In test environment you will most likely want to clean the database between test runs to keep tests completely isolated. This can be achieved like so
+In test environment you will most likely want to clean the database
+between test runs to keep tests completely isolated. This can be
+achieved like so
 
 ```ruby
 module DynamoidReset
@@ -919,7 +1244,8 @@ RSpec.configure do |config|
 end
 ```
 
-In Rails, you may also want to ensure you do not delete non-test data accidentally by adding the following to your test environment setup:
+In Rails, you may also want to ensure you do not delete non-test data
+accidentally by adding the following to your test environment setup:
 
 ```ruby
 raise "Tests should be run in 'test' environment only" if Rails.env != 'test'
@@ -956,9 +1282,14 @@ timing (231.28 ms).
 
 ## Credits
 
-Dynamoid borrows code, structure, and even its name very liberally from the truly amazing [Mongoid](https://github.com/mongoid/mongoid). Without Mongoid to crib from none of this would have been possible, and I hope they don't mind me reusing their very awesome ideas to make DynamoDB just as accessible to the Ruby world as MongoDB.
+Dynamoid borrows code, structure, and even its name very liberally from
+the truly amazing [Mongoid](https://github.com/mongoid/mongoid). Without
+Mongoid to crib from none of this would have been possible, and I hope
+they don't mind me reusing their very awesome ideas to make DynamoDB
+just as accessible to the Ruby world as MongoDB.
 
-Also, without contributors the project wouldn't be nearly as awesome. So many thanks to:
+Also, without contributors the project wouldn't be nearly as awesome. So
+many thanks to:
 
 * [Logan Bowers](https://github.com/loganb)
 * [Lane LaRue](https://github.com/luxx)
@@ -979,9 +1310,12 @@ Also, without contributors the project wouldn't be nearly as awesome. So many th
 
 ## Running the tests
 
-Running the tests is fairly simple. You should have an instance of DynamoDB running locally. Follow these steps to setup your test environment.
+Running the tests is fairly simple. You should have an instance of
+DynamoDB running locally. Follow these steps to setup your test
+environment.
 
- * First download and unpack the latest version of DynamoDB.  We have a script that will do this for you if you use homebrew on a Mac.
+ * First download and unpack the latest version of DynamoDB. We have a
+   script that will do this for you if you use homebrew on a Mac.
 
     ```shell
     bin/setup
@@ -999,13 +1333,18 @@ Running the tests is fairly simple. You should have an instance of DynamoDB runn
     rake
     ```
 
- * When you are done, remember to stop the local test instance of dynamodb
+ * When you are done, remember to stop the local test instance of
+   dynamodb
 
     ```shell
     bin/stop_dynamodblocal
     ```
 
-If you want to run all the specs that travis runs, use `bundle exec wwtd`, but first you will need to setup all the rubies, for each of `%w( 2.0.0-p648 2.1.10 2.2.6 2.3.3 2.4.1 jruby-9.1.8.0 )`.  When you run `bundle exec wwtd` it will take care of starting and stopping the local dynamodb instance.
+If you want to run all the specs that travis runs, use `bundle exec
+wwtd`, but first you will need to setup all the rubies, for each of `%w(
+2.0.0-p648 2.1.10 2.2.6 2.3.3 2.4.1 jruby-9.1.8.0 )`. When you run
+`bundle exec wwtd` it will take care of starting and stopping the local
+dynamodb instance.
 
 ```shell
 rvm use 2.0.0-p648