Documentation for GraphQL operations

[Tails]

I am exploring the GraphQL module. However, I am somewhat confused about the use of the update_tree and merge_tree mutation commands. They seem to be doing the same. What is the difference?

[zshipko]

They are pretty similar, but the main difference is that merge_tree calls the user-defined merge operation and update_tree will simply add/remove values.

For example, if you are using the JSON content type with a merge operation that is used to combine object values then calling merge_tree and update_tree will behave differently when the same key is present in both the new and old trees. In this case merge_tree will merge the objects with the same keys and update_tree will replace them with the new value.

I'm happy to provide a more concrete example if the difference is still unclear!

[Tails]

Thank you for this. I think I am starting to get the difference, though (GraphQL) examples for each operation would help in the tutorial. Also you mentioned the availability of the json and json_value content types. I now see they are mentioned in your tutorial as well, but only in the context of OCaml development.

Am I correct that the 'content' key of irmin.yml would have to be set to 'json' and 'json_value' respectively to configure the store with those content types? And that if I would want to be able to use merge_tree on non-leaf node paths, I would need json_value?

Lastly, how do you push a JSON object into the store? The GraphQL types do not seem to support a nested value argument, nor does passing a JSON object as string result in a tree being set (when using content: json_value). Can nodes using GraphQL only be set by serializing the JSON into a list of TreeItems?

[zshipko]

I think I am starting to get the difference, though (GraphQL) examples for each operation would help in the tutorial. Also you mentioned the availability of the json and json_value content types. I now see they are mentioned in your tutorial as well, but only in the context of OCaml development.

Thanks, I will work on adding some of this information to the tutorial!

Am I correct that the 'content' key of irmin.yml would have to be set to 'json' and 'json_value' respectively to configure the store with those content types?

I noticed that json_value was not actually a valid option and have added it to the list (see #694). Using json will restrict values to JSON object and using json_value will allow values to contain any JSON value (after that PR is merged).

And that if I would want to be able to use merge_tree on non-leaf node paths, I would need json_value?

I'm not exactly sure what you're asking here, but you should be able to use merge_tree on non-leaf node paths regardless of the content type.

Lastly, how do you push a JSON object into the store? The GraphQL types do not seem to support a nested value argument, nor does passing a JSON object as string result in a tree being set (when using content: json_value)

This is also due to json_value not being a valid option. After that modification you're able to pass JSON values encoded as a string using the value argument.

[Tails]

Aha, excellent! I'll await the PR and continue. Thank you!