Objection.js: Clarification of GraphUpsert options?

[einnjo]

I'm having a hard time working out how the different GraphUpsert options work together. Is anybody else having this problem? Would it be worthwile to change the documentation to make it clearer?

These are the current available options:

| | |
------ | ------
relate | If true, relations are related instead of inserted.
unrelate | If true, relations are unrelated instead of deleted.
insertMissing | If true, models that have identifiers and are not found, are inserted. By default this is false and an error is thrown.
update | If true, update operations are performaed instead of patch when altering existing models, affecting the way the data is validated.
noInsert | If true, no inserts are performed.
noUpdate | If true, no updates are performed.
noDelete | If true, no deletes are performed.
noRelate | If true, no relates are performed.
noUnrelate | If true, no unrelate operations are performed.

Its gets even more complex if you take into account the different types of relations these act on: Model.BelongsToOneRelation, Model.HasOneRelation, Model.HasManyRelation and Model.ManyToManyRelation.

These are the main issues that are not clear to me after reading the documentation:

• What are the default values for all of these options? Only insertMissing specifies a default value.
• How do unrelate/noUnrelate, relate/noRelate, update/noUpdate, insertMissing/noInsert work together?

[koskimas]

The default is false for all of them. By default upsertGraph method patches the objects that have an id, inserts objects that don’t have an id and deletes all objects that are not present.

noUpdate, noDelete, noRelate and noUnrelate are mainly useful for disabling an operation for a subset of relations.

Here I'd like to use relate instead of insert for all relations, but I'd like to disable the behaviour for movies:

Person.query()
  .upsertGraph({
    id: 1,
    movies: [movie1, movie2],
    pets: [pet1, pet2, pet2]
  }, {
    // Try to relate new relations if they have id's.
    relate: true,
    // But do nothing for new movies.
    noRelate: ['movies'] 
  });

Here I'd like to insert new and patch existing, but ignore missing relations instead of deleting them:

Person.query()
  .upsertGraph({
    id: 1,
    movies: [movie1, movie2],
    pets: [pet1, pet2, pet2]
  }, {
    noDelete: true
  });

update is poorly named. It only means
use update() method instead of patch() method.
I can see how that can cause confusion. noUpdate means the same as noRelate or noInsert as in
don't patch/update these relations (or any if true is given).

upsertGraph is complex as hell, and writing documents is difficult. I'd be more than happy to accept a PR that makes this all clearer.

[koskimas]

Did this clarify things for you? Do you have any suggestions on how to improve the docs?

[koskimas]

Closed because there was no response from the issuer.

[leonaves]

Is there any difference between unrelate and noDelete?

[koskimas]

@leonaves Yes, a big difference. noDelete is just used for disabling delete or unrelate for some items, or alltogether. When noDelete is given, neither unrelate nor delete is done to the affected items.

[leonaves]

Really? So, for example, setting noUnrelate to true and noDelete to true is the same as just setting noDelete as noDelete encompasses noUnrelate’s functionality?