mnemosyne

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
QLC (Query List Comprehensions), an Erlang language construct for the queries. This will be the recommended way to perform 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

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