NAME
Muldis::D::Ext::QRelation - Muldis D extension adding more generic relational operators
VERSION
This document is Muldis::D::Ext::QRelation version 0.61.0.
PREFACE
This document is part of the Muldis D language specification, whose root document is Muldis::D; you should read that root document before you read this one, which provides subservient details.
DESCRIPTION
Muldis D has a mandatory core set of system-defined (eternally available) entities, which is referred to as the Muldis D core or the core; they are the minimal entities that all Muldis D implementations need to provide; they are mutually self-describing and are used to bootstrap the language; any entities outside the core, called Muldis D extensions, are non-mandatory and are defined in terms of the core or each other, but the reverse isn't true.
This current QRelation document describes the system-defined Muldis D QRelation Extension, which consists of many generic relational operators (for generic q/relations), adding to the minimum few defined in the language core.
This current document does not describe the polymorphic operators that all types, or some types including core types, have defined over them; said operators are defined once for all types in Muldis::D::Core.
This documentation is pending.
SYSTEM-DEFINED GENERIC SINGLE INPUT QUASI-/RELATION FUNCTIONS
These functions are applicable to mainly q/relation types, but are generic in that they typically work with any q/relation types. Each assuming parameter is optional and defaults to the zero-attribute tuple if no explicit argument is given to it.
sys.std.QRelation.degree
function sys.std.QRelation.degree result NNInt params { topic(QRelation) }
This function results in the degree of its argument (that is, the count of attributes it has).
sys.std.QRelation.is_nullary
function sys.std.QRelation.is_nullary result Bool params { topic(QRelation) }
This function results in Bool:true iff its argument has a degree of zero (that is, it has zero attributes), and Bool:false otherwise. By definition, the only 2 q/relation values for which this function would result in Bool:true are the only members of the type RelationD0.
sys.std.QRelation.is_not_nullary
function sys.std.QRelation.is_not_nullary result Bool params { topic(QRelation) }
This function is exactly the same as sys.std.QRelation.is_nullary except that it results in the opposite boolean value when given the same argument.
sys.std.QRelation.has_attrs
function sys.std.QRelation.has_attrs result Bool params { topic(QRelation), attr_names(set_of.Name) }
This function results in Bool:true iff, for every one of the attribute names specified by its attr_names argument, its topic argument has an attribute with that name; otherwise it results in Bool:false. As a trivial case, this function's result is Bool:true if attr_names is empty.
sys.std.QRelation.attr_names
function sys.std.QRelation.attr_names result set_of.Name params { topic(QRelation) }
This function results in the set of the names of the attributes of its argument.
sys.std.QRelation.is_empty
function sys.std.QRelation.is_empty result Bool params { topic(QRelation) }
This function results in Bool:true iff its argument has a cardinality of zero (that is, it has zero q/tuples), and Bool:false otherwise. Note that if you are using a QMaybe to represent a sparse data item, analagously to a SQL nullable context, then testing the QMaybe with is_empty is analagous to testing a SQL nullable with is null.
sys.std.QRelation.is_not_empty
function sys.std.QRelation.is_not_empty result Bool params { topic(QRelation) }
This function is exactly the same as sys.std.QRelation.is_empty except that it results in the opposite boolean value when given the same argument. And following the analogy with is_empty, is_not_empty is analagous to SQL's is not null.
sys.std.QRelation.has_key
function sys.std.QRelation.has_key result Bool params { topic(QRelation), attr_names(set_of.Name) }
This function results in Bool:true iff its topic argument has a (unique) key over the subset of its attributes whose names are specified by its attr_names argument; otherwise it results in Bool:false. This function will fail if topic does not have all of the attributes named by attr_names. As a trivial case, this function's result is Bool:true if topic is empty.
sys.std.QRelation.empty
function sys.std.QRelation.empty result Relation params { topic(QRelation) }
This function results in the empty relation of the same heading of its argument, that is having the same degree and attribute names; it has zero tuples.
sys.std.QRelation.power_set
function sys.std.QRelation.power_set result quasi_set_of.QRelation params { topic(QRelation) }
This function results in the power set of its argument. The result is a QSet whose sole attribute is QRelation-typed (its type is nominally the same as that of the argument) and which has a q/tuple for every distinct subset of q/tuples in the argument. The cardinality of the result is equal to 2 raised to the power of the cardinality of the argument (which may easily lead to a very large result, so use this function with care). Note that the N-adic relational union of the power set of some q/relation is that q/relation; the N-adic intersection of any power set is the empty relation.
sys.std.QRelation.transitive_closure
function sys.std.QRelation.transitive_closure result QRelation params { topic(QRelation) }
This function results in the transitive closure of its argument. The argument must be a binary q/relation whose attributes are both of the same type, and the result is a q/relation having the same heading and a body which is a superset of the argument's q/tuples. Assuming that the argument represents all of the node pairs in a directed graph that have an arc between them, and so each argument q/tuple represents an arc, transitive_closure will determine all of the node pairs in that graph which have a path between them (a recursive operation), so each q/tuple of the result represents a path. The result is a superset since all arcs are also complete paths. The transitive_closure function is intended to support recursive queries, such as in connection with the "part explosion problem" (the problem of finding all components, at all levels, of some specified part).
sys.std.QRelation.reduction
function sys.std.QRelation.reduction result QTuple params { topic(QRelation), func(FuncRef), assuming(QTuple)?, identity(QTuple) }
This function is a generic reduction operator that recursively takes each pair of q/tuples in topic and applies an argument-specified q/tuple value-resulting function (which is both commutative and associative) to the pair until just one input q/tuple is left, which is the result. The function to apply is named in the func argument, and that function must have 3 arguments named v1, v2, assuming; the last parameter is curried with the same-named argument of reduction, and the first 2 parameters are the 2 input q/tuples for an invocation. If topic has zero q/tuples, then reduction results in the q/tuple given in identity. Note that identity may be changed to take a function name rather than a value, for consistency with func. This function will fail|warn if the |declared headings of identity and topic aren't compatible.
sys.std.QRelation.maybe_reduction
function sys.std.QRelation.maybe_reduction result quasi_maybe_of.QTuple params { topic(QRelation), func(FuncRef), assuming(QTuple)? }
This function is exactly the same as sys.std.QRelation.reduction except that it does not take an identity argument, and it results in a QMaybe of what is otherwise the result type, and that result has zero elements if the argument has zero elements.
sys.std.QRelation.map
function sys.std.QRelation.map result QRelation params { topic(QRelation), result_attr_names(set_of.Name), func(FuncRef), assuming(QTuple)? }
This function provides a convenient one-place generalization of per-q/tuple transformations that otherwise might require the chaining of up to a half-dozen other operators like restriction, extension, and rename. This function results in a q/relation each of whose q/tuples is the result of applying, to each of the q/tuples of its topic argument, the QTuple-resulting function named in its func argument when the latter function is curried by its assuming argument. There is no restriction on what attributes the result q/tuple of func may have (except that all q/tuples from func must have compatible headings); this q/tuple from func would completely replace the original q/tuple from topic. The result q/relation has a cardinality that is the same as that of topic, unless the result of func was redundant q/tuples, in which case the result has appropriately fewer q/tuples. As a trivial case, if func is defined to unconditionally result in the same q/tuple as its own topic argument, then this function results simply in topic; or, if func is defined to have a static result, then this function's result will have just 0..1 q/tuples. Now, map requires the extra result_attr_names argument to prevent ambiguity in the general case where topic might have zero q/tuples, because in that situation, func would never be invoked, and the names of the attributes of the result are not known (we don't generally assume that map can reverse-engineer func to see what attributes it would have resulted in). This function will fail if topic has at least 1 q/tuple and the result of func does not have matching attribute names to those named by result_attr_names.
SYSTEM-DEFINED GENERIC MULTIPLE INPUT QUASI-/RELATION FUNCTIONS
These functions are applicable to mainly q/relation types, but are generic in that they typically work with any q/relation types.
sys.std.QRelation.is_proper_subset
function sys.std.QRelation.is_proper_subset result Bool params { look_in(QRelation), look_for(QRelation) }
This function is exactly the same as sys.std.Core.QRelation.is_subset except that it results in Bool:false if its 2 arguments are identical.
sys.std.QRelation.is_not_proper_subset
function sys.std.QRelation.is_not_proper_subset result Bool params { look_in(QRelation), look_for(QRelation) }
This function is exactly the same as sys.std.QRelation.is_proper_subset except that it results in the opposite boolean value when given the same arguments.
sys.std.QRelation.is_disjoint
function sys.std.QRelation.is_disjoint result Bool params { topic(QRelation), other(QRelation) }
This function results in Bool:true iff the set of q/tuples comprising each of its 2 arguments are mutually disjoint, that is, iff the intersection of the 2 arguments is empty; it results in Bool:false otherwise. This function's 2 parameters are mutually commutative.
sys.std.QRelation.is_not_disjoint
function sys.std.QRelation.is_not_disjoint result Bool params { topic(QRelation), other(QRelation) }
This function is exactly the same as sys.std.QRelation.is_disjoint except that it results in the opposite boolean value when given the same arguments.
sys.std.QRelation.exclusion
function sys.std.QRelation.exclusion result QRelation params { topic(quasi_bag_of.QRelation) }
This function results in the relational exclusion/exclusive-or of the N element values of its argument; it is a reduction operator that recursively takes each pair of input values and relationally excludes (which is both commutative and associative) them together until just one is left, which is the result. The result q/relation has the same heading as all of its inputs, and its body contains every q/tuple that is in just an odd number of the input q/relations. Matters concerning a topic with zero values are as per sys.std.Core.QRelation.union; this function will fail when given such, and the per-distinct-heading identity value for relational exclusion is the same as for relational union. Note that this operation is also legitimately known as symmetric difference.
sys.std.QRelation.composition
function sys.std.QRelation.composition result QRelation params { topic(QRelation), other(QRelation) }
This function results in the relational composition of its (mutually commutative) 2 arguments. It is conceptually a short-hand for first doing an ordinary relational join between its 2 arguments, and then performing a relational projection on all of the attributes that only one of the arguments has; that is, the result has all of and just the attributes that were not involved in matching the q/tuples of the 2 arguments. This function will fail|warn any time that join would fail|warn on the same 2 input q/relations.
sys.std.QRelation.join_with_group
function sys.std.QRelation.join_with_group result QRelation params { primary(QRelation), secondary(QRelation), group_attr(Name) }
This function is a short-hand for first taking a (natural inner) join of its primary and secondary arguments, and then taking a group on all of the attributes that only the secondary argument had, such that the attribute resulting from the group has the name group_attr. The result has 1 q/tuple for every q/tuple of primary where at least 1 matching q/tuple exists in secondary. This function will fail if group_attr is the same name as any source attribute that wasn't grouped. This function is a convenient tool for gathering both parent and child records from a database using a single query while avoiding duplication of the parent record values.
SYSTEM-DEFINED RELATIONAL RANKING AND QUOTA FUNCTIONS
These additional functions are specific to supporting ranking and quotas. Each ord_assuming parameter is optional and defaults to the zero-attribute tuple if no explicit argument is given to it.
sys.std.QRelation.rank
function sys.std.QRelation.rank result QRelation params { topic(QRelation), name(Name), ord_func(FuncRef), ord_assuming(QTuple)? }
This function results in the relational extension of its topic argument by a single NNInt-typed attribute whose name is provided by the name argument, where the value of the new attribute for each q/tuple is the rank of that q/tuple as determined by the (total) order_determination function named in the ord_func argument when the latter function is curried by the ord_assuming argument. The order_determination function compares q/tuples, with each invocation of it getting a topic q/tuple as each its topic and other arguments. The new attribute of rank's result has a value of zero for its ranked-first q/tuple, and each further consecutive ranked q/tuple has the next larger integer value. Note that rank provides the functionality of SQL's "RANK" feature but that the result of rank is always a total ordering (as per a (total) order_determination function) and so there is no "dense" / "not dense" distinction (however a partial ordering can be implemented over it). See also the sys.std.QArray.QArray_from_wrap function, which is the same as sys.std.QRelation.rank but that it wraps the source q/tuples rather than just adding an attribute to them.
sys.std.QRelation.limit
function sys.std.QRelation.limit result QRelation params { topic(QRelation), ord_func(FuncRef), ord_assuming(QTuple)?, min_rank(NNInt), max_rank(NNInt) }
This function results in the relational restriction of its topic argument as determined by first ranking its q/tuples as per rank function (using ord_func and ord_assuming) and then keeping just those q/tuples whose rank is within the inclusive range specified by the min_rank and max_rank arguments (rank's extra attribute is not kept). The limit function implements a certain kind of quota query where all the result q/tuples are consecutive in their ranks. This function will fail if max_rank is before min_rank. It is valid for min_rank or max_rank to be greater than the maximum rank of the source q/tuples; in the first case, the result has zero q/tuples; in the second case, the result has all remaining q/tuples starting at min_rank. If topic has any q/tuples and min_rank matches the rank of a source q/tuple, then the result will always have at least 1 q/tuple. Note that limit provides the functionality of SQL's "LIMIT/OFFSET" feature in combination with "ORDER BY" but that the result q/tuples of limit do not remain ordered (but see sys.std.QArray.limit_of_QArray_from_wrap for an alternative).
SYSTEM-DEFINED RELATIONAL SUBSTITUTION FUNCTIONS
These additional functions are specific to supporting substitutions. Each \w*assuming parameter is optional and defaults to the zero-attribute tuple if no explicit argument is given to it.
sys.std.QRelation.substitution
function sys.std.QRelation.substitution result QRelation params { topic(QRelation), attr_names(set_of.Name), func(FuncRef), assuming(QTuple)? }
This function is similar to extension except that it substitutes values of existing q/relation attributes rather than adding new attributes. The result q/relation has the same heading as topic. The result q/tuple of the function named in func must have a heading that is a subset of the heading of topic; corresponding values resulting from the function named in func will replace the values of the q/tuples of topic. The result q/relation has a cardinality that is the same as that of topic, unless the result of any substitutions was redundant q/tuples, in which case the result has appropriately fewer q/tuples. As a trivial case, if func is defined to unconditionally result in either the degree-zero tuple or in the same q/tuple as its own topic argument, then this function results simply in topic; or, if func is defined to have a static result and it replaces all attributes, then this function's result will have just 0..1 q/tuples. Now, strictly speaking, substitution could conceivably be implemented such that each result from func is allowed to specify replacement values for different subsets of topic attributes; however, to improve the function's predictability and ease of implementation over disparate foundations, substitution requires the extra attr_names argument so that users can specify a consistent subset that func will update (possibly to itself). This function will fail if topic has at least 1 q/tuple and the result of func does not have matching attribute names to those named by attr_names.
sys.std.QRelation.static_substitution
function sys.std.QRelation.static_substitution result QRelation params { topic(QRelation), attrs(QTuple) }
This function is a simpler-syntax alternative to sys.std.QRelation.substitution in the typical scenario where every q/tuple of a q/relation, given in the topic argument, is updated with identical values for the same attributes; the new attribute values are given in the attrs argument.
sys.std.QRelation.subst_in_restr
function sys.std.QRelation.subst_in_restr result QRelation params { topic(QRelation), restr_func(FuncRef), restr_assuming(QTuple)?, subst_attr_names(set_of.Name), subst_func(FuncRef), subst_assuming(QTuple)? }
This function is like substitution except that it only transforms a subset of the q/tuples of topic rather than all of them. It is a short-hand for first separating the q/tuples of topic into 2 groups where those passed by a relational restriction (defined by restr_func and restr_assuming) are then transformed (defined by subst_attr_names, subst_func and subst_assuming), then the result of the substitution is unioned with the un-transformed group. See also the subst_in_semijoin function, which is a simpler-syntax alternative for subst_in_restr in its typical usage where restrictions are composed simply of anded or ored tests for attribute value equality.
sys.std.QRelation.static_subst_in_restr
function sys.std.QRelation.static_subst_in_restr result QRelation params { topic(QRelation), restr_func(FuncRef), restr_assuming(QTuple)?, subst(QTuple) }
This function is to sys.std.QRelation.subst_in_restr what sys.std.QRelation.static_substitution is to sys.std.QRelation.substitution. See also the static_subst_in_semijoin function.
sys.std.QRelation.subst_in_semijoin
function sys.std.QRelation.subst_in_semijoin result QRelation params { topic(QRelation), restr(QRelation), subst_attr_names(set_of.Name), subst_func(FuncRef), subst_assuming(QTuple)? }
This function is like subst_in_restr except that the subset of the q/tuples of topic to be transformed is determined by those matched by a semijoin with restr rather than those that pass a generic relational restriction.
sys.std.QRelation.static_subst_in_semijoin
function sys.std.QRelation.static_subst_in_semijoin result QRelation params { topic(QRelation), restr(QRelation), subst(QTuple) }
This function is to sys.std.QRelation.subst_in_semijoin what sys.std.QRelation.static_substitution is to sys.std.QRelation.substitution.
SYSTEM-DEFINED RELATIONAL OUTER-JOIN FUNCTIONS
These additional functions are specific to supporting outer-joins.
sys.std.QRelation.outer_join_with_group
function sys.std.QRelation.outer_join_with_group result QRelation params { primary(QRelation), secondary(QRelation), group_attr(Name) }
This function is the same as sys.std.QRelation.join_with_group except that it results in a half-outer natural join rather than an inner natural join; every q/tuple of primary has exactly 1 corresponding q/tuple in the result, but where there were no matching secondary q/tuples, the result attribute named by group_attr contains zero q/tuples rather than 1+.
sys.std.QRelation.outer_join_with_maybes
function sys.std.QRelation.outer_join_with_maybes result QRelation params { primary(QRelation), secondary(QRelation) }
This function results in a plain half-outer natural join of its primary and secondary arguments where all the result attributes that come from just secondary are QMaybe-typed; for result q/tuples from matched source q/tuples, each secondary attribute value is a QSingle; for result q/tuples from non-matched primary q/tuples, each secondary attribute value is a Nothing. The outer_join_with_maybes function is Muldis D's answer to the SQL LEFT OUTER JOIN where SQL NULL is implicitly used in result rows that were a non-match.
sys.std.QRelation.outer_join_with_defaults
function sys.std.QRelation.outer_join_with_defaults result QRelation params { primary(QRelation), secondary(QRelation), filler(TypeRef) }
This function is the same as sys.std.QRelation.outer_join_with_static_exten but that the filler q/tuple is the default value of the q/tuple data type whose name is given in the filler argument. This function is a short-hand for invoking outer_join_with_static_exten with the result from invoking sys.std.Core.Universal.default.
sys.std.QRelation.outer_join_with_static_exten
function sys.std.QRelation.outer_join_with_static_exten result QRelation params { primary(QRelation), secondary(QRelation), filler(QTuple) }
This function is the same as sys.std.QRelation.outer_join_with_maybes but that secondary-sourced result attributes are not converted to QMaybe; rather, for result q/tuples from non-matches, the missing values are provided explicitly from the filler argument, which is a q/tuple whose heading matches the projection of secondary's attributes that aren't in common with primary, and whose body is the literal values to use for those missing attribute values.
sys.std.QRelation.outer_join_with_exten
function sys.std.QRelation.outer_join_with_exten result QRelation params { primary(QRelation), secondary(QRelation), exten_func(FuncRef), exten_assuming(QTuple)? }
This function is the same as sys.std.QRelation.outer_join_with_static_exten but that the result q/tuples from non-matches are the result of performing a relational extension on the un-matched primary q/tuples such that each said result q/tuple is determined by applying the function named in exten_func to each said primary q/tuple when the named function is curried using the exten_assuming argument. The exten_assuming parameter is optional and defaults to the zero-attribute tuple if no explicit argument is given to it.
SYSTEM-DEFINED GENERIC RELVAR UPDATERS
sys.std.QRelation.assign_empty
updater sys.std.QRelation.assign_empty update { topic(QRelation) } read {}
This update operator is a short-hand for first invoking the sys.std.QRelation.empty function with the same argument, and then assigning the result of that function to topic. This updater is analagous to the SQL "TRUNCATE" statement.
sys.std.QRelation.assign_exclusion
updater sys.std.QRelation.assign_exclusion update { topic(QRelation) } read { other(QRelation) }
This update operator is a short-hand for first invoking the sys.std.QRelation.exclusion function such that it has 2 input q/relations from assign_exclusion's 2 arguments, and then assigning the result of that function to topic.
sys.std.QRelation.assign_substitution
updater sys.std.QRelation.assign_substitution update { topic(QRelation) } read { func(FuncRef), assuming(QTuple)? }
This update operator is a short-hand for first invoking the sys.std.Core.QRelation.substitution function with the same arguments, and then assigning the result of that function to topic. This updater is analagous to the general case of the unconditional SQL "UPDATE" statement.
sys.std.QRelation.assign_static_substitution
updater sys.std.QRelation.assign_static_substitution update { topic(QRelation) } read { attrs(QTuple) }
This update operator is a short-hand for first invoking the sys.std.Core.QRelation.static_substitution function with the same arguments, and then assigning the result of that function to topic.
sys.std.QRelation.assign_subst_in_restr
updater sys.std.QRelation.assign_subst_in_restr update { topic(QRelation) } read { restr_func(FuncRef), restr_assuming(QTuple)?, subst_func(FuncRef), subst_assuming(QTuple)? }
This update operator is a short-hand for first invoking the sys.std.Core.QRelation.subst_in_restr function with the same arguments, and then assigning the result of that function to topic. This updater is analagous to the general case of the conditional SQL "UPDATE" statement.
sys.std.QRelation.assign_static_subst_in_restr
updater sys.std.QRelation.assign_static_subst_in_restr update { topic(QRelation) } read { restr_func(FuncRef), restr_assuming(QTuple)?, subst(QTuple) }
This update operator is a short-hand for first invoking the sys.std.Core.QRelation.static_subst_in_restr function with the same arguments, and then assigning the result of that function to topic.
sys.std.QRelation.assign_subst_in_semijoin
updater sys.std.QRelation.assign_subst_in_semijoin update { topic(QRelation) } read { restr(QRelation), subst_func(FuncRef), subst_assuming(QTuple)? }
This update operator is a short-hand for first invoking the sys.std.Core.QRelation.subst_in_semijoin function with the same arguments, and then assigning the result of that function to topic. This updater is analagous to the common case of the conditional SQL "UPDATE" statement where the criteria is simply a set of and-ed and or-ed value equality tests.
sys.std.QRelation.assign_static_subst_in_semijoin
updater sys.std.QRelation.assign_static_subst_in_semijoin update { topic(QRelation) } read { restr(QRelation), subst(QTuple) }
This update operator is a short-hand for first invoking the sys.std.Core.QRelation.static_subst_in_semijoin function with the same arguments, and then assigning the result of that function to topic.
SEE ALSO
Go to Muldis::D for the majority of distribution-internal references, and Muldis::D::SeeAlso for the majority of distribution-external references.
AUTHOR
Darren Duncan (perl@DarrenDuncan.net)
LICENSE AND COPYRIGHT
This file is part of the formal specification of the Muldis D language.
Muldis D is Copyright © 2002-2009, Muldis Data Systems, Inc.
See the LICENSE AND COPYRIGHT of Muldis::D for details.
TRADEMARK POLICY
The TRADEMARK POLICY in Muldis::D applies to this file too.
ACKNOWLEDGEMENTS
The ACKNOWLEDGEMENTS in Muldis::D apply to this file too.