alf-shell 0.14.0 → 0.15.0

data/doc/man/max.man

@@ -0,0 +1,36 @@
+.TH Max
+.PP
+Maximal value
+.SH Signature
+.PP
+.RS
+.nf
+max(expr: AttrName|(Tuple->Numeric)) -> Aggregator
+.fi
+.RE
+.SH Examples
+.PP
+.RS
+.nf
+max(:qty)
+.fi
+.RE
+.PP
+.RS
+.nf
+max{|t| t.qty * t.price }
+.fi
+.RE
+.PP
+.RS
+.nf
+max(->(t){ t.qty * t.price })
+.fi
+.RE
+.SH Description
+.PP
+Returns the greatest of input values.
+.SH Implementation notes
+.PP
+This aggregate function must only be used with comparable types. As of
+current Alf version, it does not aggregate empty sets correctly.

data/doc/man/min.man

@@ -0,0 +1,36 @@
+.TH Min
+.PP
+Minimal value
+.SH Signature
+.PP
+.RS
+.nf
+min(expr: AttrName|(Tuple->Numeric)) -> Aggregator
+.fi
+.RE
+.SH Examples
+.PP
+.RS
+.nf
+min(:qty)
+.fi
+.RE
+.PP
+.RS
+.nf
+min{|t| t.qty * t.price }
+.fi
+.RE
+.PP
+.RS
+.nf
+min(->(t){ t.qty * t.price })
+.fi
+.RE
+.SH Description
+.PP
+Returns the smallest of input values.
+.SH Implementation notes
+.PP
+This aggregate function must only be used with comparable types. As of
+current Alf version, it does not aggregate empty sets correctly.

data/doc/man/minus.man

@@ -0,0 +1,54 @@
+.TH Minus
+.PP
+Logical AND NOT
+.SH Signature
+.PP
+.RS
+.nf
+minus(left: Relation, right: Relation) -> Relation
+.fi
+.RE
+.SH Examples
+.PP
+.RS
+.nf
+minus(
+  restrict(suppliers, eq(:city, 'Paris')),
+  restrict(suppliers, gt(:status, 10)))
+.fi
+.RE
+.SH Description
+.PP
+Computes the relation as the set difference of \fB\fCleft\fR and \fB\fCright\fR\&.
+.PP
+The \fB\fCleft\fR and \fB\fCright\fR relations must be minus\-compatible, which 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 EXCEPT ALL.
+.PP
+It is sometimes idiomatic in Alf to use \fB\fCintersect\fR as a logical AND NOT, 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
+plan when using faithful SQL compilation and available SQL DBMSs). Any patch
+is welcome here too!
+.PP
+.RS
+.nf
+minus(
+  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/native.man

@@ -0,0 +1,32 @@
+.TH Native
+.PP
+User\-defined tuple predicate
+.SH Signature
+.PP
+.RS
+.nf
+native(predicate: (Tuple -> Boolean)) -> Predicate
+.fi
+.RE
+.SH Examples
+.PP
+.RS
+.nf
+->(t){ t.city == 'London' }
+.fi
+.RE
+.SH Description
+.PP
+So called 'native' predicates are functions computing truth values from
+tuples.
+.SH Implementation notes
+.PP
+Native predicates can be any ruby Proc object of arity 1. The argument
+will be a Tuple instance. the Proc SHOULD return true or false, but ruby
+patterns for boolean expressions are supported to (such a nil evaluating
+to false, etc.).
+.PP
+Note that, as of current Alf version, native predicates cannot be delegated
+to an underlying data engine, and are not compiled to SQL in particular.
+Please always use predicate factories such as \fB\fCeq(:city, 'London')\fR if
+possible, as they do not hurt logical optimizations and compilation.

data/doc/man/neq.man

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

data/doc/man/not_matching.man

@@ -0,0 +1,51 @@
+.TH Not_matching
+.PP
+Aka 'where not exists'
+.SH Signature
+.PP
+.RS
+.nf
+not_matching(left: Relation, right: Relation) -> Relation
+.fi
+.RE
+.SH Examples
+.PP
+.RS
+.nf
+not_matching(suppliers, supplies)
+.fi
+.RE
+.SH Description
+.PP
+Computes a relation as a subset of \fB\fCleft\fR tuples for which no tuple from
+\fB\fCright\fR would join on common attributes.
+.PP
+This operator is the inverse of \fB\fCmatching\fR, as shown by the definition
+below. It keeps all tuples from \fB\fCleft\fR but those that match a tuple from
+\fB\fCright\fR\&.
+.PP
+.RS
+.nf
+def not_matching(left, right)
+  minus(left, matching(left, right))
+end
+not_matching(suppliers, supplies)
+.fi
+.RE
+.PP
+The synonym 'where not exists' comes from the fact that, since right
+attributes do not appear in the result, it may seem more intuitive to think
+about this operator as filtering tuples from left where \fIthere does not
+exist\fP any tuple from right that \fIwould\fP join. In SQL terms:
+.PP
+.RS
+.nf
+SELECT * FROM left WHERE NOT EXISTS (SELECT * FROM right WHERE [join condition])
+.fi
+.RE
+.SH Implementation notes
+.PP
+As for join and matching, you must take care of ensuring that the list of
+common attributes on which the (not) matching applies corresponds to what
+you want. Renamings and projections are worth having at hand.
+Alternatively, shortcuts can be considered (see \fB\fCmatching\fR and \fB\fCjoin\fR).

data/doc/man/page.man

@@ -0,0 +1,60 @@
+.TH Page
+.PP
+Pagination
+.SH Signature
+.PP
+.RS
+.nf
+page(operand: Relation, ordering: Ordering, nth: Integer) -> Relation
+.fi
+.RE
+.SH Examples
+.PP
+.RS
+.nf
+page(suppliers, [:status, :sid], 1, page_size: 3)
+.fi
+.RE
+.PP
+.RS
+.nf
+page(suppliers, [:status, :sid], -1, page_size: 3)
+.fi
+.RE
+.SH Description
+.PP
+Computes a relation by restricting the tuples of \fB\fCoperand\fR to those
+belonging to the \fB\fCnth\fR page (starting at 1). When \fB\fCnth\fR is negative, returns
+tuples that belong to the \fB\fCnth\fR page from the end (e.g., \-1 is last page).
+.PP
+Formally, the page is defined by those tuples whose ranking according to
+\fB\fCorder\fR is such that \fB\fC(nth-1)*page_size <= rank < nth*page_size\fR\&. In other
+words, this operator is almost equivalent to the following definition
+(ignoring negative page indexes for simplicity):
+.PP
+.RS
+.nf
+def page(operand, order, nth, page_size)
+  allbut(
+    restrict(
+      rank(operand, order, :rank),
+      lte((nth-1)*page_size, :rank) & lt(:rank, nth*page_size)),
+    [:rank])
+end
+.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
+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/project.man

@@ -0,0 +1,36 @@
+.TH Project
+.PP
+Keeps only a subset of attributes.
+.SH Signature
+.PP
+.RS
+.nf
+project(operand: Relation, attributes: AttrList) -> Relation
+.fi
+.RE
+.SH Examples
+.PP
+.RS
+.nf
+project(suppliers, [:city])
+.fi
+.RE
+.PP
+.RS
+.nf
+project(suppliers, [:city], allbut: true)
+.fi
+.RE
+.SH Description
+.PP
+Computes the relation obtained by projecting tuples from \fB\fCoperand\fR on a
+subset of their attributes.
+.PP
+This operator supports an ALL BUT variant, through the \fB\fCallbut\fR option.
+When set to true, the operator \fIremoves\fP specified attributes instead of
+keeping them. An \fB\fCallbut\fR operator is also provided that has the same
+effect.
+.SH Implementation notes
+.PP
+Unlike SQL, this operator ALWAYS remove duplicates. There is no way, in
+Alf, to compute \fIbags\fP of tuples.

data/doc/man/rank.man

@@ -0,0 +1,42 @@
+.TH Rank
+.PP
+Tuple ranking
+.SH Signature
+.PP
+.RS
+.nf
+rank(operand: Relation, order: Ordering, as: AttrName) -> Relation
+.fi
+.RE
+.SH Examples
+.PP
+.RS
+.nf
+rank(suppliers, [:status], :ranking)
+.fi
+.RE
+.PP
+.RS
+.nf
+rank(suppliers, [:status, :sid], :ranking)
+.fi
+.RE
+.SH Description
+.PP
+Extends tuples from \fB\fCoperand\fR with a new attribute (\fB\fCas\fR) capturing the
+tuple position with respect to \fB\fCorder\fR\&.
+.PP
+The ranking of a tuple \fB\fCt\fR is more precisely defined as the number of tuples
+from \fB\fCoperand\fR that would come strictly before \fB\fCt\fR if they were all ordered
+according to \fB\fCorder\fR\&. 'Equal' tuples with respect to \fB\fCorder\fR are not counted
+in this ranking.
+.PP
+This means that, unless \fB\fCorder\fR is a total order, duplicate ranking may be
+observed. In contrast, if \fB\fCorder\fR covers a candidate key then the ranking
+attribute (\fB\fCas\fR) is unique, and therefore defines an additional candidate
+key for the resulting relation.
+.SH Implementation notes
+.PP
+Note that this operator does not compile to SQL so far. The \fB\fCpage\fR and
+\fB\fCframe\fR operators provide useful alternatives when the aim is to compute
+a subset of tuples based on a ranking.

data/doc/man/rename.man

@@ -0,0 +1,29 @@
+.TH Rename
+.PP
+Rename attributes
+.SH Signature
+.PP
+.RS
+.nf
+rename(operand: Relation, renaming: Renaming) -> Relation
+.fi
+.RE
+.SH Examples
+.PP
+.RS
+.nf
+rename(suppliers, :sid => :supplier_id, :city => :lives_in)
+.fi
+.RE
+.SH Description
+.PP
+Computes the same relation as \fB\fCoperand\fR expect that some attributes have
+been renamed.
+.SH Implementation notes
+.PP
+As of current version, renamings can only be expressed through a Hash
+mapping input to output attribute names.
+.PP
+Other ways of specifying renamining will be added in future versions, such
+as prefixing, postfixing, renaming through a Proc, etc. Any patch towards
+these improvements is welcome.

data/doc/man/restrict.man

@@ -0,0 +1,38 @@
+.TH Restrict
+.PP
+Predicate\-based filtering
+.SH Signature
+.PP
+.RS
+.nf
+restrict(operand: Relation, predicate: Predicate) -> Relation
+.fi
+.RE
+.SH Examples
+.PP
+.RS
+.nf
+restrict(suppliers, city: 'Paris', status: 20)
+.fi
+.RE
+.PP
+.RS
+.nf
+restrict(suppliers, eq(city: 'Paris') & gt(:status, 20))
+.fi
+.RE
+.PP
+.RS
+.nf
+restrict(suppliers, ->(t){ t.city == 'Paris' and t.status > 20 })
+.fi
+.RE
+.SH Description
+.PP
+Computes a relation as a subset of \fB\fCoperand\fR tuples for which a tuple
+predicate evaluates to TRUE.
+.SH Implementation notes
+.PP
+As of current Alf version, native predicates (through ruby \fB\fCProc\fR objects)
+cannot be optimized nor compiled to SQL. The use of predicate factories
+(\fB\fCeq\fR, \fB\fCgt\fR, etc.) is strongly recommanded.