Documents

The document is a simple JSON entity. It is stored in a collection.

Document without collection

You can create a document without existing collection, but you'll miss some features collection provides.

Filter

Documents can be found using a fulltext search or filter.

This example is about geolocation filter.

Collection customers_shared_locations:

deform collection create -d '{
    "_id": "customers_shared_locations",
    "name": "Customers shared locations",
    "schema": {
        "type": "object",
        "properties": {
            "location": {
                "type": "object",
                "properties": {
                    "coordinates": {
                        "items": {
                            "type": "number"
                        },
                        "maxLength": 2,
                        "minLength": 2,
                        "type": "array"
                    },
                    "type": {
                        "enum": ["Point"]
                    }
                }
            }
        }
    },
    "indexes": [
        {
            "property": "$2dsphere:location",
            "type": "simple",
            "unique": false
        }
    ]
}'

Document:

deform document create -c customers_shared_locations -d '{
    "_id": "12345",
    "location": {
        "coordinates": [
            40.432121,  -3.707698
        ],
        "type": "Point"
    } 
}' 

You can find this document withing 600 meters radius.

Points [40.432121, -3.707698] and [40.432446, -3.700996] are ~573 meters away.

deform documents find -c customers_shared_locations -f '{
    "location": {
        "$geoWithin": {
            "$centerSphere": {
                40.432446, -3.700996,
                0.6/6378.137
            }
        }
    }
}'

Features

Feature	Collection Required	Description
storage		attach files to documents
validation	*	validate a document
processing	*	process a document according collection's schema
hooks		trigger a hook after document event

storage

You can upload files with data to your document in a single request.

It will create a document with a file reference. File will be saved as a document to _files collection.

Create a document using CLI:

deform document create -c users -d '{
    "name": "Andrey",
    "avatar": @"/home/andrey/files/avatar.jpg"
}'

deform documents find -c users -f '{"name": "Andrey"}' --pretty

{
    "_id": "574d48cf32d2c69274322585",
    "name": "andrey",
    "avatar": {
        "_id": "574c9a266dff87000562eaf6",
        "collection_id": "users",
        "content_type": "image/png",
        "date_created": "2016-05-31T19:53:10.43Z",
        "document_id": "574d48cf32d2c69274322585",
        "last_access": "2016-05-31T19:53:10.43Z",
        "md5": "a6a859273c133cdf168295a3b7d83a0f",
        "name": "avatar.png",
        "size": 3421
    }
}

Also a _files collection will contain a file document.

deform documents find -c _files -f '{"_id": "574c9a266dff87000562eaf6"}' --pretty

{
    "_id": "574c9a266dff87000562eaf6",
    "collection_id": "users",
    "content_type": "image/png",
    "date_created": "2016-05-31T19:53:10.43Z",
    "document_id": "574d48cf32d2c69274322585",
    "last_access": "2016-05-31T19:53:10.43Z",
    "md5": "a6a859273c133cdf168295a3b7d83a0f",
    "name": "avatar.png",
    "size": 3421
}

validation

We are using JSON Schema customized draft v4.

Schema validation:

{
    "type": "object",
    "properties": {
        "integer_price": {
            "type": "integer"
        },
        "float_price": {
            "type": "number"
        }
    }
}

Document	Valid
{"integer_price": 1.2}
{"integer_price": 1}	*
{"float_price": 1.2}	*
{"float_price": 1}	*

processing

hooks

Document can trigger a hook.

Hooks has triggers property of type array.

Every document operation via interfaces pushes this event to hook's queue.

HTTP Method	Hook trigger
POST	created
PATCH	updated
DELETE	deleted
PUT	updated. If document exists
PUT	created. If document does not exist

Cli-Deform method	Hook trigger

Python-Deform method	Hook trigger

Example usage

We need to receive a slack notification every time new user registers in one of our services.

There are 4 steps to achieve the result:

• create a collection for users. users
• create a collection for slack notifications. slack_notifications
• add a webhook for user document creation. Hook will send it slack_notifications
• add a webhook for slack_notifications document creation. Hook will send it to Slack.

Let's use CLI.

step 1

Create a collection for users.

deform collection create -d '{
    "_id": "users",
    "name":"users",
    "schema": {
        "type": "object",
        "properties": {
            "username": {
                "type": "string"
            },
            "email": {
                "type": "string"
            },
            "avatar": {
                "type": "string"
            }
        }
    }
}'

step 2

Create a collection for slack notifications.

deform collection create -d '{
    "_id": "slack_notifications",
    "name": "Slack Notifications",
    "schema": {
        "title": "Slack specific hook wrapper",
        "type": "object",
        "properties": {
            "text": {
                "type": "string",
                "processors": [
                    {
                        "name": "template",
                        "in": {
                            "context": {
                                "profile": {
                                    "property": "user"
                                }
                            },
                            "syntax": {
                                "value": "handlebars"
                            },
                            "template_string": {
                                "value": "{{#if profile}} Welcome <{{profile.username}}>{{/if}}"
                            }
                        }
                    }
                ]
            },
            "user": {
                "type": "object",
                "properties": {
                    "username": {
                        "type": "string"
                    }
                },
                "additionalProperties": true
            }
        }
    }
}'

step 3

Add a hook for new user registration. We must insert his data to slack_notifications collection.

deform document save -c _hooks -d '{
    "_id": "user_registered",
    "name": "User joined",
    "url": "https://YOUR_PROJECT.deform.io/api/collections/slack_notifications/documents/",
    "method": "PUT",
    "triggers": ["created"],
    "collection": "users",
    "headers": {
        "Authorization": "Token slack_notifications_creation_token"
    }
}'

Notes:

• method set to PUT. This will create or update existing slack notification.
• url set to our collection slack_notifications
• triggers set to created. Only new users will trigger this hook
• headers has an item with AUTHORIZATION header. We recommend you to create a token allowed to create documents inside of slack_notifications collection.

  deform document save -c _tokens -d '{
      "_id": "slack_notifications_creation_token",
      "name": "Slack notification",
      "is_active": true,
      "permission": {
          "allow": {
              "create": [
                  {
                      "what": "document",
                      "where": "slack_notifications"
                  }
              ]
          }
      }
  }'
  

step 4

Now we need to create a hook for slack_notifications collection.

It will send a document to a Slack.

deform document save -c _hooks -d '{
    "_id": "send_slack_notification",
    "name": "Slack notification",
    "url": "https://hooks.slack.com/services/YOUR_SLACK_DETAILS",
    "method": "POST",
    "triggers": ["created"],
    "collection": "slack_notifications"
}'

Notes:

• url replace to a correct slack webhook url.

How does it work.

New User registation in your service causes a document to be created inside users collection.

Collection users has a hook triggering by create event. This hook will commit a HTTP Request:

• use an HTTP Method PUT to create or update
• use a Authorization header
• send a document to a slack_notifications collection

Collection slack_notifications has a hook triggering by create event. This hook will send a document directly to a Slack

In a few moments you will get a Slack notification.