# mnemosyne

### MODULE

Mnemosyne

### MODULE SUMMARY

A 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
- 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

`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)

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`

### AUTHORS

Hans Nilsson - support@erlang.ericsson.se

mnemosyne 1.2.6
Copyright © 1991-2006 Ericsson AB