###########################
Overview of Dynamodb-mapper
###########################

.. include:: ../_include/intro.rst

Requirements
============

 - Boto = 2.6.0
 - AWS account

Highlights
==========

- Python <--> DynamoDB type mapping
- Deep schema definition and validation with ``Onctuous`` (new in 1.8.0)
- Multi-target transaction (new in 1.6.0)
- Sub-transactions (new in 1.6.2)
- Migration engine (new in 1.7.0)
- Smart conflict detection (new in 1.7.0)
- Full low-level chunking abstraction for ``scan``, ``query`` and ``get_batch``
- Default values
- Auto-inc hash_key
- Framework agnostic

.. TODO: add links to related documentation

Logging
=======

Dynamodb-mapper uses 3 loggers:

- model
- model.database-access
- transactions

.. example de parametrage de la sortie

Known limitations
=================

- Dates nested in a dict or set can not be saved as ``datetime`` does not support JSON serialization. (issue #7)

Important performance notice
============================

To avoid superfluous ``DescribeTable`` requests, ``Table`` objects are cached
after their first request. As it removes an extra overhead of ~20ms that was
before each requests, it might let you go faster than your provisioned
throughput. This will trigger an exponential backoff retry algorithm in Boto.
While this algorithm is well done, be informed that the resulting effective
throughput will be up to 40% *slower* than what you could have expected with
your configured throughput.

If you ever reach this situation, you have 2 options:

 - either increase (if bandwith allows) your provisioned throughput.
 - either introduce manual, carefully chosen sleeps.

With the second option, I have been able to reach the theoretical throughput on
an extremely intensive and non representative benchmark.