Add documentation page about mappings

helpers/handlebars.js

@@ -66,8 +66,7 @@ module.exports = {
     return new SafeString(title);
   },
 
-  since: version => `<p class="since">Added in v${version}</p>`,
+  since: version => `<p class="since">Added in ${version}</p>`,
 
-  deprecated: version => `<p class="deprecated">Deprecated since v${version}</p>`
+  deprecated: version => `<p class="deprecated">Deprecated since ${version}</p>`
 };
-

src/api/1/controller-collection/create/index.md

@@ -11,9 +11,15 @@ Creates a new [collection]({{ site_base_path }}guide/1/essentials/persisted), in
 
 {{{since "1.3.0"}}}
 
-You can also provide an optional body with a data mapping that allow you to exploit the full capabilities of our persistent data storage layer.
+You can also provide an optional body with a [collection mapping]({{ site_base_path }}guide/1/essentials/database-mappings) allowing you to exploit the full capabilities of our persistent data storage layer.
 
-This method will only update the mapping if the collection already exists.
+This method will only update the mapping when the collection already exists.
+
+{{{since "1.7.1"}}}
+
+You can define the collection [dynamic mapping policy]({{ site_base_path}}guide/1/essentials/database-mappings/#dynamic-mapping-policy) by setting the `dynamic` field to the desired value.
+
+You can define [collection additional metadata]({{ site_base_path}}guide/1/essentials/database-mappings/#collection-metadata) within the `_meta` root field.
 
 ---
 
@@ -29,6 +35,10 @@ Body:
 
 ```js
 {
+  "dynamic": "[false|true|strict]",
+  "_meta": {
+    "field": "value"
+  },
   "properties": {
     "field1": { 
       "type": "integer"
@@ -37,8 +47,8 @@ Body:
       "type": "keyword"
     },
     "field3": {
-        "type":   "date",
-        "format": "yyyy-MM-dd HH:mm:ss||yyyy-MM-dd||epoch_millis"
+      "type":   "date",
+      "format": "yyyy-MM-dd HH:mm:ss||yyyy-MM-dd||epoch_millis"
     }
   }
 }
@@ -54,6 +64,10 @@ Body:
   "controller": "collection",
   "action": "create",
   "body": {
+    "dynamic": "[false|true|strict]",
+    "_meta": {
+      "field": "value"
+    },
     "properties": {
       "field1": { 
         "type": "integer"
@@ -62,8 +76,8 @@ Body:
         "type": "keyword"
       },
       "field3": {
-          "type":   "date",
-          "format": "yyyy-MM-dd HH:mm:ss||yyyy-MM-dd||epoch_millis"
+        "type":   "date",
+        "format": "yyyy-MM-dd HH:mm:ss||yyyy-MM-dd||epoch_millis"
       }
     }
   }
@@ -74,16 +88,18 @@ Body:
 
 ## Arguments
 
-* `collection`: collection name to create
-* `index`: index name that will host the new collection
+* `collection`: name of the collection to create
+* `index`: index that will host the new collection
 
 ---
 
 ## Body properties
 
 ### Optional:
 
-* `properties`: object describing the data mapping to associate to the new collection, using [Elasticsearch mapping format](https://www.elastic.co/guide/en/elasticsearch/reference/5.6/mapping.html).
+* `dynamic`: [dynamic mapping policy]({{ site_base_path}}guide/1/essentials/database-mappings/#dynamic-mapping-policy) for new fields. Allowed values: `true` (default), `false`, `strict`
+* `_meta`: [collection additional metadata]({{ site_base_path}}guide/1/essentials/database-mappings/#collection-metadata) stored next to the collection
+* `properties`: object describing the data mapping to associate to the new collection, using [Elasticsearch types definitions format]({{ site_base_path}}guide/1/essentials/database-mappings/#properties-types-definition)
 
 ---
 

src/api/1/controller-collection/get-mapping/index.md

@@ -7,7 +7,11 @@ title: getMapping
 
 {{{since "1.0.0"}}}
 
-Returns a collection mapping.
+Returns the collection mapping.
+
+{{{since "1.7.1"}}}
+
+Also returns the collection [dynamic mapping policy]({{ site_base_path}}guide/1/essentials/database-mappings/#dynamic-mapping-policy) and [collection additional metadata]({{ site_base_path}}guide/1/essentials/database-mappings/#collection-metadata).
 
 ---
 
@@ -47,13 +51,17 @@ Returns a mapping object with the following structure:
 
 ```
 <index>
-   |- mappings
-         |- <collection>
-               |- properties
-                     |- mapping for field 1
-                     |- mapping for field 2
-                     |- ...
-                     |- mapping for field n
+  |- mappings
+    |- <collection>
+      |- dynamic
+      |- _meta
+        |- metadata 1
+        |- metadata 1
+      |- properties
+        |- mapping for field 1
+        |- mapping for field 2
+        |- ...
+        |- mapping for field n
 ```
 
 ### Example:
@@ -71,16 +79,16 @@ Returns a mapping object with the following structure:
     "<index>": {
       "mappings": {
         "<collection>": {
+          "dynamic": "true",
+          "_meta": {
+            "metadata1": "value1"
+          },
           "properties": {
-            "field1": { 
-              "type": "integer"
-            },
-            "field2": {
-              "type": "keyword"
-            },
+            "field1": { "type": "integer" },
+            "field2": { "type": "keyword" },
             "field3": {
-                "type":   "date",
-                "format": "yyyy-MM-dd HH:mm:ss||yyyy-MM-dd||epoch_millis"
+              "type":   "date",
+              "format": "yyyy-MM-dd HH:mm:ss||yyyy-MM-dd||epoch_millis"
             }
           }
         }

src/api/1/controller-collection/update-mapping/index.md

@@ -9,6 +9,12 @@ title: updateMapping
 
 Updates a collection mapping.
 
+{{{since "1.7.1"}}}
+
+You can define the collection [dynamic mapping policy]({{ site_base_path}}guide/1/essentials/database-mappings/#dynamic-mapping-policy) by setting the `dynamic` field to the desired value.
+
+You can define [collection additional metadata]({{ site_base_path}}guide/1/essentials/database-mappings/#collection-metadata) within the `_meta` root field.
+
 ---
 
 ## Query Syntax
@@ -23,6 +29,10 @@ Body:
 
 ```js
 {
+  "dynamic": "[true|false|strict]",
+  "_meta": {
+    "field": "value"
+  },
   "properties": {
     "field1": { 
       "type": "integer"
@@ -31,8 +41,8 @@ Body:
       "type": "keyword"
     },
     "field3": {
-        "type":   "date",
-        "format": "yyyy-MM-dd HH:mm:ss||yyyy-MM-dd||epoch_millis"
+      "type":   "date",
+      "format": "yyyy-MM-dd HH:mm:ss||yyyy-MM-dd||epoch_millis"
     }
   }
 }
@@ -46,8 +56,11 @@ Body:
   "collection": "<collection>",
   "controller": "collection",
   "action": "updateMapping",
-
   "body": {
+  "dynamic": "[true|false|strict]",
+    "_meta": {
+      "field": "value"
+    },
     "properties": {
       "field1": { 
         "type": "integer"
@@ -56,8 +69,8 @@ Body:
         "type": "keyword"
       },
       "field3": {
-          "type":   "date",
-          "format": "yyyy-MM-dd HH:mm:ss||yyyy-MM-dd||epoch_millis"
+        "type":   "date",
+        "format": "yyyy-MM-dd HH:mm:ss||yyyy-MM-dd||epoch_millis"
       }
     }
   }
@@ -68,14 +81,18 @@ Body:
 
 ## Arguments
 
-* `collection`: collection name
-* `index`: index name
+* `collection`: name of the collection to update
+* `index`: index that will host the new collection
 
 ---
 
 ## Body properties
 
-* `properties`: object describing the data mapping to associate to the new collection, using [Elasticsearch mapping format](https://www.elastic.co/guide/en/elasticsearch/reference/5.6/mapping.html).
+### Optional:
+
+* `dynamic`: [dynamic mapping policy]({{ site_base_path}}guide/1/essentials/database-mappings/#dynamic-mapping-policy) for new fields. Allowed values: `true` (default), `false`, `strict`
+* `_meta`: [collection additional metadata]({{ site_base_path}}guide/1/essentials/database-mappings/#collection-metadata) stored next to the collection
+* `properties`: object describing the data mapping to associate to the new collection, using [Elasticsearch types definitions format]({{ site_base_path}}guide/1/essentials/database-mappings/#properties-types-definition)
 
 ---