This is used when we refer other stream to get some of the attributes based on some condition. Therefore for example, if we keep quasi static data or reference data in another stream and refer that stream at run time to read some attribute values on some condition then this is useful. It has more usage than simply just referring as you explore.

We can use it to refer attributes in other stream at run time,

OR

Refer the same stream for some useful computations [ we will see this in detail ]

"refr":[
   {
      "name":"myrefr1",
      "iatr":[
         "r"
      ],
      "stat":1,
      "rstm":"s2",
      "ratr":[
         "p1"
      ],
      "jqry":{
         "cond":[
            "f"
         ],
         "opnm":"ATTR",
         "args":[
            "f"
         ]
      }
   },
   {
      "name":"myrefr2",
      "iatr":[
         "s"
      ],
      "stat":2,
      "rstm":"s2",
      "ratr":[
         "p2"
      ],
      "jqry":{
         "cond":[
            "f",
            "g"
         ],
         "opnm":"FIXED",
         "args":[
            "87",
            "240.9"
         ],
         "cmp":[
            "EQ",
            "LT"
         ]
      }
   }
]

Let's look at each one now at a time

{
   "name":"myrefr1",
   "iatr":[
      "r"
   ],
   "stat":1,
   "rstm":"s2",
   "ratr":[
      "p1"
   ],
   "jqry":{
      "cond":[
         "f"
      ],
      "opnm":"ATTR",
      "args":[
         "f"
      ]
   }
}

This tells that the stream (for which it's defined, we will see that in a moment), should refer the other stream “s2” and join on the given condition (explained right below), and then pick p1 and name it r and store it in the current stream.

So in simple sense:

  1. join this stream with "rstm" stream , using jqry s1.f = s2.f
  2. if successful, read "ratr" "p1"
  3. store "p1" value in this stream with attribute name "r", i.e. rename "p1" as "r1" in this stream.

Now, before we go to the other details of the topic "refr", review the "jqry" part here; jqry: jqry (join query) defines condition to join two streams. The structure for jqry is as follows:

"jqry":{
    "cond":[
        "f",
        "g"
    ],
    "opnm":"FIXED",
    "args":[
        "87",
        "240.9"
    ]
}
"jqry":{
    "cond":[
        "f",
        "g"
    ],
    "opnm":"ATTR",
    "args":[
        "f",
        "g"
    ]
}
"jqry":{
    "cond":[
        "f",
        "g"
    ],
    "opnm":"ATTR",
    "args":[
        "f",
        "g"
    ],
    "cmp":[
        "EQ",
        "NE"
    ]
}
"jqry":{
    "cond":[
        "a",
        "b"
    ],
    "opnm":"myrule2",
    "args":[
        "a",
        "b"
    ]
}

It joins two streams equating the values of one stream with the other, or the values of one stream with fixed ones. Here the "args" is either value from this stream or fixed value, which get compared with joining stream. The "rstm" stream defines which is the joining stream in the "join". The last one also provides the how to compare the values, here it says s2.f = s1.f and s2.g != s1.g. We could also have GT, GTE, LT, LTE, NE. Please look at joinfor more information.

The "opnm" or "opid" here tells where the argument is attribute value or a fixed value itself.

Let's look at the other item

{
    "name":"myrefr2",
    "iatr":[
        "s"
    ],
    "stat":2,
    "rstm":"s2",
    "ratr":[
        "p2"
    ],
    "jqry":{
        "cond":[
            "f",
            "g"
        ],
        "opnm":"FIXED",
        "args":[
            "87",
            "240.9"
        ],
        "cmp":[
            "EQ",
            "LT"
        ]
    }
}

Here, join happens with the fixed values, i.e. other stream attributes (f, g) comapred with 87 and 240.9

  1. join. s2.f = 87 and s2.g < 240.9
  2. select "p2" val and store that in the key "s" in this stream etc…

While refr (referring) is generally done for two normal streams (input stream, filter stream or joined stream), but in some cases we would like to also refer a entity stream, which contains long term statistics for a given attribute. To do so, we would have a minor change in the syntax.

So, let's say I have a visitor stream, which is adding statistics for page view in entity stream. And from 'order' stream, I would like to refer to the 'count' of page views for a given visitor. Here is how we would define the refer.

{
   "name":"myrefr2",
   "iatr":[
      "npage_view",
      "nsales_avg",
      "nsales_stdd"
   ],
   "rstm":"page_view_stream",
   "ratr":[
      "pageviews.cnt",
      "sales.avg",
      "sales.stdd"
   ],
   "jqry":{
      "cond":[
         "visitorid"
      ],
      "opnm":"ATTR",
      "args":[
         "visitorid"
      ]
   }
}

We are referring to page_views.cnt = count of page_views statistics.