Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add documentation page about mappings #271

Merged
merged 10 commits into from
Mar 29, 2019
Merged

Add documentation page about mappings #271

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
5f5d95d
Add database-mappings page
Aschen Mar 27, 2019
8b0dad4
Update collection API methods
Aschen Mar 27, 2019
673ae0a
Update collection:create in SDKs
Aschen Mar 27, 2019
f67ed86
Update collection:updateMapping and getMapping in SDKs
Aschen Mar 27, 2019
7a5bace
Fix since tag
Aschen Mar 27, 2019
65d4186
Apply suggestions from @scottinet
scottinet Mar 27, 2019
a06e8f9
Merge branch '2-dev' into add-ability-to-restrict-collection-mapping
scottinet Mar 28, 2019
d643de5
dead link + warning about _meta
Aschen Mar 29, 2019
7882817
merge ok
Aschen Mar 29, 2019
e15e307
collection mapping => database mapping
Aschen Mar 29, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 2 additions & 3 deletions helpers/handlebars.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>`
};

34 changes: 25 additions & 9 deletions src/api/1/controller-collection/create/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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) that allow you to exploit the full capabilities of our persistent data storage layer.
Aschen marked this conversation as resolved.
Show resolved Hide resolved

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.

---

Expand All @@ -29,6 +35,10 @@ Body:

```js
{
"dynamic": "false",
Aschen marked this conversation as resolved.
Show resolved Hide resolved
"_meta": {
"field": "value"
},
"properties": {
"field1": {
"type": "integer"
Expand All @@ -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"
}
}
}
Expand All @@ -54,6 +64,10 @@ Body:
"controller": "collection",
"action": "create",
"body": {
"dynamic": "false",
Aschen marked this conversation as resolved.
Show resolved Hide resolved
"_meta": {
"field": "value"
},
"properties": {
"field1": {
"type": "integer"
Expand All @@ -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"
}
}
}
Expand All @@ -74,16 +88,18 @@ Body:

## Arguments

* `collection`: data collection to create
* `index`: data index that will host the new data 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
Aschen marked this conversation as resolved.
Show resolved Hide resolved
* `_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)

---

Expand Down
44 changes: 26 additions & 18 deletions src/api/1/controller-collection/get-mapping/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,11 @@ title: getMapping

{{{since "1.0.0"}}}

Returns a data 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).

---

Expand Down Expand Up @@ -36,8 +40,8 @@ Method: GET

## Arguments

* `collection`: data collection
* `index`: data index
* `collection`: collection name
* `index`: index name

---

Expand All @@ -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:
Expand All @@ -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"
}
}
}
Expand Down
35 changes: 26 additions & 9 deletions src/api/1/controller-collection/update-mapping/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,13 @@ title: updateMapping

{{{since "1.0.0"}}}

Updates a data collection mapping.
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.

---

Expand All @@ -23,6 +29,10 @@ Body:

```js
{
"dynamic": "false",
Aschen marked this conversation as resolved.
Show resolved Hide resolved
"_meta": {
"field": "value"
},
"properties": {
"field1": {
"type": "integer"
Expand All @@ -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"
}
}
}
Expand All @@ -46,8 +56,11 @@ Body:
"collection": "<collection>",
"controller": "collection",
"action": "updateMapping",

"body": {
"dynamic": "false",
Aschen marked this conversation as resolved.
Show resolved Hide resolved
"_meta": {
"field": "value"
},
"properties": {
"field1": {
"type": "integer"
Expand All @@ -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"
}
}
}
Expand All @@ -68,14 +81,18 @@ Body:

## Arguments

* `collection`: data collection
* `index`: data index
* `collection`: name of the collection to create
* `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
Aschen marked this conversation as resolved.
Show resolved Hide resolved
* `_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)

---

Expand Down
Loading