There may be many like me that do not use Jsonata enough to be fluent, but may benefit and leverage the resources already available and embedded.
Can you provide a topic dialog on usage/examples and a Guide on efficient, effective use of Jsonata expressions in the nodes that can use Jsonata expressions.
What Jsonata is/is not
Things you can do with Jsonata in core nodes. Target functionalities
a . Change Node
b. .. ???
simple expressions and how to use variables
Pitfalls, fallacies / things that you cannot/ should not do with Jsonata Things to avoid.
What it is not is terribly efficient since it has a lot of overheads - again rather like Node-RED itself. (Actually of course, Node-RED is pretty good considering everything that it provides. But still, if you wanted scaled efficiency, you would use something else).
Since it is a built-in capability of the Typed Input field, it is available for any node that wants to implement it. For example, I recently added it to the uib-element and uib-update nodes in uibuilder and while it was a bit of a pain to program, the results are incredibly useful. In core nodes, inject, change, switch - I'm sure there may be others, all have it available.
That is in the documentation.
This is perhaps somewhat personal since different people have different levels of affinity for the sometimes excessively "sideways" thinking required for JSONata. There is also a pretty steep learning curve for the details.
I now mostly find myself using it for creating dynamic inputs as mentioned earlier. The ability to do a quick calculation with multiple input properties and format the output is great and is the equivalent of a "math" node that you might find in other flow-style environments.
But, there are limitations even there. For example, the lack of trig functions (sin, cos, tan, etc) limit what you can easily do.
Thank you both for taking the time to respond. Excellent "customer service".
However, the request is to take much of your response and apply it to the Documentation. That way we as users can get these questions answered by looking it up in the place where you most likely find it. I looked and found literally a link to the Jsonata web page. THAT'S GREAT!, but the Jsonata web page is not geared toward Node-RED. Here is what I had to get from looking up past entries which were NOT in the documentation..
Context is "payload" value to Jsonnata.
Context is "flow variable" value to Jsonnata.
And applying it too flow / global context variables.
I had to find this from another question regarding environment variables and jsonata.
My reference to "efficient" is referring to making the overall programming flow page less complex. In some cases Jsonata may be many more nodes if you are exclusively using anything other than Function nodes. I do not think that is efficient flow "writing". And using a Function node for everything is not efficient either.
You may have a case where you add Jsonata in a sequence in a Change Node which will easily take care of the programming you want in the message flow. Then you can dispense with Function nodes, or reduce them because the logic is available there in an existing Change Node.
I guess the thought I'm trying to convey is node layout "consolidation" and not necessarily code efficiency. Also, I found it helpful to execute logic where I did not know I could before. That's pretty cool!
Inject and Switch nodes with calculation ability. OK thats pretty cool too!
You can always "pay it forward" and create a PR on the documentation! It would be reviewed by the devs so you don't need to worry if you don't quite get it right. It just that many of us have a lot of other things both for Node-RED and elsewhere that we are working on and while we can find a couple of minutes to do a response, finding time to submit some Node-RED documentation changes is a much harder ask unfortunately. Of course, you may well be in a similar situation but the more people who help out, the easier it becomes for all of us.
That's not a problem. What is the best format? Word? or Wordpad? or something else?
I was also thinking that if you or someone that has experience (that I was asking for) could help supply the general outline. That is what that was, An example of items discussed in the body of what I am asking for regarding Jsonata relating it to Node-RED.
I may do a brief training in Jsonata for "Learning hours" for credits at work.
I would need some assistance on something within scope of a good example of what can be done. I don't want to make it complicated, but give something a bit more than calculating deg C or INC a variable... and a good application of such for use in a Switch or the Change noode. Useful to spark ideas in the user to understand what you can do. etc...
When you take a clone of the documentation repository, you will see that all of the pages are, I think , in Markdown format which is very easy to edit as it is text based.
If you read the other documentation pages, you will get a feel for the style. If in doubt, ping @knolleary
As mentioned, if it isn't quite right, it will get reviewed when you submit a PR anyway, it is common to need to do last minute tweaks in any case. Nick may also have an idea about the best place to link in the info if it won't conveniently fit on an existing page.
I am almost never using function nodes - instead I am using Jsonata in change nodes.
The benefits are:
you can easily validate/test your expression using the jsonata test tab
performance (but note that it must have been years ago that I have rewritten part of my flows due to poor performance of a jsonata query - so in most cases performance won't be an issue and if so then you only need to rewrite those jsonata query causing the performance problem).
not always easy to write more complex jsonata query. It is a skill you need to acquire and maintain.
some (mathematical) functions are missing (sin, cos, atan2,....)
outputting a string with a local timestamp (taking daylight savings into account) is not that easy (but possible).
When manipulating arrays, it is important to consider the border cases where the output array consists of only 1 element or no element. As your jsonata query might instead of returning [a] or , return a or nothing which is often not expected by the remaining part of your node-red flow. This issue can be overcome by adapting the jsonata query a bit.
You can't test jsonata expression containing $flowContext() or $env() in the test tab. To overcome this problem you can in the same change node first assign those flow context variables and env variables to local variables and use these local variables in your jsonata expression.