Document :exists

[eraserhd]

No description provided.

[mrrodriguez]

👌

[WilliamParker]

I don't think this is quite right, at least as I read it (maybe others read it differently) - I think you can just change the sentence about unbound variables to be about binding groups. To be clear, this behaves the same way as accumulators for both unbound values and values bound by a prior condition, since it is just syntax sugar for an accumulator.

clara.test-rules> (defrecord LocationRecorded [location])
clara.test_rules.LocationRecorded
clara.test-rules> (defrule the-rule
                    [WindSpeed (= ?loc location)]
                    [:exists [Temperature (= ?loc location)]]
                    =>
                    (insert! (->LocationRecorded ?loc)))
#'clara.test-rules/the-rule
clara.test-rules> (defquery the-query [] [?fact <- LocationRecorded])

Example:

clara.test-rules> (-> (mk-session [the-rule the-query] :cache false) 
                      (insert (->Temperature 0 "LGW")
                              (->Temperature 5 "LGW")
                              (->Temperature 0 "LHR") 
                              (->WindSpeed 20 "LGW") 
                              (->WindSpeed 20 "LHR"))
                      fire-rules
                      (query the-query))
({:?fact #clara.test_rules.LocationRecorded{:location "LGW"}} {:?fact #clara.test_rules.LocationRecorded{:location "LHR"}})

This fires once per tuple of (1 WindSpeed, all temperatures such that the temperature has the same location as the WindSpeed fact) with the restriction that the second element of the tuple is nonempty.

[eraserhd]

The term "binding group" doesn't appear anywhere else on the site, and I'm not sure that's intuitive. I'm also trying to describe it concisely without appealing to accumulators, as it is trying to model existential quantification, which should be describable without accumulators. (This documentation appears before accumulators in the site flow.)

The point about "unbound" is fair though. That's over-specific. So, how can we describe a "binding group" concisely in plain English? Do we necessarily have to introduce a term? "the set of variables mentioned in the clause"? That doesn't work because of other tests. Or simply "bindings"?

I think an example would help. I'll update and think about phrasing.

[WilliamParker]

Thanks for keeping me honest about "binding group" - it appears in some of the internals and is a useful construct there but perhaps not from the POV of documentation. Perhaps something like "distinct variable bindings used in the condition"? Agreed with your suggestion of an example - you could add a few examples to the clara-examples project and link there from the site. That said, this doesn't need to be perfect at first, the existing state being no docs at all. Accurate albeit incomplete docs are still better than no docs IMO.

"Do we necessarily have to introduce a term? "the set of variables mentioned in the clause"? That doesn't work because of other tests.

I'm not sure what you mean by other tests, could you clarify perhaps with an example?

Or simply "bindings"?

Yes, perhaps something simple is the way to go here while including a link to examples with more rigorous examples. A lot of users probably aren't going to get into the more complicated cases of this anyway. Maybe

Variables are treated the same as in [accumulators](/docs/accumulators/); the :exists condition will trigger once for each distinct set of variable bindings.

Note that I changed "rule" to "condition" in the above, since :exists could appear in both rules and queries, and more fundamentally bindings in following conditions in the same rule/query won't impact the way :exists works.