Atomic counters documentation missed

[Ilya Sviridov]

The atomic counter functionality is not documented

http://magnetodb.readthedocs.org/en/latest/update_item.html

[Ilya Sviridov (isviridov)]

Draft

Atomic counters is a part of update_item

URL:
http://{{HOST}}:{{PORT}}/v1/{{PROJECT_ID}}/data/tables/{{TABLE}}/update_item

Spec:
https://wiki.openstack.org/wiki/MagnetoDB/specs/data-api#Updateitem

User can specify action to perform on the item.
If action is "ADD" then MagnetoDB guarantees that operation will be performed
atomically. Sets and numbers are only valid types for ADD action.

If attribute type is number then this attribute can be used as atomic
counter.

Some examples with explanations:

1. Create table for forum threads. We have 4 attributes: name, subject, tags
and views count (we want to use it like atomic counter)

Request:

{
    "table_name": "Thread",
    "attribute_definitions": [
        {
            "attribute_name": "ForumName",
            "attribute_type": "S"
        },
        {
            "attribute_name": "Subject",
            "attribute_type": "S"
        },
        {
            "attribute_name": "Tags",
            "attribute_type": "SS"
        },
        {
            "attribute_name": "ViewsCount",
            "attribute_type": "N"
        }
    ],
    "key_schema": [
        {
            "attribute_name": "ForumName",
            "key_type": "HASH"
        },
        {
            "attribute_name": "Subject",
            "key_type": "RANGE"
        }
    ]
}

2. Put new item into Thread table.

Request:

{
    "item": {
      "ForumName": {"S": "MagnetoDB"},
      "Subject": {"S": "How do I delete an item?"},
      "LastPostedBy": {"S": "<email address hidden>"},
      "Tags": {"SS": ["Update", "Multiple Items"]},
      "ViewsCount": {"N": "0"}
    }
}

If we try to query an item now we'll see that ViewsCount = 0 and
Tags = ["Update", "Multiple Items"].

3. Use update_item to update Tags

Request:

{
    "key": {
        "ForumName": {
            "S": "MagnetoDB"
        },
        "Subject": {
            "S": "How do I delete an item?"
        }
    },
    "attribute_updates": {
        "Tags": {
            "action": "ADD",
          "value": {
            "SS": ["HelpMe"]
          }
        }
    }
}

If we try to query an item now we'll see that ViewsCount = 0 and
Tags = ["Update", "Multiple Items", "HelpMe"]

4. Atomic counters

Different users looking the thread and we need to update ViewsCount

Request:

{
    "key": {
        "ForumName": {
            "S": "MagnetoDB"
        },
        "Subject": {
            "S": "How do I delete an item?"
        }
    },
    "attribute_updates": {
        "ViewsCount": {
            "action": "ADD",
          "value": {
            "N": "1"
          }
        }
    }
}

Any time when different users try to query our item, they shell see same value
of ViewsCount. After our request ViewsCount should be 1.

Different users can update this value simultaneously.