DataStore documentation revamp Part 2/2 #1903

drochetti · 2020-06-03T02:26:05Z

Disclaimer: This is a work in progress PR. If you find anything bizarre like an iOS code snippet on an Android fragment, or clearly wrong code snippets it's because I'm still working on them (or I might just have missed them, who knows!?).

It has a dependency on #1827

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

wooj2 · 2020-06-03T17:43:40Z

docs/lib/datastore/data-access.md


 <inline-fragment platform="js" src="~/lib/datastore/fragments/js/data-access/save-snippet.md"></inline-fragment>
 <inline-fragment platform="ios" src="~/lib/datastore/fragments/ios/data-access/save-snippet.md"></inline-fragment>
 <inline-fragment platform="android" src="~/lib/datastore/fragments/android/data-access/save-snippet.md"></inline-fragment>

+The `save` method takes care of creating a new record or updating an existing one in case the model `id` already exists in the database.


The save method creates a new record, or in the event that one already exists in the database, it updates the record.

docs/lib/datastore/fragments/ios/data-access/delete-snippet.md

docs/lib/datastore/data-access.md

docs/lib/datastore/fragments/android/sync/10-installPlugin.md

wooj2 · 2020-06-03T18:07:46Z

docs/lib/datastore/schema-updates.md

-### Migrations
+## Migrations
+
+Local migrations on device are not currently supported. If you are syncing with the cloud the structure and items of that data in your DynamoDB table will not be touched as part of this process.


We might need to describe what a local migration is before saying that it is not supported?

wooj2 · 2020-06-03T18:08:51Z

docs/lib/datastore/sync.md

+## Setup cloud sync
+
+Synchronization between offline and online data can be tricky. DataStore goal is to remove that burden from the application code and handle all data consistency and reconciliation between local and remote behind the scenes, while developers focus on their application logic. Up to this point the focus was to setup a local datastore that works offline and has all the capabilities you would expect from a data persistence framework.


"up to this point" is ambiguous.... do we mean.. prior to launching amplify? or... something else?

No, the intent was to say up to that point in the docs (if you go page by page). A more clear sentence would definitely be better

wooj2 · 2020-06-03T18:10:19Z

docs/lib/datastore/sync.md

+
+For instance, when updating or deleting data, one has to consider that the state of the local data might be outdated in case the data syncrhonization process 


need to add periods to the end of these sentences to stay consistent.

wooj2 · 2020-06-03T18:13:05Z

docs/lib/datastore/sync.md

+### Conlfict detection and resolution
+
+When concurrently updating the data in multiple places, it is likely that some conflict might happen. For most of the cases the default *Auto-merge* algorithm should be able to resolve. However, there are scenarios where the algorithm won't be able to solve and for those a more advanced option is available and will be described in details in the next section.


the second sentence ends abruptly. i think it should dread ".... should be able to resolve conflicts"
3rd sentence change: "won't be able to be solve and" to "won't be able to be resolved, and in these cases, a more advanced.."

wooj2 · 2020-06-03T18:15:26Z

docs/lib/datastore/sync.md

+<inline-fragment platform="android" src="~/lib/datastore/fragments/android/sync/40-clear.md"></inline-fragment>
+
+This is a simple yet effective example. However, in a real scenario you might want to optimize it and only call `clear()` when a different user `signedIn` in order to avoid clearing the database for a repeated sign-in of the same user.


suggestion:

remove the words "optimize it and"

I think we need to add the word "is", so that it reads: ".. when a different user is signedIn in order.."

drochetti · 2020-06-04T22:43:34Z

docs/lib/datastore/fragments/android/sync/20-savePredicate.md

@@ -0,0 +1 @@
+TODO: add Android snippets


@jpignata @jamesonwilliams heads up, will need help here

drochetti · 2020-06-04T22:43:44Z

docs/lib/datastore/fragments/android/sync/30-savePredicateComparison.md

@@ -0,0 +1 @@
+TODO: add Android snippets


@jpignata @jamesonwilliams heads up, will need help here

drochetti · 2020-06-04T22:43:51Z

docs/lib/datastore/fragments/android/sync/40-clear.md

@@ -0,0 +1 @@
+// TODO add Android snippet


@jpignata @jamesonwilliams heads up, will need help here

docs/lib/datastore/conflict.md

docs/lib/datastore/data-access.md

docs/lib/datastore/fragments/android/data-access/query-pagination-snippet.md

docs/lib/datastore/fragments/android/sync/10-installPlugin.md

Co-authored-by: Jameson Williams <jhwill@amazon.com>

…docs into next-datastore-docs

lgtm-com · 2020-06-15T20:18:54Z

This pull request introduces 4 alerts and fixes 1 when merging 30d7abc into 85728cb - view on LGTM.com

new alerts:

4 for Unused variable, import, function or class

fixed alerts:

1 for Unused variable, import, function or class

lgtm-com · 2020-06-16T03:02:51Z

This pull request introduces 4 alerts and fixes 1 when merging 867bd57 into 85728cb - view on LGTM.com

new alerts:

4 for Unused variable, import, function or class

fixed alerts:

1 for Unused variable, import, function or class

…into next-datastore-docs

Co-authored-by: Jameson Williams <jhwill@amazon.com>

drochetti · 2020-07-01T18:14:59Z

docs/lib/datastore/menu.json

+    "how-it-works",
+    "examples"


@dabit3 I broke apart "How it works" and the JS full app examples

docs/lib/datastore/fragments/js/data-access/update-snippet.md

docs/lib/datastore/fragments/js/data-access/delete-snippet.md

docs/lib/datastore/conflict.md

wooj2 · 2020-07-01T18:31:21Z

docs/lib/datastore/fragments/ios/conflict.md

-</amplify-callout>
-
-The code below illustrates a conflict resolution handler for the `Post` model that retries a mutation with the same title, but the most recent remote data for all other fields. The conflict resolution handler discards conflicts for all other models (by passing `.discard` to the `resolve` function).
+The code below illustrates a conflict resolution handler for the `Post` model that retries a mutation with the same title, but the most recent remote data for all other fields. The conflict resolution handler discards conflicts for all other models (by passing `.applyRemote` to the `resolve` function).


on line 3, we say it can be specified in minutes, but it should be "seconds"

actually, let me verify this before you take action on this.

elorzafe

A few comments, I need to look docs/lib/datastore/sync/md

elorzafe · 2020-07-01T18:46:35Z

docs/lib/datastore/data-access.md


-To write any data to the DataStore you can pass an instance of a Model to `DataStore.save()` and it will be persisted in offline storage. At this point you can use it as an item in a normal data store such as querying, updating or deleting. If you choose to later connect to the cloud the item will be synchronized using GraphQL mutations and any other systems connected to the same backend can run queries or mutations on these items as well as observe them with GraphQL subscriptions.
+To write data to the DataStore, pass an instance of a model to `Amplify.DataStore.save()`:


On JS is like it was mentioned before, maybe is needed inline-fragment for that as well

docs/lib/datastore/data-access.md

docs/lib/datastore/examples.md

Co-authored-by: Francisco Rodriguez <elorzafe@amazon.com> Co-authored-by: Jameson Williams <jhwill@amazon.com>

…docs into next-datastore-docs

…-fragments feat: next datastore sync android fragments

j1mr10rd4n · 2020-07-13T15:04:45Z

#2105 has a fix for a typo in the relational save-snippet.

…into next-datastore-docs

drochetti added 3 commits May 27, 2020 02:57

datastore documentation flow re-org

5c7d327

Merge branch 'next-datastore-getting-started' into next-datastore-docs

b04536c

datastore docs revamp wip

e559193

drochetti requested review from lawmicha, jamesonwilliams, jpignata, rjuliano and wooj2 June 3, 2020 02:27

fix next step link

2fd9dd2

wooj2 reviewed Jun 3, 2020

View reviewed changes

drochetti added 3 commits June 3, 2020 12:36

update ios code snippets

3459454

update data access snippets

e15257b

address pr feedback and todos for js and android

e3e5a90

drochetti requested review from elorzafe and manueliglesias June 3, 2020 21:11

drochetti commented Jun 4, 2020

View reviewed changes

jamesonwilliams reviewed Jun 4, 2020

View reviewed changes

jamesonwilliams reviewed Jun 5, 2020

View reviewed changes

drochetti and others added 3 commits June 6, 2020 13:51

Apply suggestions from code review

1fae005

Co-authored-by: Jameson Williams <jhwill@amazon.com>

Merge remote-tracking branch 'origin/master' into next-datastore-docs

9871420

Merge branch 'next-datastore-docs' of https://github.com/aws-amplify/…

30d7abc

…docs into next-datastore-docs

Merge remote-tracking branch 'origin/master' into next-datastore-docs

867bd57

drochetti and others added 4 commits June 23, 2020 19:18

Merge remote-tracking branch 'origin/next-datastore-getting-started' …

7456bc3

…into next-datastore-docs

fix spelling

05c9e1d

Apply suggestions from code review

e3bd52e

Co-authored-by: Jameson Williams <jhwill@amazon.com>

Merge remote-tracking branch 'origin/master' into next-datastore-docs

0fbee13

drochetti commented Jul 1, 2020

View reviewed changes

clarify schema updates

0383338

dabit3 reviewed Jul 1, 2020

View reviewed changes

docs/lib/datastore/fragments/js/data-access/update-snippet.md Show resolved Hide resolved

dabit3 reviewed Jul 1, 2020

View reviewed changes

docs/lib/datastore/fragments/js/data-access/delete-snippet.md Outdated Show resolved Hide resolved

wooj2 reviewed Jul 1, 2020

View reviewed changes

docs/lib/datastore/conflict.md Show resolved Hide resolved

wooj2 reviewed Jul 1, 2020

View reviewed changes

drochetti added 3 commits July 1, 2020 11:31

improve conflict resolution paragraph

e89aea3

fix typo

04498b6

update log message

13bda3a

wooj2 approved these changes Jul 1, 2020

View reviewed changes

drochetti and others added 4 commits July 1, 2020 11:36

update js delete code snippet

664186e

update JS code snippet

77a7683

content updates for clear()

56c0862

feat: next datastore sync android fragments

95420c0

elorzafe reviewed Jul 1, 2020

View reviewed changes

drochetti and others added 6 commits July 7, 2020 17:10

addressing pr feedback

aadc662

Merge remote-tracking branch 'origin/master' into next-datastore-docs

152fb28

Apply suggestions from code review

0041446

Co-authored-by: Francisco Rodriguez <elorzafe@amazon.com> Co-authored-by: Jameson Williams <jhwill@amazon.com>

Merge branch 'next-datastore-docs' of https://github.com/aws-amplify/…

4f8eb9d

…docs into next-datastore-docs

Merge branch 'next-datastore-getting-started' into next-datastore-docs

079f5de

Merge pull request #2049 from aws-amplify/next-datastore-docs+android…

8e901d9

…-fragments feat: next datastore sync android fragments

j1mr10rd4n mentioned this pull request Jul 14, 2020

[Feedback]Datastore documentation is lacking. #2102

Closed

drochetti added 4 commits July 14, 2020 13:17

Merge remote-tracking branch 'origin/next-datastore-getting-started' …

74d4299

…into next-datastore-docs

update missing JS snippets

a031f37

fix iOS snippet

399d2ab

fix android pagination snippet

ea230ee

drochetti merged commit 348d24b into next-datastore-getting-started Jul 14, 2020

j1mr10rd4n mentioned this pull request Jul 15, 2020

Fix typo in relational save snippet #2105

Closed

jpignata deleted the next-datastore-docs branch November 30, 2020 22:05

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DataStore documentation revamp Part 2/2 #1903

DataStore documentation revamp Part 2/2 #1903

drochetti commented Jun 3, 2020 •

edited

Loading

wooj2 Jun 3, 2020

wooj2 Jun 3, 2020

wooj2 Jun 3, 2020

drochetti Jun 3, 2020

wooj2 Jun 3, 2020

wooj2 Jun 3, 2020

wooj2 Jun 3, 2020

drochetti Jun 4, 2020 •

edited

Loading

drochetti Jun 4, 2020 •

edited

Loading

drochetti Jun 4, 2020 •

edited

Loading

lgtm-com bot commented Jun 15, 2020

lgtm-com bot commented Jun 16, 2020

drochetti Jul 1, 2020

wooj2 Jul 1, 2020

wooj2 Jul 1, 2020

elorzafe left a comment

elorzafe Jul 1, 2020

j1mr10rd4n commented Jul 13, 2020

		## Setup cloud sync

		Synchronization between offline and online data can be tricky. DataStore goal is to remove that burden from the application code and handle all data consistency and reconciliation between local and remote behind the scenes, while developers focus on their application logic. Up to this point the focus was to setup a local datastore that works offline and has all the capabilities you would expect from a data persistence framework.


		For instance, when updating or deleting data, one has to consider that the state of the local data might be outdated in case the data syncrhonization process

		### Conlfict detection and resolution

		When concurrently updating the data in multiple places, it is likely that some conflict might happen. For most of the cases the default Auto-merge algorithm should be able to resolve. However, there are scenarios where the algorithm won't be able to solve and for those a more advanced option is available and will be described in details in the next section.

		<inline-fragment platform="android" src="~/lib/datastore/fragments/android/sync/40-clear.md"></inline-fragment>

		This is a simple yet effective example. However, in a real scenario you might want to optimize it and only call `clear()` when a different user `signedIn` in order to avoid clearing the database for a repeated sign-in of the same user.


		To write any data to the DataStore you can pass an instance of a Model to `DataStore.save()` and it will be persisted in offline storage. At this point you can use it as an item in a normal data store such as querying, updating or deleting. If you choose to later connect to the cloud the item will be synchronized using GraphQL mutations and any other systems connected to the same backend can run queries or mutations on these items as well as observe them with GraphQL subscriptions.
		To write data to the DataStore, pass an instance of a model to `Amplify.DataStore.save()`:

DataStore documentation revamp Part 2/2 #1903

DataStore documentation revamp Part 2/2 #1903

Conversation

drochetti commented Jun 3, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

drochetti Jun 4, 2020 • edited Loading

Choose a reason for hiding this comment

drochetti Jun 4, 2020 • edited Loading

Choose a reason for hiding this comment

drochetti Jun 4, 2020 • edited Loading

Choose a reason for hiding this comment

lgtm-com bot commented Jun 15, 2020

lgtm-com bot commented Jun 16, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

elorzafe left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

j1mr10rd4n commented Jul 13, 2020

drochetti commented Jun 3, 2020 •

edited

Loading

drochetti Jun 4, 2020 •

edited

Loading

drochetti Jun 4, 2020 •

edited

Loading

drochetti Jun 4, 2020 •

edited

Loading