alf-shell 0.14.0 → 0.15.0

data/doc/man/stddev.man

@@ -0,0 +1,37 @@
+.TH Stddev
+.PP
+Standard deviation
+.SH Signature
+.PP
+.RS
+.nf
+stddev(expr: AttrName|(Tuple->Numeric)) -> Aggregator
+.fi
+.RE
+.SH Examples
+.PP
+.RS
+.nf
+stddev(:qty)
+.fi
+.RE
+.PP
+.RS
+.nf
+stddev{|t| t.qty * t.price }
+.fi
+.RE
+.PP
+.RS
+.nf
+stddev(->(t){ t.qty * t.price })
+.fi
+.RE
+.SH Description
+.PP
+Computes how much variation from the average exists.
+.SH Implementation notes
+.PP
+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/man/sum.man

@@ -0,0 +1,37 @@
+.TH Sum
+.PP
+Arithmetic sum
+.SH Signature
+.PP
+.RS
+.nf
+sum(expr: AttrName|(Tuple->Numeric)) -> Aggregator
+.fi
+.RE
+.SH Examples
+.PP
+.RS
+.nf
+sum(:qty)
+.fi
+.RE
+.PP
+.RS
+.nf
+sum{|t| t.qty * t.price }
+.fi
+.RE
+.PP
+.RS
+.nf
+sum(->(t){ t.qty * t.price })
+.fi
+.RE
+.SH Description
+.PP
+Computes \fB\fCv1 + v2 + ... + vn\fR\&.
+.SH Implementation notes
+.PP
+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/man/summarize.man

@@ -0,0 +1,45 @@
+.TH Summarize
+.PP
+Aggregate and compute
+.SH Signature
+.PP
+.RS
+.nf
+summarize(operand: Relation, by: AttrList, aggs: Summarization) -> Relation
+.fi
+.RE
+.SH Examples
+.PP
+.RS
+.nf
+summarize(supplies, [:sid], total: sum(:qty))
+.fi
+.RE
+.PP
+.RS
+.nf
+summarize(supplies, [:sid], total: sum{|t| t.qty * 2 })
+.fi
+.RE
+.PP
+.RS
+.nf
+summarize(supplies, [:pid, :qty], {total: sum{|t| t.qty * 2 }}, allbut: true)
+.fi
+.RE
+.SH Description
+.PP
+Computes the relation obtained by taking the projection of \fB\fCoperand\fR
+on \fB\fCby\fR attributes then extending each tuple \fB\fCt\fR with the result of
+aggregations defined by \fB\fCaggs\fR on the tuples from \fB\fCoperand\fR matching \fB\fCt\fR\&.
+.PP
+In SQL terms, \fB\fCSELECT [by], [agg] FROM operand GROUP BY [by]\fR\&.
+.SH Implementation notes
+.PP
+As of current Alf version, this operator cannot be translated to SQL code.
+That means that all computations are done in ruby, which may seriously
+hurt performance.
+.PP
+Similarly, as \fB\fCsummarize\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/tautology.man

@@ -0,0 +1,26 @@
+.TH Tautology
+.PP
+TRUE
+.SH Signature
+.PP
+.RS
+.nf
+tautology() -> Predicate
+.fi
+.RE
+.SH Examples
+.PP
+.RS
+.nf
+true
+.fi
+.RE
+.PP
+.RS
+.nf
+tautology
+.fi
+.RE
+.SH Description
+.PP
+This predicate always return true. It is equivalent to \fB\fC->(t){ true }\fR\&.

data/doc/man/ungroup.man

@@ -0,0 +1,30 @@
+.TH Ungroup
+.PP
+Inverse of group
+.SH Signature
+.PP
+.RS
+.nf
+ungroup(operand: Relation, rva: AttrName) -> Relation
+.fi
+.RE
+.SH Examples
+.PP
+.RS
+.nf
+ungroup(group(suppliers, [:city], :suppliers, allbut: true), :suppliers)
+.fi
+.RE
+.SH Description
+.PP
+Computes the relation obtained by ungrouping a relation\-valued attribute
+\fB\fCrva\fR\&. Ungrouping \fB\fCrva\fR leads as many tuples as in \fB\fCrva\fR, each extended
+with the other attributes of \fB\fCoperand\fR\&.
+.PP
+\fB\fCrva\fR must be a relation\-valued attribute. It should not itself contain
+any attribute whose name clashes with an attribute of \fB\fCoperand\fR\&.
+.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/union.man

@@ -0,0 +1,55 @@
+.TH Union
+.PP
+Logical OR
+.SH Signature
+.PP
+.RS
+.nf
+union(left: Relation, right: Relation) -> Relation
+.fi
+.RE
+.SH Examples
+.PP
+.RS
+.nf
+union(project(suppliers, [:city]), project(parts, [:city]))
+.fi
+.RE
+.SH Description
+.PP
+Computes the relation as the set union of \fB\fCleft\fR and \fB\fCright\fR\&.
+.PP
+The \fB\fCleft\fR and \fB\fCright\fR relations must be union\-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 UNION ALL.
+.PP
+The optimizer is not smart enough so far to discover when operands are
+actually disjoint and duplicate removal not needed (e.g. the SQL compiler
+never generates UNION ALL). Any patch improving this is welcome!
+.PP
+Similarly, it is sometimes idiomatic in Alf to use \fB\fCunion\fR as a logical OR,
+as illustrated below. So far, the optimizer/compiler is not smart enough to
+translate the former in the latter (which is likely to have a better query
+plan, especially when using faithful SQL compilation and usual SQL DBMSs).
+Any patch is welcome here too!
+.PP
+.RS
+.nf
+union(
+  restrict(suppliers, city: 'Paris'),
+  restrict(suppliers, city: 'London'))
+.fi
+.RE
+.PP
+is equivalent to
+.PP
+.RS
+.nf
+restrict(suppliers, eq(:city, 'Paris') | eq(:city, 'London'))
+.fi
+.RE

data/doc/man/unwrap.man

@@ -0,0 +1,37 @@
+.TH Unwrap
+.PP
+Inverse of wrap
+.SH Signature
+.PP
+.RS
+.nf
+unwrap(operand: Relation, tva: AttrName) -> Relation
+.fi
+.RE
+.SH Examples
+.PP
+.RS
+.nf
+unwrap(wrap(suppliers, [:city, :status], :extra), :extra)
+.fi
+.RE
+.SH Description
+.PP
+Computes the relation obtained by unwrapping a tuple\-valued attribute \fB\fCtva\fR\&.
+Unwrapping of \fB\fCtva\fR on an input tuple \fB\fCt\fR consists in removing \fB\fCtva\fR from
+\fB\fCt\fR and extending the result with \fB\fCtva\fR\&'s own attributes:
+.PP
+.RS
+.nf
+Tuple(x: 1, tva: Tuple(y: 2, z: 3)) -> Tuple(x: 1, y: 2, z: 3)
+.fi
+.RE
+.PP
+\fB\fCtva\fR must be a tuple\-valued attribute. It should not itself contain any
+attribute whose name clashes with an attribute of \fB\fCoperand\fR\&. In the examples
+above, \fB\fCtva\fR may not contain an attribute called \fB\fCx\fR\&.
+.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/variance.man

@@ -0,0 +1,37 @@
+.TH Variance
+.PP
+Variance
+.SH Signature
+.PP
+.RS
+.nf
+variance(expr: AttrName|(Tuple->Numeric)) -> Aggregator
+.fi
+.RE
+.SH Examples
+.PP
+.RS
+.nf
+variance(:qty)
+.fi
+.RE
+.PP
+.RS
+.nf
+variance{|t| t.qty * t.price }
+.fi
+.RE
+.PP
+.RS
+.nf
+variance(->(t){ t.qty * t.price })
+.fi
+.RE
+.SH Description
+.PP
+Computes how far the set of input values is spread out.
+.SH Implementation notes
+.PP
+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/man/wrap.man

@@ -0,0 +1,37 @@
+.TH Wrap
+.PP
+Tuple\-valued attribute
+.SH Signature
+.PP
+.RS
+.nf
+wrap(operand: Relation, attributes: AttrList, as: AttrName) -> Relation
+.fi
+.RE
+.SH Examples
+.PP
+.RS
+.nf
+wrap(suppliers, [:city, :status], :extra)
+.fi
+.RE
+.PP
+.RS
+.nf
+wrap(suppliers, [:city, :status], :extra, allbut: true)
+.fi
+.RE
+.SH Description
+.PP
+Computes the relation obtained by removing \fB\fCattributes\fR and replacing them
+by a single attribute (\fB\fCas\fR). The latter is a tuple\-valued attribute
+obtained by projecting the input tuple on \fB\fCattributes\fR\&.
+.PP
+This operators supports an ALL BUT variant, through the \fB\fCallbut\fR option.
+When set to true, the operator keeps specified attributes and wraps all the
+remaining ones as a tuple\-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/txt/alf-explain.man

@@ -0,0 +1,22 @@
+# alf-explain
+
+Show the logical (optimizer) and physical (compiler) plans of a query.
+
+## Synopsis
+
+`alf` explain *QUERY*
+
+## Description
+
+This command prints the logical and physical query plans for QUERY to
+standard output:
+
+* The logical plan is post-optimizer and allows checking that the latter
+  performs correctly.
+* The physical plan provides information about compilation. In particular it
+  provides feedback about the effective delegation to underlying database
+  engines, as well as involved SQL queries.
+
+## Example
+
+`alf` `--examples` explain "restrict(suppliers, city: 'London')"

data/doc/txt/alf-metadata.man

@@ -0,0 +1,16 @@
+# alf-metadata
+
+Show metadata about a query, such as heading and candidate keys.
+
+## Synopsis
+
+`alf` metadata *QUERY*
+
+## Description
+
+This command prints some metadata (e.g. heading, keys, etc.) about the
+expression passed as first argument.
+
+## Example
+
+`alf` `--examples` metadata "restrict(suppliers, city: 'London')"

data/doc/txt/alf-show.man

@@ -0,0 +1,19 @@
+# alf-show
+
+Evaluates a query and shows the result.
+
+## Synopsis
+
+`alf` [`--csv`|`--json`...] show *QUERY* -- [*ORDERING*]
+
+## Description
+
+Take a query argument and execute it against the current database (according
+to options passed to the `alf` main command). Show the result on standard
+output. The format (e.g. json) may be specified through `alf` main options.
+
+When an ordering is specified, tuples are rendered in the order specified.
+
+## Example
+
+`alf` `--examples` show "restrict(suppliers, city: 'London')" -- name DESC

data/doc/txt/alf.man

@@ -0,0 +1,80 @@
+# alf
+
+Relational algebra at your fingertips
+
+## Synopsis
+
+`alf` [`--version`] [`--help`]
+
+`alf` *FILE.alf*
+
+`alf` show *QUERY*
+
+`alf` explain *QUERY*
+
+`alf` help *OPERATOR*
+
+## Options
+
+  `--rash`
+    Render output as ruby hashes
+
+  `--text`
+    Render output as a text table
+
+  `--yaml`
+    Render output in YAML
+
+  `--json`
+    Render output in JSON
+
+  `--csv`
+    Render output in CSV
+
+  `--examples`
+    Use the suppliers and parts example database
+
+  `--db=DB`
+    Set the database (adapter) to use. Recognized values can be
+    folders with recognized files, or an URL to a SQL database
+    (e.g. postgres://user:pass@host/database)
+
+  `--stdin=READER`
+    Specify the kind of reader when reading on standard input
+    (i.e. rash, csv, json, ruby, or yaml)
+
+  `-Idirectory`
+    Specify $LOAD_PATH directory (may be used more than once)
+
+  `-rlibrary`
+    Require the specified ruby library, before executing alf
+
+  `--ff=FORMAT`
+    Specify the floating point format
+
+  `--[no-]pretty`
+    Enable/disable pretty print best effort
+
+  `-h`, `--help`
+    Show this help
+
+  `-v`, `--version`
+    Show version and copyright
+
+## Commands
+
+  `help`
+    Shows help about a specific command, relational operator, aggregator,
+    or predicate.
+
+  `show`
+    Evaluates a query and shows the result in a specified format.
+
+  `metadata`
+    Show metadata for a query (heading, keys).
+
+  `explain`
+    Show the logical (optimizer) and physical (compiler) plans of a query.
+
+See `alf help COMMAND` for details about a specific command or `alf help
+OPERATOR` for documentation of a relational operator.