alf-shell 0.14.0 → 0.15.0

data/doc/txt/lt.txt

@@ -0,0 +1,20 @@
+# Lt
+
+Less than
+
+## Signature
+
+lt(left: Alpha|AttrName, right: Alpha|AttrName) -> Predicate
+
+## Examples
+lt(:status, 20)
+lt(:status, 30)
+
+## Description
+
+This predicates checks whether a value (`left`) is less than another one
+(`right`).
+
+## Implementation notes
+
+This predicate is equivalent to `->(t){ _left_ < _right_ }`.

data/doc/txt/lte.txt

@@ -0,0 +1,20 @@
+# Lte
+
+Less than or equal to
+
+## Signature
+
+lte(left: Alpha|AttrName, right: Alpha|AttrName) -> Predicate
+
+## Examples
+lte(:status, 20)
+lte(:status, 30)
+
+## Description
+
+This predicates checks whether a value (`left`) is less than or equal to
+another one (`right`).
+
+## Implementation notes
+
+This predicate is equivalent to `->(t){ _left_ <= _right_ }`.

data/doc/txt/matching.txt

@@ -0,0 +1,54 @@
+# Matching
+
+Aka 'where exists'
+
+## Signature
+
+matching(left: Relation, right: Relation) -> Relation
+
+## Examples
+
+matching(suppliers, supplies)
+
+## Description
+
+Computes a relation as a subset of `left` tuples for which at least one
+`right` tuple would join on common attributes.
+
+This operator, also known as semi-join, can be explained through the
+definition below. As shown, it consists in joining `left` and `right`
+relations and projecting the result back on `left` attributes.
+
+def matching(left, right)
+  project(join(left, right), left.attr_list)
+end
+matching(suppliers, supplies)
+
+Or, in SQL terms:
+
+SELECT left.* FROM left NATURAL JOIN right
+
+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 _there exists_ some tuple at right that
+_would_ join. In SQL terms:
+
+SELECT * FROM left WHERE EXISTS (SELECT * FROM right WHERE [join condition])
+
+## Implementation notes
+
+As for (natural) `join`, 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:
+
+# 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])

data/doc/txt/max.txt

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

data/doc/txt/min.txt

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

data/doc/txt/minus.txt

@@ -0,0 +1,42 @@
+# Minus
+
+Logical AND NOT
+
+## Signature
+
+minus(left: Relation, right: Relation) -> Relation
+
+## Examples
+
+minus(
+  restrict(suppliers, eq(:city, 'Paris')),
+  restrict(suppliers, gt(:status, 10)))
+
+## Description
+
+Computes the relation as the set difference of `left` and `right`.
+
+The `left` and `right` 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).
+
+## Implementation notes
+
+Unlike SQL, this operator ALWAYS remove duplicates. There is no way, in
+Alf, to compute _bags_ of tuples and therefore no way to express something
+such as SQL's EXCEPT ALL.
+
+It is sometimes idiomatic in Alf to use `intersect` 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!
+
+minus(
+  restrict(suppliers, eq(:city, 'Paris')),
+  restrict(suppliers, gt(:status, 10)))
+
+is equivalent to
+
+restrict(suppliers, eq(:city, 'Paris') & !gt(:status, 10))

data/doc/txt/native.txt

@@ -0,0 +1,27 @@
+# Native
+
+User-defined tuple predicate
+
+## Signature
+
+native(predicate: (Tuple -> Boolean)) -> Predicate
+
+## Examples
+->(t){ t.city == 'London' }
+
+## Description
+
+So called 'native' predicates are functions computing truth values from
+tuples.
+
+## Implementation notes
+
+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.).
+
+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 `eq(:city, 'London')` if
+possible, as they do not hurt logical optimizations and compilation.

data/doc/txt/neq.txt

@@ -0,0 +1,19 @@
+# Neq
+
+Not equal to
+
+## Signature
+
+neq(left: Alpha|AttrName, right: Alpha|AttrName) -> Predicate
+
+## Examples
+neq(:city, 'London')
+neq(:supplier_city, :part_city)
+
+## Description
+
+This predicates checks whether two values are different.
+
+## Implementation notes
+
+This predicate is equivalent to `->(t){ _left_ != _right_ }`.

data/doc/txt/not_matching.txt

@@ -0,0 +1,39 @@
+# Not_matching
+
+Aka 'where not exists'
+
+## Signature
+
+not_matching(left: Relation, right: Relation) -> Relation
+
+## Examples
+
+not_matching(suppliers, supplies)
+
+## Description
+
+Computes a relation as a subset of `left` tuples for which no tuple from
+`right` would join on common attributes.
+
+This operator is the inverse of `matching`, as shown by the definition
+below. It keeps all tuples from `left` but those that match a tuple from
+`right`.
+
+def not_matching(left, right)
+  minus(left, matching(left, right))
+end
+not_matching(suppliers, supplies)
+
+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 _there does not
+exist_ any tuple from right that _would_ join. In SQL terms:
+
+SELECT * FROM left WHERE NOT EXISTS (SELECT * FROM right WHERE [join condition])
+
+## Implementation notes
+
+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 `matching` and `join`).

data/doc/txt/page.txt

@@ -0,0 +1,48 @@
+# Page
+
+Pagination
+
+## Signature
+
+page(operand: Relation, ordering: Ordering, nth: Integer) -> Relation
+
+## Examples
+
+page(suppliers, [:status, :sid], 1, page_size: 3)
+
+page(suppliers, [:status, :sid], -1, page_size: 3)
+
+## Description
+
+Computes a relation by restricting the tuples of `operand` to those
+belonging to the `nth` page (starting at 1). When `nth` is negative, returns
+tuples that belong to the `nth` page from the end (e.g., -1 is last page).
+
+Formally, the page is defined by those tuples whose ranking according to
+`order` is such that `(nth-1)*page_size <= rank < nth*page_size`. In other
+words, this operator is almost equivalent to the following definition
+(ignoring negative page indexes for simplicity):
+
+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
+
+As of current Alf version, for this operator to be semantically sound and
+deterministic, `order` 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.
+
+## Implementation notes
+
+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.
+
+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 `order`.

data/doc/txt/project.txt

@@ -0,0 +1,28 @@
+# Project
+
+Keeps only a subset of attributes.
+
+## Signature
+
+project(operand: Relation, attributes: AttrList) -> Relation
+
+## Examples
+
+project(suppliers, [:city])
+
+project(suppliers, [:city], allbut: true)
+
+## Description
+
+Computes the relation obtained by projecting tuples from `operand` on a
+subset of their attributes.
+
+This operator supports an ALL BUT variant, through the `allbut` option.
+When set to true, the operator _removes_ specified attributes instead of
+keeping them. An `allbut` operator is also provided that has the same
+effect.
+
+## Implementation notes
+
+Unlike SQL, this operator ALWAYS remove duplicates. There is no way, in
+Alf, to compute _bags_ of tuples.

data/doc/txt/rank.txt

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

data/doc/txt/rename.txt

@@ -0,0 +1,25 @@
+# Rename
+
+Rename attributes
+
+## Signature
+
+rename(operand: Relation, renaming: Renaming) -> Relation
+
+## Examples
+
+rename(suppliers, :sid => :supplier_id, :city => :lives_in)
+
+## Description
+
+Computes the same relation as `operand` expect that some attributes have
+been renamed.
+
+## Implementation notes
+
+As of current version, renamings can only be expressed through a Hash
+mapping input to output attribute names.
+
+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/txt/restrict.txt

@@ -0,0 +1,26 @@
+# Restrict
+
+Predicate-based filtering
+
+## Signature
+
+restrict(operand: Relation, predicate: Predicate) -> Relation
+
+## Examples
+
+restrict(suppliers, city: 'Paris', status: 20)
+
+restrict(suppliers, eq(city: 'Paris') & gt(:status, 20))
+
+restrict(suppliers, ->(t){ t.city == 'Paris' and t.status > 20 })
+
+## Description
+
+Computes a relation as a subset of `operand` tuples for which a tuple
+predicate evaluates to TRUE.
+
+## Implementation notes
+
+As of current Alf version, native predicates (through ruby `Proc` objects)
+cannot be optimized nor compiled to SQL. The use of predicate factories
+(`eq`, `gt`, etc.) is strongly recommanded.

data/doc/txt/stddev.txt

@@ -0,0 +1,22 @@
+# Stddev
+
+Standard deviation
+
+## Signature
+
+stddev(expr: AttrName|(Tuple->Numeric)) -> Aggregator
+
+## Examples
+stddev(:qty)
+stddev{|t| t.qty * t.price }
+stddev(->(t){ t.qty * t.price })
+
+## Description
+
+Computes how much variation from the average exists.
+
+## Implementation notes
+
+This aggregate function should only be used with numeric types. As of
+current Alf version, it does not aggregate empty sets correctly on
+non-numeric data types.