spec out insert / update format about franca-js HOT 10 OPEN

on branch feature/insert-update.

cc @vinnie-pepi @fanchen1988 @ruichao

I've documented an uncomplete spec here:
https://github.com/chenguo/franca-js/blob/feature/insert-update/docs/query-insert.md

Please flesh out the spec, implement, and add tests.

from franca-js.

I added some doc into the write doc. I mainly modified:
0.) Rename the doc name from query-insert to query-write
1.) Add some examples on special operators and behaviours on Update
2.) Remove update key in Upsert and put the payload into upsert key, 'cause it's upsert already, it's redundant and confusing if we still set {upsert: true}. In addition, the upsert action is binded to INSERT in relational db, so put payload in upsert is better than update.

There must be something that need improvements or more specific description, but before going on, there's still something that I need to figure out:
0.) Due to different behaviours and parameters, I found it's hard to unify update interface for different databases. Like Postgres updates all matched rows while Mongo doesn't by default. And Postgres update implicitly includes SET whereas Mongo must explicitly put payload into $set key. So do you think it's ok that users writes different format for Mongo and Postgres, or we should set different update interface, like updateOne, updateMulti, replaceOne and replaceMulti(these 2 should be invalid for relational db)?
1.) I don't quite understand your last sentence:

For Mongo, it may be optional depending on the contents of the ```update``` payload. This is still under consideration.

In what condition the upserts=true would be optional in upserts mode?

from franca-js.

Add some examples on special operators and behaviours on Update

I expect $set to be the default behavior, so I don't want an "$set" nested payload. If the user wants to do a full payload reset they can either 1) set all the fields or 2) delete and insert a new row.

Remove update key in Upsert and put the payload into upsert key

I see your reasoning, sure. Partially I thought having the key be update and having upsert: true in options would make the translation code simpler, but I think you're right in that we should prioritize making the interface easy to understand.

So do you think it's ok that users writes different format for Mongo and Postgres

No, I'd prefer to minimize special casing of different DBs. Make it harder to write and harder to use if we do special casing.

I'm ok not supporting replaceOne and replaceMulti for Mongo. It's easy enough to get around it.

And Postgres update implicitly includes SET whereas Mongo must explicitly put payload into $set key

I like the implicit $set, it makes the most sense for an update.

I don't quite understand your last sentence:

I think I meant the query is optional and can be inferred, but I've forgotten what my train of thought at the time was. It was likely about the core differences between a SQL upsert and a Mongo upsert though, which will be tricky to resolve:

In SQL you try to insert a payload, and collisions are implicit based on the primary key(s) of the existing rows and the new rows. In Mongo this is flipped; you explicitly state (via a query) the rows to match to apply the update to.

It's this implicit vs explicit collision we need to reconcile.

from franca-js.

@chen-factual I'v modified the spec, could you help me have a look at it? I try to unify the update/upsert interface behaviour among different backends, like implicit $set, and only update the first row by default unless got a {"multi": true} in options. Also I think the {"type": "RAW"} should also be supported.

Let me know your thoughts

from franca-js.

Actually for Mongo I like multi: true by default. I've personally never not used multi: true, what's your experience been like?

Type: RAW should be supported, thanks for thinking of that. In fact RAW was included originally specifically to handle these DB specific cases, like Mongo's $set.

from franca-js.

Ok, like I said during the meeting, I prefer multi. I just realised that I omitted the Delete operation, I'll add it along with the multi modification later.

from franca-js.

@chen-factual I updated the default update action to multi, and use justOne=true to update just one row. Also I added the Remove operation. Here's the diff with master branch. https://github.com/chenguo/franca-js/compare/feature/insert-update

from franca-js.

are we calling it remove because delete is a javascript keyword? :)

Can we change the "justOne" flag to "singleRow"? It's a bit more explicit
in the subject.

On Sat, Apr 16, 2016 at 6:10 AM, FanChen [email protected] wrote:

@chen-factual https://github.com/chen-factual I updated the default
update action to multi, and use justOne=true to update just one row. Also
I added the Remove operation. Here's the diff with master branch.
https://github.com/chenguo/franca-js/compare/feature/insert-update

—
You are receiving this because you were mentioned.
Reply to this email directly or view it on GitHub
#4 (comment)

Factual Confidential Information
This email contains Factual confidential information and is only for use by
the intended recipient under the terms of a non-disclosure agreement or
other binding confidentiality terms. If you've gotten this email in error,
please let the sender know of the mistake and delete the email
immediately.

from franca-js.

Ok, I changed the wording stuff. @chen-factual do you think we have other things need to spec out before we start implementation?

from franca-js.

I'm of the opinion you can't plan for a lot of things until you get into the thick of it. I think we have enough of a solid foundation to start implementing. Thanks @fanchen1988

from franca-js.