datastore: Support commit mutation methods on top level of dataset

[ryanseys]

Should support commit mutations as top level methods in dataset.
It just makes sense:

dataset.upsert(key, properties, function(err, result) {});
dataset.update(key, properties, function(err, result) {});
dataset.insert(key, properties, function(err, result) {});
dataset.insertAutoId(key, properties, function(err, result) {});
dataset.delete(key, function(err) {});

[stephenplusplus]

+1. Users would probably appreciate explicit control.

And bonus, we support delete already!

[stephenplusplus]

What's the difference between insert and insertAutoId? Will calls to insert with incomplete keys throw an exception? Will calls to insertAutoId throw if there are complete keys?

[ryanseys]

From the docs: "To have the Datastore assign a numeric ID automatically, omit both the name and id fields and place the entity in the insertAutoId (JSON) or insert_auto_id (protocol buffers) field of the mutation"

[stephenplusplus]

Sure, but how do you propose we handle our implementation? (The last two questions)

[ryanseys]

Will calls to insert with incomplete keys throw an exception?

If we are missing required information from the key, return an error in the callback (don't throw).

Will calls to insertAutoId throw if there are complete keys?

Again, no throwing, use the callback to return errors. An error will occur if they provide too little information, not too much.

[ryanseys]

We can assume that if they call insertAutoId, then we just include the information relevant to that call i.e. ignore the name and id fields if they are specified.

[stephenplusplus]

I think I'm starting to think differently towards this proposal. I like the simplicity of our API. I think that's the point of making this nice abstraction. If we allow direct methods, we give the user too many options imo, and would be better recommending they use another library/combination of libraries for lower level access.

[ryanseys]

I don't see these as "low level access" but fundamental actions you commit to the data in the datastore. The problem with the current code-generated library is it's too high level. You commit a big json blob and that's interpreted as commands including these mutations.

I'm proposing we extract those commands and give them to the user. Those 5 mutations are all I found. I don't think it's asking for much and it shows the developer what they can/cannot do with the datastore from a storage point of view (querying is a different issue).

[stephenplusplus]

fundamental actions you commit to the data in the datastore.

We provide these actions. upsert, insert, insertAutoId, and update all result in an entity being inserted or updated, and these are all handled with save. I don't consider save to be doing much magic. You get the results you intend, based on what you provide.

upsert: "I want to update this entity if it exists, otherwise create one."
save: "give me a complete key or incomplete key"

insert: "I want to insert this entity into the datastore."
save: "give me a complete key or incomplete key"

insertAutoId: "I want to create this entity and have an id generated for me."
save: "give me an incomplete key"

update: "I want to update this entity"
save: "give me a complete key"

So, I don't consider save a limiting factor. I think we would end up overwhelming the user by providing too many methods.

I'm proposing we extract those commands and give them to the user.

Maybe we can show the user more explicitly in our documentation how save works based on what it is given.

[ryanseys]

I didn't know save was doing all this. Yeah, an easy way to better the documentation is inline provide a bunch of complete / incomplete keys and what their effect on the datastore will be (i.e. create, update, autoId, etc)