File: mnemosyne.html

package info (click to toggle)
erlang-doc-html 1%3A11.b.2-1
links: PTS
area: main
in suites: etch, etch-m68k
size: 23,284 kB
ctags: 10,724
sloc: erlang: 505; ansic: 323; makefile: 62; perl: 61; sh: 45
file content (663 lines) | stat: -rw-r--r-- 17,395 bytes
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!-- This document was generated using DocBuilder 3.3.3 -->
<HTML>
<HEAD>
  <TITLE>mnemosyne</TITLE>
  <SCRIPT type="text/javascript" src="../../../../doc/erlresolvelinks.js">
</SCRIPT>
  <STYLE TYPE="text/css">
<!--
    .REFBODY     { margin-left: 13mm }
    .REFTYPES    { margin-left: 8mm }
-->
  </STYLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#FF00FF"
      ALINK="#FF0000">
<!-- refpage -->
<CENTER>
<A HREF="http://www.erlang.se">
  <IMG BORDER=0 ALT="[Ericsson AB]" SRC="min_head.gif">
</A>
<H1>mnemosyne</H1>
</CENTER>

<H3>MODULE</H3>
<DIV CLASS=REFBODY>
Mnemosyne
</DIV>

<H3>MODULE SUMMARY</H3>
<DIV CLASS=REFBODY>
A query language support for the DBMS Mnesia
</DIV>

<H3>DESCRIPTION</H3>
<DIV CLASS=REFBODY>

<P><STRONG>Queries</STRONG> are used for accessing the data in a Database
Management System. The query specifies a relation (possibly 
complicated) to all of the selected data. This could involve
several tables as well as conditions such as '&#60;' (less than),
function calls and similar.


<P>Mnesia has two query interfaces which are used together:
<P>
<UL>

<LI>
 Mnemosyne, which is this module
</LI>


<LI>
<STRONG>QLC (Query List Comprehensions)</STRONG>, an Erlang language construct for the queries. This will be the recommended way to perform queries
</LI>


</UL>

<P>The exact syntax of query list comprehensions are
described in a <A HREF="#lcdescr">separate
section</A> of this document.



<P>The query list comprehensions only define the query and the
syntax of the solutions to be returned. The actual evaluation
is determined by calling different functions with a handle
obtained by the list comprehension. For example:


<PRE>
      -record(person, {name,age}).
      Handle = 
           query
               [ P.name || P &#60;- table(person) ]
           end,
      L = mnesia:transaction(
           fun() -&#62;
               mnemosyne:eval(Handle)
           end)
    
</PRE>

<P>The example above matches a list of all names in the table
&#34;person&#34; with the variable <CODE>L</CODE>. Note the
following points:

<P>
<UL>

<LI>
Each database table must have a corresponding record
declaration.<BR>

</LI>


<LI>
A <STRONG>query</STRONG> is declared with
<BR>

<PRE>
          query [ &#60;pattern&#62; || &#60;body&#62; ] end
          
</PRE>


        where <CODE>&#60;pattern&#62;</CODE> is an Erlang term without
         function calls. The notation <CODE>P.name</CODE> means that
         <CODE>P</CODE> is a variable and it has an associated record
         with a field <CODE>name</CODE> which we use. The <CODE>&#60;body&#62;</CODE>
         is a sequence of conditions separated by commas. In the
         example, we have <CODE> P &#60;- table(person) </CODE> which
         means: &#34;<CODE>P</CODE> is taken from the table
         <CODE>person</CODE>&#34;.

<BR>
The whole query could therefore be read as follows: &#34;Make the
         list of all names of <CODE>P</CODE> such that <CODE>P</CODE> is
         taken from the table <CODE>person</CODE>&#34;.

        <BR>
However, the query list comprehension does not return the answers
         but a <STRONG>handle</STRONG>. This handle is used as an argument for 
         different evaluation functions which do the actual query processing.
         In the example we used the simplest, <CODE>eval/1</CODE>, which evaluates 
         the query and returns all the answers.<BR>

</LI>


<LI>
Some parts of the query must be evaluated in a Mnesia
         transaction or by utilizing an alternative Mnesia access context. 
         These functions are marked in the function
         descriptions below. <BR>

</LI>


</UL>

<P>After obtaining a handle from a query list comprehension, the
query can be evaluated in three different ways: 
<P>
<UL>

<LI>
A simple all-answer query as in the example shown above. This
function is <CODE>eval/1</CODE>.

<BR>

</LI>


<LI>
Getting the answers in small or large chunks. The
query may be aborted when enough solutions have been
obtained. These are called <STRONG>cursors</STRONG>. The functions are
<CODE>cursor/1</CODE>, <CODE>cursor/2</CODE>, <CODE>next_answers/1</CODE>,
<CODE>next_answers/3</CODE>, <CODE>all_answers/1</CODE>,
<CODE>all_answers/3</CODE>, and <CODE>delete_cursor/1</CODE>.

<BR>

</LI>


<LI>
An even more sophisticated cursor version where the
time consuming part of the cursor creation can be
done in advance. The functions are <CODE>setup_query/1</CODE>, <CODE> init_query/1</CODE>, <CODE>init_query/2</CODE>,
<CODE>next_answers/1</CODE>, <CODE>next_answers/3</CODE>,
<CODE>all_answers/1</CODE>, <CODE>all_answers/3</CODE>, and
<CODE>delete_query/1</CODE>.
<BR>

</LI>


</UL>

<P>Let us reconsider the previous example, this time with cursors. In the
following example, we will get just five names <STRONG>without evaluating
all of the answers</STRONG>:

<PRE>
      -record(person, {name,age}).
      Handle =
           query
               [ P.name || P &#60;- table(person) ]
           end,
      L = mnesia:transaction(
           fun() -&#62;
               Cursor = mnemosyne:cursor(Handle),
               As = mnemosyne:next_answers(Cursor, 5, 5),
               mnemosyne:delete_cursor(Cursor),
               As
           end)
    
</PRE>

<P>The third way of evaluating a query is by a further
division of the query process. The <CODE>cursor/1</CODE> function is
now split into two. The reason for this is that we can set up the query
when there is plenty of time and initialize it when 
answers are needed quickly. As in the previous example, we will get
just five names:

<PRE>
      -record(person, {name,age}).
      
      Handle = 
           query
               [ P.name || P &#60;- table(person) ]
           end,
      
      QuerySetup = mnemosyne:setup_query(Handle),
      L = mnesia:transaction(
           fun() -&#62;
               Cursor = mnemosyne:init_query(QuerySetup),
               mnemosyne:next_answers(Cursor, 5, 5)
           end),
      
      % Here we may call more init_query-next_answers constructions
      % with the same Handle
      mnemosyne:delete_query(QuerySetup)
    
</PRE>

</DIV>

<H3>EXPORTS</H3>

<P><A NAME="all_answers/1"><STRONG><CODE>all_answers(Cursor) -&#62; Answer</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>Returns all remaining answers from the query identified by
<CODE>Cursor</CODE>. It can be applied after <CODE>next_answers</CODE> to
obtain all answers that are left.

        
<P><STRONG> Note:</STRONG> This must be evaluated inside a transaction.



</DIV>

<P><A NAME="cursor/1"><STRONG><CODE>cursor(Handle) -&#62; Cursor</CODE></STRONG></A><BR>
<A NAME="cursor/2"><STRONG><CODE>cursor(Handle,Nprefetch) -&#62; Cursor</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>Sets up a query for evaluation and starts an answer
pre-fetch. <CODE>Nprefetch</CODE> gives the number of answers to
pre-fetch and must be greater than 0. The default value is
1. A pre-fetch is the first part of a query evaluation. It is placed in a
separate process which may on some occasions speed up the subsequent collection of answers.
        
<P><STRONG> Note:</STRONG> This must be evaluated inside a transaction.

</DIV>

<P><A NAME="delete_cursor/1"><STRONG><CODE>delete_cursor(Cursor)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>Deletes the Cursor and associated query evaluation.
        
<P><STRONG> Note:</STRONG> This must be evaluated inside a transaction.

</DIV>

<P><A NAME="delete_query/1"><STRONG><CODE>delete_query(QuerySetup)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>Deletes a query setup.

</DIV>

<P><A NAME="eval/1"><STRONG><CODE>eval(Handle) -&#62; Answers</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>Starts a query evaluation according to the <CODE>Handle</CODE> and
collects all answers in one operation.
        
<P><STRONG> Note:</STRONG> This must be evaluated inside a transaction.

</DIV>

<P><A NAME="init_query/1"><STRONG><CODE>init_query(QuerySetup) -&#62; Cursor</CODE></STRONG></A><BR>
<A NAME="init_query/2"><STRONG><CODE>init_query(QuerySetup,Nprefetch) -&#62; Cursor</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>Performs the last short step in starting a query from
<CODE>QuerySetup</CODE>. <CODE>Nprefetch</CODE> defines the number of
answers to pre-fetch as in <CODE>cursor/2</CODE>. The default
value is 1.
        
<P><STRONG> Note:</STRONG> This must be evaluated inside a transaction.

</DIV>

<P><A NAME="next_answers/1"><STRONG><CODE>next_answers(Cursor) -&#62; Answers</CODE></STRONG></A><BR>
<A NAME="next_answers/3"><STRONG><CODE>next_answers(Cursor,Nmin,Nmax) -&#62; Answers</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>Fetches the next answers from the query evaluation
identified by <CODE>Cursor</CODE>. At least <CODE>Nmin</CODE> and at
most <CODE>Nmax</CODE> answers are collected. If less than
<CODE>Nmin</CODE> answers are returned; for example, 0, there are
no more answers. If enough answers are not available, but
more are expected, the functions wait for them.
        
<P><STRONG> Note:</STRONG> This must be evaluated inside a transaction.

</DIV>

<P><A NAME="reoptimize/1"><STRONG><CODE>reoptimize(Handle) -&#62; Handle</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>Re-optimizes a query. Queries are always optimized, but the
optimization takes into account the dynamic table
statistics like size, attribute distribution etc. If
a table has changed after obtaining the <CODE>Handle</CODE>
from a query list comprehension, the query execution plan
will no longer be appropriate (although semantically
correct). This function will rearrange the execution plan
according to the current statistics from the database.

</DIV>

<P><A NAME="setup_query/1"><STRONG><CODE>setup_query(Handle) -&#62; QuerySetup</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>Creates a query setup, that is, performs most of
a query evaluation without actually initiating the
actual evaluation.

</DIV>

<P><A NAME="version/0"><STRONG><CODE>version() -&#62; String</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>Returns the current module version.

</DIV>

<H3>List Comprehension</H3>
<DIV CLASS=REFBODY>
<A NAME="lcdescr"><!-- Empty --></A>
<P>There must be a directive in the Erlang file telling the
compiler how to treat queries. This directive is:


<PRE>
-include_lib(&#34;mnemosyne/include/mnemosyne.hrl&#34;).
        
</PRE>

<P>A list comprehension consists of:

<PRE>
                query [ &#60;pattern&#62; || &#60;body&#62; ] end
       
</PRE>

<P>The <CODE>&#60;pattern&#62;</CODE> is a description of the terms that are returned by
a query. Details of how to obtain the actual values in the <CODE>&#60;pattern&#62;</CODE> is
given by the <CODE>&#60;body&#62;</CODE>.


<P>The <CODE>&#60;pattern&#62;</CODE> is an Erlang term without function calls. It typically has
one or more variables from the <CODE>&#60;body&#62;</CODE> which are
instantiated for each answer produced. Every element in the
returned list is composed by instantiating this <CODE>&#60;pattern&#62;</CODE> and
then adding it to the answers.


<P>The <CODE>&#60;body&#62;</CODE> takes a sequence of <STRONG>goals</STRONG> separated by &#34;,&#34;. The
possible goals are:

<P>
<UL>

<LI>
        <CODE>&#60;logical-variable&#62; &#60;- table( &#60;table-name&#62; [ , &#60;table-type&#62; ] )</CODE>
<BR>

</LI>


<LI>
<CODE>&#60;logical-variable&#62; &#60;- rule( &#60;rule-name&#62; )</CODE>
<BR>

</LI>


<LI>
<CODE>&#60;logical-variable&#62; &#60;- rule( &#60;module&#62; : &#60;rule-name&#62; )</CODE>
<BR>

</LI>


<LI>
<CODE>&#60;logical-variable&#62; &#60;- &#60;erlang-list-expression&#62;</CODE>


<BR>

</LI>


<LI>
<CODE>&#60;expression&#62; &#60;relop&#62; &#60;expression&#62;</CODE>
<BR>

</LI>


<LI>
<CODE>&#60;erlang-test-expression&#62;</CODE>
<BR>

</LI>


</UL>

<P>A <CODE>&#60;logical-variable&#62;</CODE> is written exactly as an Erlang
variable. The <CODE>&#60;table-name&#62;</CODE>, <CODE>&#60;table-type&#62;</CODE>, <CODE>&#60;rule-name&#62;</CODE> and
<CODE>&#60;module&#62;</CODE> are atoms. The <CODE>&#60;table-name&#62;</CODE> and <CODE>&#60;table-type&#62;</CODE> may be an
Erlang variable which must be bound at runtime. The logical
variables are local to a list comprehension and shadows any
Erlang variables with the same name.


<P>An <CODE>&#60;expression&#62;</CODE> is any Erlang expression
which may include function calls and
<CODE>&#60;logical-variable&#62;</CODE>. The variants
<CODE>&#60;erlang-list-expression&#62;</CODE> is an
<CODE>&#60;expression&#62;</CODE> which must produce lists where all
elements are records of the same type. The
<CODE>&#60;logical-variable&#62;</CODE> must have the same associated record. The <CODE>&#60;erlang-test-expression&#62;</CODE>
is an <CODE>&#60;expression&#62;</CODE> which only has the values
<CODE>true</CODE> or <CODE>false</CODE>.


<P>Erlang variables are allowed in all variants of
<CODE>&#60;expression&#62;</CODE> and in <CODE>&#60;pattern&#62;</CODE>. They
must always be bound in the query list comprehension.


<P><STRONG>logical variables</STRONG> is local to a query list
comprehension and have an associated Erlang record.
The associated record can in most cases be inferred by
the query compiler. Therefore, the normal notation for the field
<CODE>f1</CODE> in variable <CODE>X</CODE> is just <CODE>X.f1</CODE>. The
query compiler notifies when it cannot deduce the corresponding record. 
The explicit form is <CODE>X#r.f1</CODE> as in ordinary
Erlang. If the type of the record is not deducable at
Erlang compile time, it is more efficient to use the explicit 
form as a help to the compiler.


A variable receiving values from a table will have the
record with the same name as the table.


<P>Erlang variables are allowed in <CODE>&#60;expression&#62;</CODE> and in some places
as described above. They must always be bound in
the query list comprehension.


<P>Errors in the description are reported as exceptions in the
Erlang standard format as follows:

<PRE>
      {error, {Line,Module,Msg}}
    
</PRE>

<P>The descriptive English text is returned by calling

<PRE>
      Module:format_error(Msg)
    
</PRE>
<BR>

<P>
<P>
<TABLE CELLPADDING=4>
  <TR>
    <TD VALIGN=TOP><IMG ALT="Note!" SRC="note.gif"></TD>
    <TD>

<P>A function used in a query list
comprehension must <STRONG>never</STRONG> directly or indirectly:

<P>
<OL>

<LI>
have side effects
         <BR>

</LI>


<LI>
access the database either by a query<BR>

         or by Mnesia functions 
<BR>

</LI>


<LI>
spawn processes
<BR>

</LI>


<LI>
send or receive messages
<BR>

</LI>


</OL>
    </TD>
  </TR>
</TABLE>

</DIV>

<H3>Rules (Views)</H3>
<DIV CLASS=REFBODY>

<P>A <STRONG>rule</STRONG> (or <STRONG>view</STRONG>) is a declaration of how to
combine data from sources as a kind of &#34;subroutine&#34;. Assume
that we have the following query list comprehension:

<PRE>
      query
          [ Employee || Employee &#60;- table(employee),
                        Employee.department = sales  ]
      end
    
</PRE>

<P>This retrieves a list of all sales employees. This could
be formulated in the following rule:

<PRE>
      sales(E, employee) :-
              E &#60;- table(employee),
              E.salary = sales.
    
</PRE>

<P>The <CODE>employee</CODE> declaration in the head of the rule forces the rule argument to
associate the <CODE>employee</CODE> record. If we omit the
declaration, then the associated record would be the rule
name, in this case <CODE>sales</CODE>.
Note that the syntax used in previous versions of Mnemosyne by using an
separate <CODE>argtype</CODE> declaration still works, but the above method is prefered.

<P>The <CODE>sales</CODE> rule may now be used in a query list
comprehension: 

<PRE>
      query
          [ SalesPerson || SalesPerson &#60;- rule(sales) ]
      end
    
</PRE>

<P>The SalesPerson is an <CODE>employee</CODE> record because of the
declaration of the rule above. Another example lists the names
of all female sales people:

<PRE>
      query
          [ SalesPerson.name || SalesPerson &#60;- rule(sales),
                                SalesPerson.sex = female   ]
      end
    
</PRE>

<P>The rule must have one argument when used. Although the declaration 
of a rule looks similar to an ordinary function, no function of that
name is constructed. Hence the name of the rule can be used
for another function. All rules
are automatically exported so they could be referred in other
modules by the usual notation <CODE>module:name</CODE>. After the
<CODE>:-</CODE>, there is the usual <CODE>&#60;body&#62;</CODE> as in the query list
comprehension.

</DIV>

<H3>Generated Functions</H3>
<DIV CLASS=REFBODY>

<P>When compiling queries some extra (hidden) functions
are automatically generated and exported. 
Thus, there cannot be other functions with the same
name and arity within the module. 
Three such generated functions exist. They are:

<P>
<UL>

<LI>
<CODE>MNEMOSYNE QUERY/2</CODE>
</LI>


<LI>
<CODE>MNEMOSYNE RECFUNDEF/1</CODE>
</LI>


<LI>
<CODE>MNEMOSYNE RULE/1</CODE>
</LI>


</UL>

</DIV>

<H3>AUTHORS</H3>
<DIV CLASS=REFBODY>
Hans Nilsson - support@erlang.ericsson.se<BR>

</DIV>
<CENTER>
<HR>
<SMALL>mnemosyne 1.2.6<BR>
Copyright &copy; 1991-2006
<A HREF="http://www.erlang.se">Ericsson AB</A><BR>
</SMALL>
</CENTER>
</BODY>
</HTML>