Module iodb

Description
Function Index
Function Details

IDEA Object Database API.

Behaviours: application.

Description

IDEA Object Database API. This module is a proxy for all IODB object manipulation requests during each object's lifetime -- from its creation, over searching and updating, to its deletion from database.

Each IODB object is an instance of IODB Data Model which is mapping of Erlang parametrized modules into a hierarchical MUMPS backend implemented by IDEA EGTM application.

For details how to define and compile IODB Data Model, take a look at iodb_model_compiler documentation.

Function Index

create/1	Equivalent to `create(Model, [])`.
create/2	Returns a new instance of data model specified by `Model` and with fields loaded from `Data` proplist.
drop/1	Simply delete the `Object` with all the values and indices.
drop/2	Delete the object of `Model` identified by its `Id`.
exists/2	Check whether the object of `Model` identified by `Id` exists in the database.
fetch/2	Attempts to return an instance of model specified by `Model` stored in database with `Id` primary index.
find/1	Equivalent to `find(Model, [])`.
find/2	Find all the objects of specified `Model`.
find/4	Find object of specified `Model` that exactly match a specific criteria `Conditions`.
foreach/1	Equivalent to `foreach(Model, CounterFun)`.
foreach/2	Call function `Fun` on all the hits of Model/Object `next` iterator function.
start/0	Start IDEA Object Database Application.
start/2	application:start callback, do not use directly!
stop/0	Stop IDEA Object Database Application.
stop/1	application:stop callback, do not use directly!

Function Details

create/1

create(Model) -> any()

Equivalent to create(Model, []).

create/2

create(Model::model_name(), Data::model_data()) -> Object::model_instance() | {error, Reason::model_error()}

Returns a new instance of data model specified by Model and with fields loaded from Data proplist.

drop/1

drop(Object::model_instance()) -> ok | {error, Error::model_error()}

Simply delete the Object with all the values and indices.

drop/2

drop(Model::model_name(), Id::string()) -> ok | {error, Error::model_error()}

Delete the object of Model identified by its Id.

exists/2

exists(Model::model_name(), Id::string()) -> Result::boolean() | {error, model_error()}

Check whether the object of Model identified by Id exists in the database.

For complex multi-dimensional indices, take a look at the trick described in documentation of fetch.

fetch/2

fetch(Model::model_name(), Id::string()) -> model_instance() | {error, model_error()}

Attempts to return an instance of model specified by Model stored in database with Id primary index.

Note that multi-index records are not fully supported at the moment.

If you need to fetch object with complex multi-dimensional index [x, y, id], you have to ensure it contains all the index fields x and y filled and id is "primary" index (= last key in subscript) filled by fetch automatically to be Id from argument.

find/1

find(Model) -> any()

Equivalent to find(Model, []).

find/2

find(Model::model_name(), Conditions::[]) -> [model_instance()]

Find all the objects of specified Model.

find/4

find(Model::model_name(), Conditions::model_conditions(), Start::integer(), Limit::integer()) -> [model_instance()]

Find object of specified Model that exactly match a specific criteria Conditions.

This function, as other variants of find, is slow because it loads all the fields of each object for Conditions matching purposes. In future, the search will be boosted by search optimalization using index_by_* fields.

Optional argument of Start says how many matching objects ignore before find starts collecting objects into result accumulator.

Optional argument of Limit specifies the maximum number of matching objects to return.

For example, if we have objects:

{person, [{id, 1}, {name, "John"}, {Age, 30}]}
{person, [{id, 2}, {name, "Mark"}, {Age, 30}]}
{person, [{id, 3}, {name, "Tom"}, {Age, 30}]}
{person, [{id, 4}, {name, "Tom"}, {Age, 25}]}
{person, [{id, 5}, {name, "John"}, {Age, 30}]}
{person, [{id, 6}, {name, "Tom"}, {Age, 40}]}
{person, [{id, 7}, {name, "John"}, {Age, 30}]}

and we expect following shorthand function:

  Finder = fun
    (C) -> [ P:id () || P <- find (person, C) ];
    (C, S, L) -> [ P:id () || P <- find (person, C, S, L) ]
  end.

then we can get following results:

[P:id () || P <- find (person)] gives [1,2,3,4,5,6,7]
Finder ([{age, 30}]) gives [1,2,3,5,7]
Finder ([{age, 30}, {name, "John"}]) gives [1,5,7]
Finder ([{name, "John"}], 0, 2)) gives [1,5]
Finder ([{name, "John"}], 1, 2)) gives [5,7]
Finder ([{name, "John"}], 2, 2)) gives [7]

foreach/1

foreach(X::model_name() | model_instance()) -> Count::integer() | {error, model_error()}

Equivalent to foreach(Model, CounterFun).

foreach/2

foreach(X::model_name() | model_instance(), Fun::accumulator_function()) -> Count::integer() | {error, model_error()}

Call function Fun on all the hits of Model/Object next iterator function.

First argument may be Model Instance as well as just Model Name -- in the case of Model Name, an empty instance is created and iterator is executed on this dummy object.

If the first argument is Model Instance (object), the iterator is executed directly on such an object. This is very useful for Models with complex multi-dimensional indices -- we just pass an object that has defined all the keys except the last subscript and foreach will go through all these last key occurences.

Second argument Fun is function of arity 2 that implements decision logic whether to return the object or whether to ignore it. Fun takes first argument of an object to be evaluated (returned from iterator) and second parameter of an accumulator with previously collected results. If the object is to be collected Fun will append it to accumulator and return it. Otherwise, Fun returns an original accumulator without any change.

Generated by EDoc, Jun 10 2012, 19:21:56.