alf-shell 0.14.0 → 0.15.0

data/doc/txt/allbut.txt

@@ -0,0 +1,31 @@
+# Allbut
+
+Projects a subset of attributes away.
+
+## Signature
+
+allbut(operand: Relation, attributes: AttrList) -> Relation
+
+## Examples
+
+allbut(suppliers, [:city])
+
+## Description
+
+Computes the relation obtained by removing a subset of attributes from
+`operand` tuples.
+
+This operator is the inverse of `project`. While the latter _keeps_
+attributes, this one _removes_ them. `project` actually supports an allbut
+variant, which is equivalent to this operator. In other words, this
+operator can be understood as follows:
+
+def allbut(operand, attributes)
+  project(operand, attributes, allbut: true)
+end
+allbut(suppliers, [:city, :status])
+
+## Implementation notes
+
+Unlike SQL, this operator ALWAYS remove duplicates. There is no way, in
+Alf, to compute _bags_ of tuples.

data/doc/txt/among.txt

@@ -0,0 +1,20 @@
+# Among
+
+Among a set of values
+
+## Signature
+
+among(val: Alpha|AttrName, vals: Set<Alpha>) -> Predicate
+
+## Examples
+among(:status, [10, 30])
+
+## Description
+
+This predicates checks whether `val` belongs to the set of values `vals`.
+
+## Implementation notes
+
+The set `vals` may only contain pure values, attribute names are not
+supported. Any enumerable of such values is supported in practice, e.g.
+an Array literal.

data/doc/txt/avg.txt

@@ -0,0 +1,22 @@
+# Avg
+
+Average
+
+## Signature
+
+avg(expr: AttrName|(Tuple->Numeric)) -> Aggregator
+
+## Examples
+avg(:qty)
+avg{|t| t.qty * t.price }
+avg(->(t){ t.qty * t.price })
+
+## Description
+
+Aggregates through `v1 + v2 + ... + vn / n`.
+
+## 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.

data/doc/txt/between.txt

@@ -0,0 +1,19 @@
+# Between
+
+Between (inclusive)
+
+## Signature
+
+between(val: Alpha|AttrName, min: Alpha|AttrName, max: Alpha|AttrName) -> Predicate
+
+## Examples
+between(:status, 10, 30)
+
+## Description
+
+This predicates checks whether a value (`val`) is between two bounds `min`
+and `max`, inclusive on both sides.
+
+## Implementation notes
+
+This predicate is equivalent to `gte(_val_,_min_) & lte(_val_,_max_)`.

data/doc/txt/concat.txt

@@ -0,0 +1,31 @@
+# Concat
+
+String concatenation
+
+## Signature
+
+concat(expr: AttrName|(Tuple->Numeric)) -> Aggregator
+
+## Examples
+concat(:name)
+concat(:name, between: ', ')
+concat(between: ', '){|t| t.name }
+concat(->(t){ t.name.upcase }, between: ', ')
+
+## Description
+
+Concatenates string representations of input values.
+
+## Implementation notes
+
+This aggregate function can be applied to any data type, not only String
+attributes. Ruby's `to_s` will be used on values prior to concatenation.
+
+The options are:
+
+* `before` starts the resulting string (defaults to '')
+* `after` ends the resulting string (defaults to '')
+* `between` is used between each value
+
+As of current Alf version, the order in which the values are concatenated
+is not guaranteed. So far, this function is thus non-deterministic.

data/doc/txt/contradiction.txt

@@ -0,0 +1,15 @@
+# Contradiction
+
+FALSE
+
+## Signature
+
+contradiction() -> Predicate
+
+## Examples
+false
+contradiction
+
+## Description
+
+This predicate always return false. It is equivalent to `->(t){ false }`.

data/doc/txt/count.txt

@@ -0,0 +1,14 @@
+# Count
+
+Count
+
+## Signature
+
+count() -> Aggregator
+
+## Examples
+count()
+
+## Description
+
+Counts the number of input values.

data/doc/txt/eq.txt

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

data/doc/txt/extend.txt

@@ -0,0 +1,29 @@
+# Extend
+
+Extends input tuples with derived/computed attributes
+
+## Signature
+
+extend(operand: Relation, ext: TupleComputation) -> Relation
+
+## Examples
+
+extend(suppliers,
+  big:   ->(t){ t.name.upcase },
+  small: ->(t){ t.name.downcase })
+
+## Description
+
+Computes a relation which is the same as `operand`, except that each of
+its tuples has new attributes whose value is the result of evaluating the
+tuple expressions specified in `ext`.
+
+## Implementation notes
+
+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.
+
+Similarly, as `extend` 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/txt/frame.txt

@@ -0,0 +1,48 @@
+# Frame
+
+Aka limit/offset
+
+## Signature
+
+frame(operand: Relation, order: Ordering, offset: Integer, limit: Integer) -> Relation
+
+## Examples
+
+frame(suppliers, [:status, :sid], 0, 3)
+
+frame(suppliers, [[:status, :asc], [:sid, :desc]], 1, 2)
+
+## Description
+
+Computes a relation by restricting the tuples of `operand` to a particular
+frame. This frame can be easily remembered through the "skip `offset`,
+take `limit`" mnemonic mean, provided `order` is a total order.
+
+Formally, the frame is defined by those tuples whose ranking according to
+`order` is such that `offset <= rank < limit`. In other words, this
+operator is actually equivalent to the following definition:
+
+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)
+
+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
+'efficient' 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/group.txt

@@ -0,0 +1,37 @@
+# Group
+
+Relation-valued attribute
+
+## Signature
+
+group(operand: Relation, attributes: AttrList, as: AttrName) -> Relation
+
+## Examples
+
+group(suppliers, [:sid, :name, :status], :suppliers)
+
+group(suppliers, [:city], :suppliers, allbut: true)
+
+## Description
+
+Summarizes `operand` by all but the specified `attributes` and groups the
+latter under a relation-value attribute `as`.
+
+This operator could be formally defined as the following shortcut:
+
+def group(operand, attributes, as)
+  extend(
+    allbut(operand, attributes),
+    as: ->(t){ project(matching(operand, Relation(t)), attributes) })
+end
+group(suppliers, [:sid, :name, :status], :suppliers)
+
+This operators supports an ALL BUT variant, through the `allbut` option.
+When set to true, the operator keeps specified attributes and groups all
+remaining ones as a relation-valued attribute.
+
+## Implementation notes
+
+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/txt/gt.txt

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

data/doc/txt/gte.txt

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

data/doc/txt/intersect.txt

@@ -0,0 +1,42 @@
+# Intersect
+
+Logical AND
+
+## Signature
+
+intersect(left: Relation, right: Relation) -> Relation
+
+## Examples
+
+intersect(
+  restrict(suppliers, eq(:city, 'Paris')),
+  restrict(suppliers, gt(:status, 10)))
+
+## Description
+
+Computes the relation as the set intersection of `left` and `right`.
+
+The `left` and `right` 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).
+
+## 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 INTERSECT ALL.
+
+It is sometimes idiomatic in Alf to use `intersect` 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!
+
+intersect(
+  restrict(suppliers, eq(:city, 'Paris')),
+  restrict(suppliers, gt(:status, 10)))
+
+is equivalent to
+
+restrict(suppliers, eq(:city, 'Paris') & gt(:status, 10))

data/doc/txt/join.txt

@@ -0,0 +1,65 @@
+# Join
+
+Natural join
+
+## Signature
+
+join(left: Relation, right: Relation) -> Relation
+
+## Examples
+
+join(suppliers, supplies)
+
+## Description
+
+Computes the relation resuting from joining tuples from `left` and `right`
+whose respective projections on common attributes are equal.
+
+## Implementation notes
+
+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:
+
+# 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))
+
+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:
+
+pairs = join(project(suppliers, [:sid]), project(parts, [:pid]))
+
+Non equi-joins can be computed through a latter restriction. For instance,
+the (supplier, part) pairs not located in the same city:
+
+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])
+
+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.
+
+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 `latest_change` and `deleted` fields and the like). Renamings and
+projections are worth having at hand when joining.
+
+Alternatively, shortcuts can be considered. A (advanced) example below:
+
+# 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])