Mnemosyne(3)

MODULE
mnemosyne - The query language support for the DBMS Mnesia

DESCRIPTION

Queries 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 '<' (less than), function calls and similar.

Mnesia has two query interfaces which are used together:

    *   Mnemosyne, which is this module

    *   query list comprehensions, an Erlang language construct for the queries.

The exact syntax of query list comprehensions are described in a separate section of this document.

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:
      -record(person, {name,age}).
      Handle =
           query
               [ P.name || P <- table(person) ]
           end,
      L = mnesia:transaction(
           fun() ->
               mnemosyne:eval(Handle)
           end)

The example above matches a list of all names in the table "person" with the variable L. Note the following points:

    *   Each database table must have a corresponding record declaration.

    *   A query is declared with
                  query [ <pattern> || <body> ] end

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

        The whole query could therefore be read as follows: "Make the list of all names of P such that P is taken from the table person".

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

    *   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.

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

    *   A simple all-answer query as in the example shown above. This function is eval/1.

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

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

Let us reconsider the previous example, this time with cursors. In the following example, we will get just five names without evaluating all of the answers:
      -record(person, {name,age}).
      Handle =
           query
               [ P.name || P <- table(person) ]
           end,
      L = mnesia:transaction(
           fun() ->
               Cursor = mnemosyne:cursor(Handle),
               As = mnemosyne:next_answers(Cursor, 5, 5),
               mnemosyne:delete_cursor(Cursor),
               As
           end)

The third way of evaluating a query is by a further division of the query process. The cursor/1 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:
      -record(person, {name,age}).

      Handle =
           query
               [ P.name || P <- table(person) ]
           end,

      QuerySetup = mnemosyne:setup_query(Handle),
      L = mnesia:transaction(
           fun() ->
               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)

EXPORTS

all_answers(Cursor) -> Answer

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

    Note: This must be evaluated inside a transaction.

cursor(Handle) -> Cursor
cursor(Handle,Nprefetch) -> Cursor

    Sets up a query for evaluation and starts an answer pre-fetch. Nprefetch 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.

    Note: This must be evaluated inside a transaction.

delete_cursor(Cursor)

    Deletes the Cursor and associated query evaluation.

    Note: This must be evaluated inside a transaction.

delete_query(QuerySetup)

    Deletes a query setup.

eval(Handle) -> Answers

    Starts a query evaluation according to the Handle and collects all answers in one operation.

    Note: This must be evaluated inside a transaction.

init_query(QuerySetup) -> Cursor
init_query(QuerySetup,Nprefetch) -> Cursor

    Performs the last short step in starting a query from QuerySetup. Nprefetch defines the number of answers to pre-fetch as in cursor/2. The default value is 1.

    Note: This must be evaluated inside a transaction.

next_answers(Cursor) -> Answers
next_answers(Cursor,Nmin,Nmax) -> Answers

    Fetches the next answers from the query evaluation identified by Cursor. At least Nmin and at most Nmax answers are collected. If less than Nmin 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.

    Note: This must be evaluated inside a transaction.

reoptimize(Handle) -> Handle

    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 Handle 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.

setup_query(Handle) -> QuerySetup

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

version() -> String

    Returns the current module version.

List Comprehension

There must be a directive in the Erlang file telling the compiler how to treat queries. This directive is:
-include_lib("mnemosyne/include/mnemosyne.hrl").

A list comprehension consists of:
                query [ <pattern> || <body> ] end

The <pattern> is a description of the terms that are returned by a query. Details of how to obtain the actual values in the <pattern> is given by the <body>.

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

The <body> takes a sequence of goals separated by ",". The possible goals are:

    *   <logical-variable> <- table( <table-name> [ , <table-type> ] )

    *   <logical-variable> <- rule( <rule-name> )

    *   <logical-variable> <- rule( <module> : <rule-name> )

    *   <logical-variable> <- <erlang-list-expression>

    *   <expression> <relop> <expression>

    *   <erlang-test-expression>

A <logical-variable> is written exactly as an Erlang variable. The <table-name>, <table-type>, <rule-name> and <module> are atoms. The <table-name> and <table-type> 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.

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

Erlang variables are allowed in all variants of <expression> and in <pattern>. They must always be bound in the query list comprehension.

logical variables 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 f1 in variable X is just X.f1. The query compiler notifies when it cannot deduce the corresponding record. The explicit form is X#r.f1 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.

Erlang variables are allowed in <expression> and in some places as described above. They must always be bound in the query list comprehension.

Errors in the description are reported as exceptions in the Erlang standard format as follows:
      {error, {Line,Module,Msg}}

The descriptive English text is returned by calling
      Module:format_error(Msg)

  Note:

A function used in a query list comprehension must never directly or indirectly:

    1.  have side effects

    2.  access the database either by a query
         or by Mnesia functions

    3.  spawn processes

    4.  send or receive messages

Rules (Views)

A rule (or view) is a declaration of how to combine data from sources as a kind of "subroutine". Assume that we have the following query list comprehension:
      query
          [ Employee || Employee <- table(employee),
                        Employee.department = sales  ]
      end

This retrieves a list of all sales employees. This could be formulated in the following rule:
      sales(E, employee) :-
              E <- table(employee),
              E.salary = sales.

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

The sales rule may now be used in a query list comprehension:
      query
          [ SalesPerson || SalesPerson <- rule(sales) ]
      end

The SalesPerson is an employee record because of the declaration of the rule above. Another example lists the names of all female sales people:
      query
          [ SalesPerson.name || SalesPerson <- rule(sales),
                                SalesPerson.sex = female   ]
      end

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 module:name. After the :-, there is the usual <body> as in the query list comprehension.

Generated Functions

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:

    *   MNEMOSYNE QUERY/2

    *   MNEMOSYNE RECFUNDEF/1

    *   MNEMOSYNE RULE/1

AUTHOR
Hans Nilsson - support@erlang.ericsson.se