retrieve [Macro]

Purpose

The retrieve macro is used for retrieving facts from a knowledge base.

Syntax

retrieve variables query &key context generators

Arguments

The variables argument is a symbol or list of symbols each beginning with the character ?.

The query argument is an expression in the Loom query language (see Remarks below). This language has the expressive power of the first-order predicate calculus.

The context argument is the name of the context in which query is to be evaluated.

The generators argument is a list containing one or more of the terms in query. The Loom query optimizer will prefer these terms when selecting generators for the query variables. Normally, generators are terms that are expected to generate few instances.

Value

If variables is a symbol, the retrieve macro returns a list of values satisfying query. If variables is a list, a list of tuples is returned, where each tuple contains as many values as there are output variables.

Remarks

  query-expr ::= 
      ( {:AND | :OR} query-expr+ ) | 
      ( {:NOT | :FAIL} query-expr ) | 
      ( :IMPLIES query-expr query-expr ) | 
      ( {:FOR-SOME | :FOR-ALL} ( ?Var+ ) query-expr ) | 
      ( :COLLECT ( ?Var ) query-expr ) | 
      ( concept instance ) | 
      ( relation instance+ value ) | 
      ( :SAME-AS instance instance ) | 
      ( :SUBSET instance instance ) | 
      ( :PREDCALL LispPredicate value+ ) | 
      ( :ABOUT instance about-clause* )

  about-clause ::= 
      concept | 
      ( concept ) | 
      ( relation value ) | 
      ( :FILLED-BY relation value+ ) | 
      ( {:AT-LEAST | :AT-MOST | :EXACTLY} Integer relation ) | 
      ( {:ALL | :SOME | :THE} relation concept )

The query expressions appearing in the query argument above have the following syntax: Each about-term in a query :about clause has the form:

The query-expression operators have the following semantics:

If Q = (:and Q1...Qn), Q is true if Q1...Qn are all true.
If Q = (:or Q1...Qn), Q is true if at least one of Q1...Qn is true.
If Q = (:not Q1), Q is true if Q1 is not true.
If Q = (:fail Q1), Q is true if Loom cannot prove that Q1 is true.
If Q = (:for-some (?X1...?Xn) Q1), Q is true if there are bindings for ?X1...?Xn that cause Q1 to be satisfied.
If Q = (:for-all (?X1...?Xn) (:implies Q1 Q2)), Q is true if all bindings of ?X1...?Xn that satisfy Q1 also satisfy Q2.
If Q = (:collect ?X Q1), Q returns the values V1...Vn such that Q1 is satisfied when ?X is bound to each Vi.
If Q = (C I), Q is true if I is an instance of concept C.
If Q = (R I V), Q is true if V is a filler of role R on instance I.
If Q = (R I1...In), Q is true if the tuple <I1...In> is in the n-ary relation R
If Q = (:same-as V1 V2), Q is true if values V1 and V2 are equivalent.
If Q = (:subset V1 V2), Q is true if V1 and V2 evaluate to sets of values, and V1 is a subset of V2.
If Q = (:predcall P V), Q is true if application of Lisp predicate P to value V returns true.
If Q = (:about I C) or (:about I (C)), Q is true if I is an instance of concept C.
If Q = (:about I (R V)), Q is true if the filler of role R on instance I is V.
If Q = (:about I (:filled-by R V1...Vn)), Q is true if every value Vi is a filler of role R on instance I.
If Q = (:about I (:at-least K R)), Q is true if instance I has at least K fillers of role R. The :at-most and :exactly operators have corresponding semantics.
If Q = (:about I (:all R C)), Q is true if all fillers of role R on instance I are instances of concept C. The :some and :the operators have corresponding semantics.

A concept, relation, or instance may be either a symbol that names a Loom object, or a variable beginning with the character ?. An instance may also be a constant or a formula, where a formula is a list of the form (relation instance).

Any ?-variable not bound in variables, or in the variables of a :for-some, :for-all, or :collect clause, is assumed to be bound externally. The value of an external ?-variable should be a Loom object, i.e., a concept, relation, or instance, rather than the name of such an object.

The :filled-by-list operator cannot be used in the :about clause of a query. The Loom Grammar at the end of this manual is too general in this respect.

Concepts and relations referenced by name in a query must be defined at the time the query is compiled. Instances referenced by identifier must exist at the time the query is executed.

Examples

(retrieve ?x (Artist ?x)) ==> (|I|JOE \ldots) 
(retrieve ?x (age Joe ?x)) ==> (39) 
(retrieve (?x) (age Joe ?x) :context cl-user-theory) ==> ((39)) 
(retrieve ?x (max (age (child Joe)) ?x)) 
(retrieve ?x (distance Paris Rome ?x)) 
(retrieve (?x ?y) (wife ?x ?y)) ==> ((|I|JOE |I|SUE) (|I|FRED |I|MARY)) 
(retrieve ?x (:and (Woman ?x) (Senator ?x)) :generators ((Senator ?x))) 
(retrieve ?x (:and (pet Joe ?x) (:not (Dog ?x)))) 
(retrieve ?x (:and (Artist ?x) (:fail (:or (French ?x) 
                                           (resides ?x France))))) 
(retrieve ?x (:and (Writer ?x) (:for-some ?y (:and (author ?y ?x)  
                                                   (Best-Seller ?y))))) 
(retrieve ?x (:and (Writer ?x) (:for-all ?y (:implies (author ?y ?x)  
                                                      (Best-Seller ?y))))) 
(retrieve ?x (:and (Salesman ?x) (:same-as (home ?x) (office ?x)))) 
(retrieve ?x (:and (Salesman ?x) (:subset (customer ?x) (customer Joe)))) 
(retrieve ?x (:and (age (child Joe) ?x) (:predcall \#'oddp ?x))) 
(retrieve ?x (:about ?x Man (:at-least 2 child) (:exactly 0 son))) 
(retrieve ?x (:about ?x Man (:all child Female) (:some child Teen-Ager))) 
(retrieve ?x (:about ?x Man (:filled-by daughter Mary Sue))) 
(setq ?C (fc Artist) ?R (fr friend) ?V (fi Joe)) 
(retrieve ?x (:and (?C ?x) (?R ?x ?V) (:about ?x (:all ?R ?C))))