Skip to content

Commit

Permalink
Merge pull request #332 from Dynamoid/update-readme
Browse files Browse the repository at this point in the history 
Update Readme.md
  • Loading branch information
@andrykonchin
andrykonchin committed Apr 21, 2019
2 parents 930dc3e + 606209c commit 5675129
Showing 1 changed file with 27 additions and 59 deletions.
86 changes: 27 additions & 59 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,12 @@
# Dynamoid

You are viewing the README for version 3 of Dynamoid. See the [CHANGELOG](https://github.com/Dynamoid/Dynamoid/blob/master/CHANGELOG.md#200) for details on breaking changes since 1.3.x.

For version 1.3.x use the [1-3-stable branch](https://github.com/Dynamoid/Dynamoid/blob/1-3-stable/README.md).
[![Build Status](https://travis-ci.org/Dynamoid/dynamoid.svg?branch=master)](https://travis-ci.org/Dynamoid/dynamoid)
[![Code Climate](https://codeclimate.com/github/Dynamoid/dynamoid.svg)](https://codeclimate.com/github/Dynamoid/dynamoid)
[![Coverage Status](https://coveralls.io/repos/github/Dynamoid/Dynamoid/badge.svg?branch=master)](https://coveralls.io/github/Dynamoid/Dynamoid?branch=master)
[![CodeTriage Helpers](https://www.codetriage.com/dynamoid/dynamoid/badges/users.svg)](https://www.codetriage.com/dynamoid/dynamoid)
[![Yard Docs](http://img.shields.io/badge/yard-docs-blue.svg)](https://www.rubydoc.info/github/Dynamoid/dynamoid/frames)
[![Inline docs](http://inch-ci.org/github/Dynamoid/Dynamoid.svg?branch=master)](http://inch-ci.org/github/Dynamoid/Dynamoid)
![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
Expand All @@ -14,21 +18,6 @@ DynamoDB is not like other document-based databases you might know, and is very

But if you want a fast, scalable, simple, easy-to-use database (and a Gem that supports it) then look no further!


| Project | Dynamoid |
|------------------------ | ----------------- |
| gem name | dynamoid |
| license | MIT |
| download rank | [![Total Downloads](https://img.shields.io/gem/rt/Dynamoid.svg)](https://rubygems.org/gems/dynamoid) |
| version | [![Gem Version](https://badge.fury.io/rb/dynamoid.svg)](https://badge.fury.io/rb/dynamoid) |
| dependencies | [![Depfu](https://badges.depfu.com/badges/6661c063c8e77a5008344fc7283a50aa/status.svg)](https://depfu.com) |
| code quality | [![Code Climate](https://codeclimate.com/github/Dynamoid/dynamoid.svg)](https://codeclimate.com/github/Dynamoid/dynamoid) |
| continuous integration | [![Build Status](https://travis-ci.org/Dynamoid/dynamoid.svg?branch=master)](https://travis-ci.org/Dynamoid/dynamoid) |
| test coverage | [![Coverage Status](https://coveralls.io/repos/github/Dynamoid/Dynamoid/badge.svg?branch=master)](https://coveralls.io/github/Dynamoid/Dynamoid?branch=master) |
| triage helpers | [![CodeTriage Helpers](https://www.codetriage.com/dynamoid/dynamoid/badges/users.svg)](https://www.codetriage.com/dynamoid/dynamoid) |
| homepage | [https://github.com/Dynamoid/dynamoid](https://github.com/Dynamoid/dynamoid) |
| documentation | [http://rdoc.info/github/Dynamoid/dynamoid/frames](http://rdoc.info/github/Dynamoid/dynamoid/frames) |

## Installation

Installing Dynamoid is pretty simple. First include the Gem in your Gemfile:
Expand Down Expand Up @@ -176,7 +165,7 @@ class Document
end
```

WARNING: Fields in numeric format are stored with nanoseconds as a fraction part and precision could be lost.
**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:
Expand Down Expand Up @@ -542,8 +531,7 @@ 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.

#### Pagination
##### Limits / Skip-Take
#### Limits

There are three types of limits that you can query with:

Expand Down Expand Up @@ -581,8 +569,9 @@ Address.record_limit(10_000).batch(100).each { … } # Batch specified as part o
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 Native Pages
At times it can be useful to rely on DynamoDB [default pages](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Query.html#Query.Pagination)
#### 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.

Expand All @@ -591,18 +580,20 @@ method, which yields arrays of records.

```ruby
Address.find_by_pages do |addresses, metadata|
# have an array of pages
end
```

Each yielded pages returns metadata as the second argument, which is a hash
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:

```ruby
class UserController < ApplicationController
def index
next_page = params[:next_page_token] ? JSON.parse(Base64.decode64(params[:next_page_token])) : ''
next_page = params[:next_page_token] ? JSON.parse(Base64.decode64(params[:next_page_token])) : nil

records, metadata = User.start(next_page).find_by_pages.first

Expand Down Expand Up @@ -727,44 +718,17 @@ There are following options:

The only mandatory option is `name`.

To use index in `Document.where` implicitly you need to project all the fields with option `projected_attributes: :all`.

There are two ways to query Global Secondary Indexes (GSI).

#### Explicit

The first way explicitly uses your GSI and utilizes the `find_all_by_secondary_index` method which will lookup a valid
GSI to use based on the inputs, you MUST provide the correct keys to match the GSI you want:
**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
find_all_by_secondary_index(
{
dynamo_primary_key_column_name => dynamo_primary_key_value
}, # The signature of find_all_by_secondary_index is ugly, so must be an explicit hash here
:range => {
"#{range_column}.#{range_modifier}" => range_value
},
# false is the same as DESC in SQL (newest timestamp first)
# true is the same as ASC in SQL (oldest timestamp first)
scan_index_forward: false # or true
)
```

Where the range modifier is one of `Dynamoid::Finders::RANGE_MAP.keys`, where the `RANGE_MAP` is:
class User
# ...

```ruby
RANGE_MAP = {
'gt' => :range_greater_than,
'lt' => :range_less_than,
'gte' => :range_gte,
'lte' => :range_lte,
'begins_with' => :range_begins_with,
'between' => :range_between,
'eq' => :range_eq
}
global_secondary_index hash_key: :age, projected_attributes: :all
end
```

Most range searches, like `eq`, need a single value, and searches like `between`, need an array with two values.
There is only one implicit way to query Global and Local Secondary Indexes (GSI/LSI).

#### Implicit

Expand Down Expand Up @@ -820,6 +784,10 @@ Listed below are all configuration options.
`'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`


## Concurrency
Expand Down

0 comments on commit 5675129

Please sign in to comment.