Objection.js: upsert/insert graph documentation doesn't mention #dbRef functionality

[kibertoad]

It is currently pretty impossible to figure out using just official documentation how to insert/upsert references to existing entries, without googling up GitHub issues like this:
https://github.com/Vincit/objection.js/issues/441

It would be super-helpful to have at least a brief mention that using prop defined in dbRefProp is the way to relate to existing entities.

[heisian]

This line is in the documentation under the "Upsert Graphs" section, second paragraph:

By default upsertGraph method updates the objects that have an id, inserts objects that don’t have an id and deletes all objects that are not present. This functionality can be modified in many ways by providing UpsertGraphOptions object as the second argument.

I think that's pretty clear, but perhaps not prominent enough?

I personally avoid insert/upsert graph at all costs.

[kibertoad]

@heisian It doesn't explain how you can use upsert functionality to merely pass a bunch of ids without any actual attributes (to only update relationships, not entities).

[heisian]

@kibertoad You mean just updating the records in a pivot/intermediate table? With extra fields? or? Sorry, I don't understand the use-case.

[kibertoad]

Imagine you have Parent table and Children table, with Parent hasMany relationship to Children. Consider that you have setChildren method that passes list of ids for a parent, with Children being created in a different time and place, only linked to Parents later. (UI-wise you would have separate ui for creating parents and children, and separate ui to tick children that belong to selected parent)

[koskimas]

Well, it is mentioned, but only in one example in this section. I think, in most cases, you can live without #dbRef by using the relate option (both insertGraph and upsertGraph support it now). I'd merge a PR for a better #dbRef documentation though.

[kibertoad]

Awesome, I'm finally moving to an apartment with actual table today, hopefully will be able to produce PR for documentation.

[demisx]

I personally avoid insert/upsert graph at all costs.

@heisian Can you please share more info why you think these should be avoided? What are the side effects or any negatives?