Documentation for Jsonata usage in common Node-RED nodes

Core Development Feature Requests
,
1

I'm using Node-RED more and getting better with Javascript and using the Function Node. I have discovered by trying Jsonata on a very limited basis. NOW with recent improvements to the basics available in Node-RED there is probably a way to use the available resources to limit the "Function" Nodes and do very similar, more efficient programming using Jsonata inside the core nodes where available.

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.

  1. What Jsonata is/is not
  2. Things you can do with Jsonata in core nodes. Target functionalities
    a . Change Node
    b. .. ???
  3. simple expressions and how to use variables
    a. node
    b. flow
    c. global
  4. Pitfalls, fallacies / things that you cannot/ should not do with Jsonata Things to avoid.
  5. ...
2 Likes
2

Generally (if not always) using javascript in a Function node will be more efficient (in terms of CPU usage) than JSONata in a core node.

1 Like
3

Like Node-RED itself, JSONata can be a very quick and convinient way to either restructure JavaScript object/array data (its original purpose, similar to what XLST does for XML data structures). It has also become a way of very quickly adding some dynamic output to a message without the need to drop into JavaScript - very helpful for nodes that want some dynamic input (e.g. a random number, a date calculation, etc).

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.

My approach is that if I can't work out a JSONata formula in 5 minutes, I'll switch to JavaScript. But then I'm very familiar with coding and JavaScript. Ultimately though, if the "cure" is worse than the problem, it is the wrong tool. People feel the same way about other domain-specific languages such as Regular Expressions and XLST of course, SQL too.

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.

4

@TotallyInformation and @Colin,

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.

image

Context is "flow variable" value to Jsonnata.

And applying it too flow / global context variables.
image

I had to find this from another question regarding environment variables and jsonata.

5

@Colin ,
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!

Kindest Regards,

6

You can always "pay it forward" and create a PR on the documentation! :grin: 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.

7

@TotallyInformation ,
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...

1 Like
8

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 :slight_smile:

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.

1 Like
9

I am almost never using function nodes - instead I am using Jsonata in change nodes.

The benefits are:

  1. declarative description
  2. you can easily validate/test your expression using the jsonata test tab
  3. very powerful (the jsonata expression in most cases will be much smaller than corresponding javascript).

Disadvantages:

  1. 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).
  2. not always easy to write more complex jsonata query. It is a skill you need to acquire and maintain.
  3. some (mathematical) functions are missing (sin, cos, atan2,....)
  4. outputting a string with a local timestamp (taking daylight savings into account) is not that easy (but possible).

Pitfalls:

  1. 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.

Tips:

  1. 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.
2 Likes
10

This topic was automatically closed 60 days after the last reply. New replies are no longer allowed.