alf-shell 0.14.0 → 0.15.0

data/doc/man/eq.man

@@ -0,0 +1,29 @@
+.TH Eq
+.PP
+Equals to
+.SH Signature
+.PP
+.RS
+.nf
+eq(left: Alpha|AttrName, right: Alpha|AttrName) -> Predicate
+.fi
+.RE
+.SH Examples
+.PP
+.RS
+.nf
+eq(:city, 'London')
+.fi
+.RE
+.PP
+.RS
+.nf
+eq(:supplier_city, :part_city)
+.fi
+.RE
+.SH Description
+.PP
+This predicates checks whether two values are equal.
+.SH Implementation notes
+.PP
+This predicate is equivalent to \fB\fC->(t){ _left_ == _right_ }\fR\&.

data/doc/man/extend.man

@@ -0,0 +1,33 @@
+.TH Extend
+.PP
+Extends input tuples with derived/computed attributes
+.SH Signature
+.PP
+.RS
+.nf
+extend(operand: Relation, ext: TupleComputation) -> Relation
+.fi
+.RE
+.SH Examples
+.PP
+.RS
+.nf
+extend(suppliers,
+  big:   ->(t){ t.name.upcase },
+  small: ->(t){ t.name.downcase })
+.fi
+.RE
+.SH Description
+.PP
+Computes a relation which is the same as \fB\fCoperand\fR, except that each of
+its tuples has new attributes whose value is the result of evaluating the
+tuple expressions specified in \fB\fCext\fR\&.
+.SH Implementation notes
+.PP
+As of current Alf version, this operator cannot be translated to SQL code.
+In other words, all computations are done in ruby, which may seriously
+hurt performance.
+.PP
+Similarly, as \fB\fCextend\fR tends to be a showstopper during compilation, it is
+strongly recommanded to use it as high as possible in query expressions
+trees so as to delegate the largest possible query parts to data engines.

data/doc/man/frame.man

@@ -0,0 +1,60 @@
+.TH Frame
+.PP
+Aka limit/offset
+.SH Signature
+.PP
+.RS
+.nf
+frame(operand: Relation, order: Ordering, offset: Integer, limit: Integer) -> Relation
+.fi
+.RE
+.SH Examples
+.PP
+.RS
+.nf
+frame(suppliers, [:status, :sid], 0, 3)
+.fi
+.RE
+.PP
+.RS
+.nf
+frame(suppliers, [[:status, :asc], [:sid, :desc]], 1, 2)
+.fi
+.RE
+.SH Description
+.PP
+Computes a relation by restricting the tuples of \fB\fCoperand\fR to a particular
+frame. This frame can be easily remembered through the "skip \fB\fCoffset\fR,
+take \fB\fClimit\fR" mnemonic mean, provided \fB\fCorder\fR is a total order.
+.PP
+Formally, the frame is defined by those tuples whose ranking according to
+\fB\fCorder\fR is such that \fB\fCoffset <= rank < limit\fR\&. In other words, this
+operator is actually equivalent to the following definition:
+.PP
+.RS
+.nf
+def frame(operand, order, offset, limit)
+  allbut(
+    restrict(
+      rank(operand, order, :rank),
+      lte(offset, :rank) & lt(:rank, offset+limit)),
+    [:rank])
+end
+frame(suppliers, [:city, :sid], 2, 3)
+.fi
+.RE
+.PP
+As of current Alf version, for this operator to be semantically sound and
+deterministic, \fB\fCorder\fR MUST be a total order, that is, it must at least
+cover a candidate key. As of current Alf version, no error is raised if
+this is not the case but that might change in future versions.
+.SH Implementation notes
+.PP
+Contrary to the longer expression shown above, this operator compiles to
+\&'efficient' SQL (rank does not, so far) at the cost of having to provide a
+total order.
+.PP
+As the result is a relation and relations are not ordered by definition,
+the order in which tuples can be observed in the result (e.g. through
+explicit tuple iteration, casting to an array, json encoding) is NOT
+guaranteed to follow \fB\fCorder\fR\&.

data/doc/man/group.man

@@ -0,0 +1,51 @@
+.TH Group
+.PP
+Relation\-valued attribute
+.SH Signature
+.PP
+.RS
+.nf
+group(operand: Relation, attributes: AttrList, as: AttrName) -> Relation
+.fi
+.RE
+.SH Examples
+.PP
+.RS
+.nf
+group(suppliers, [:sid, :name, :status], :suppliers)
+.fi
+.RE
+.PP
+.RS
+.nf
+group(suppliers, [:city], :suppliers, allbut: true)
+.fi
+.RE
+.SH Description
+.PP
+Summarizes \fB\fCoperand\fR by all but the specified \fB\fCattributes\fR and groups the
+latter under a relation\-value attribute \fB\fCas\fR\&.
+.PP
+This operator could be formally defined as the following shortcut:
+.PP
+.RS
+.nf
+def group(operand, attributes, as)
+  extend(
+    allbut(operand, attributes),
+    as: ->(t){ project(matching(operand, 
+.BR Relation (t)), 
+attributes) })
+end
+group(suppliers, [:sid, :name, :status], :suppliers)
+.fi
+.RE
+.PP
+This operators supports an ALL BUT variant, through the \fB\fCallbut\fR option.
+When set to true, the operator keeps specified attributes and groups all
+remaining ones as a relation\-valued attribute.
+.SH Implementation notes
+.PP
+This operator does not compile to SQL so far. Contributions are welcome
+to provide it with a SQL compilation for SQL DBMSs that support this kind
+of feature (e.g. PostgreSQL with JSON data type)

data/doc/man/gt.man

@@ -0,0 +1,30 @@
+.TH Gt
+.PP
+Greater than
+.SH Signature
+.PP
+.RS
+.nf
+gt(left: Alpha|AttrName, right: Alpha|AttrName) -> Predicate
+.fi
+.RE
+.SH Examples
+.PP
+.RS
+.nf
+gt(:status, 20)
+.fi
+.RE
+.PP
+.RS
+.nf
+gt(:status, 30)
+.fi
+.RE
+.SH Description
+.PP
+This predicates checks whether a value (\fB\fCleft\fR) is greater than another
+one (\fB\fCright\fR).
+.SH Implementation notes
+.PP
+This predicate is equivalent to \fB\fC->(t){ _left_ > _right_ }\fR\&.

data/doc/man/gte.man

@@ -0,0 +1,30 @@
+.TH Gte
+.PP
+Greater than or equal to
+.SH Signature
+.PP
+.RS
+.nf
+gte(left: Alpha|AttrName, right: Alpha|AttrName) -> Predicate
+.fi
+.RE
+.SH Examples
+.PP
+.RS
+.nf
+gte(:status, 20)
+.fi
+.RE
+.PP
+.RS
+.nf
+gte(:status, 30)
+.fi
+.RE
+.SH Description
+.PP
+This predicates checks whether a value (\fB\fCleft\fR) is greater than or equal
+to another one (\fB\fCright\fR).
+.SH Implementation notes
+.PP
+This predicate is equivalent to \fB\fC->(t){ _left_ >= _right_ }\fR\&.

data/doc/man/intersect.man

@@ -0,0 +1,54 @@
+.TH Intersect
+.PP
+Logical AND
+.SH Signature
+.PP
+.RS
+.nf
+intersect(left: Relation, right: Relation) -> Relation
+.fi
+.RE
+.SH Examples
+.PP
+.RS
+.nf
+intersect(
+  restrict(suppliers, eq(:city, 'Paris')),
+  restrict(suppliers, gt(:status, 10)))
+.fi
+.RE
+.SH Description
+.PP
+Computes the relation as the set intersection of \fB\fCleft\fR and \fB\fCright\fR\&.
+.PP
+The \fB\fCleft\fR and \fB\fCright\fR relations must be intersect\-compatible, meaning that
+they must have same heading (type inheritance is partly supported through
+ruby's own type system, so that the actual behavior is slighlty more
+permissive).
+.SH Implementation notes
+.PP
+Unlike SQL, this operator ALWAYS remove duplicates. There is no way, in
+Alf, to compute \fIbags\fP of tuples and therefore no way to express something
+such as SQL's INTERSECT ALL.
+.PP
+It is sometimes idiomatic in Alf to use \fB\fCintersect\fR as a logical AND, as
+illustrated below. So far, the optimizer/compiler is not smart enough to
+translate the former into the latter (which is likely to have a better query
+when using faithful SQL compilation and available SQL DBMSs). Any patch is
+welcome here too!
+.PP
+.RS
+.nf
+intersect(
+  restrict(suppliers, eq(:city, 'Paris')),
+  restrict(suppliers, gt(:status, 10)))
+.fi
+.RE
+.PP
+is equivalent to
+.PP
+.RS
+.nf
+restrict(suppliers, eq(:city, 'Paris') & gt(:status, 10))
+.fi
+.RE

data/doc/man/join.man

@@ -0,0 +1,84 @@
+.TH Join
+.PP
+Natural join
+.SH Signature
+.PP
+.RS
+.nf
+join(left: Relation, right: Relation) -> Relation
+.fi
+.RE
+.SH Examples
+.PP
+.RS
+.nf
+join(suppliers, supplies)
+.fi
+.RE
+.SH Description
+.PP
+Computes the relation resuting from joining tuples from \fB\fCleft\fR and \fB\fCright\fR
+whose respective projections on common attributes are equal.
+.SH Implementation notes
+.PP
+Alf only support natural join for now. Other kinds of join can generally
+be computed through longer expressions. For instance, joining on attributes
+with different names requires some renaming first:
+.PP
+.RS
+.nf
+# suppose preferences has type Relation[supplier_id: String, ...]
+# suppose we want to join on suppliers.sid == preferences.supplier_id
+join(suppliers, rename(preferences, :supplier_id => :sid))
+.fi
+.RE
+.PP
+Cross joins can be computed through operands having no attribute in common.
+For instance, all pairs of supplier and part identifiers can be computed
+as follows:
+.PP
+.RS
+.nf
+pairs = join(project(suppliers, [:sid]), project(parts, [:pid]))
+.fi
+.RE
+.PP
+Non equi\-joins can be computed through a latter restriction. For instance,
+the (supplier, part) pairs not located in the same city:
+.PP
+.RS
+.nf
+ps = project(rename(parts, :city => :part_city), [:pid, :part_city])
+ss = project(rename(suppliers, :city => :supplier_city), [:sid, :supplier_city])
+pairs = join(ps, ss)
+project(restrict(pairs, neq(:part_city, :supplier_city)), [:sid, :pid])
+.fi
+.RE
+.PP
+As obviously demonstrated by the example above, such query is rather
+cumbersome to write and verbous. Future versions of Alf will come with
+useful shortcuts and new operators. In the mean time, don't forget that
+defining your own shortcuts and operators is easy! Don't hesitate to
+contribute them if of general purpose.
+.PP
+Last, natural join tends to be error prone; in particular, you must take
+care of common attributes of your design on which you do not want to join
+(such as \fB\fClatest_change\fR and \fB\fCdeleted\fR fields and the like). Renamings and
+projections are worth having at hand when joining.
+.PP
+Alternatively, shortcuts can be considered. A (advanced) example below:
+.PP
+.RS
+.nf
+# The following shortcut joins `left` and `right` on `wish` attributes
+# only. Other common attributes are simply projected away from `right`
+# before joining.
+def join_on(left, right, wish)
+  commons = left.attr_list & right.attr_list
+  join(left, allbut(right, commons - wish))
+end
+# observe here how part names have been discarded to avoid joining them
+# with supplier names (empty result guaranteed)
+join_on(suppliers, parts, [:city])
+.fi
+.RE

data/doc/man/lt.man

@@ -0,0 +1,30 @@
+.TH Lt
+.PP
+Less than
+.SH Signature
+.PP
+.RS
+.nf
+lt(left: Alpha|AttrName, right: Alpha|AttrName) -> Predicate
+.fi
+.RE
+.SH Examples
+.PP
+.RS
+.nf
+lt(:status, 20)
+.fi
+.RE
+.PP
+.RS
+.nf
+lt(:status, 30)
+.fi
+.RE
+.SH Description
+.PP
+This predicates checks whether a value (\fB\fCleft\fR) is less than another one
+(\fB\fCright\fR).
+.SH Implementation notes
+.PP
+This predicate is equivalent to \fB\fC->(t){ _left_ < _right_ }\fR\&.

data/doc/man/lte.man

@@ -0,0 +1,30 @@
+.TH Lte
+.PP
+Less than or equal to
+.SH Signature
+.PP
+.RS
+.nf
+lte(left: Alpha|AttrName, right: Alpha|AttrName) -> Predicate
+.fi
+.RE
+.SH Examples
+.PP
+.RS
+.nf
+lte(:status, 20)
+.fi
+.RE
+.PP
+.RS
+.nf
+lte(:status, 30)
+.fi
+.RE
+.SH Description
+.PP
+This predicates checks whether a value (\fB\fCleft\fR) is less than or equal to
+another one (\fB\fCright\fR).
+.SH Implementation notes
+.PP
+This predicate is equivalent to \fB\fC->(t){ _left_ <= _right_ }\fR\&.

data/doc/man/matching.man

@@ -0,0 +1,73 @@
+.TH Matching
+.PP
+Aka 'where exists'
+.SH Signature
+.PP
+.RS
+.nf
+matching(left: Relation, right: Relation) -> Relation
+.fi
+.RE
+.SH Examples
+.PP
+.RS
+.nf
+matching(suppliers, supplies)
+.fi
+.RE
+.SH Description
+.PP
+Computes a relation as a subset of \fB\fCleft\fR tuples for which at least one
+\fB\fCright\fR tuple would join on common attributes.
+.PP
+This operator, also known as semi\-join, can be explained through the
+definition below. As shown, it consists in joining \fB\fCleft\fR and \fB\fCright\fR
+relations and projecting the result back on \fB\fCleft\fR attributes.
+.PP
+.RS
+.nf
+def matching(left, right)
+  project(join(left, right), left.attr_list)
+end
+matching(suppliers, supplies)
+.fi
+.RE
+.PP
+Or, in SQL terms:
+.PP
+.RS
+.nf
+SELECT left.* FROM left NATURAL JOIN right
+.fi
+.RE
+.PP
+The synonym 'where exists' comes from the fact that, since right attributes
+are projected away, it may seem more intuitive to think about this operator
+as filtering tuples from left where \fIthere exists\fP some tuple at right that
+\fIwould\fP join. In SQL terms:
+.PP
+.RS
+.nf
+SELECT * FROM left WHERE EXISTS (SELECT * FROM right WHERE [join condition])
+.fi
+.RE
+.SH Implementation notes
+.PP
+As for (natural) \fB\fCjoin\fR, you must take care of ensuring that the list of
+common attributes on which the matching applies corresponds to what you
+want. Renamings and projections are worth having at hand when using
+matching. Alternatively, shortcuts can be considered. A (advanced) example
+below:
+.PP
+.RS
+.nf
+# Same as matching(left, right) except that only attributes in `wish`
+# are take into account in matching.
+def matching_on(left, right, wish)
+  matching(left, project(right, wish))
+end
+# observe here how part names have been discarded to avoid matching them
+# with supplier names (empty result guaranteed)
+matching_on(suppliers, parts, [:city])
+.fi
+.RE