exstreamspeed Reference/es_mba

Reference/es_mba_prepare

Syntax

int es_mba_prepare( struct es_mba *agg,
                    struct es_mbd *resultdef,
                    const char *resultcls,
                    char *queryplan,
                    int queryplansize );

Arguments

`struct es_mba *agg`	Database aggregator.
`struct es_mbd *rdef`	Database definition of result database.
`const char *rcls`	Name of result database class.
`char *queryplan`	Query plan buffer. Populated by es_mba_prepare. Set to NULL if you don't want the query plan.
`int queryplansize`	Size of query plan buffer `queryplan` in bytes.

Return Codes

`ES_ERROR_NONE`	Success. No errors.
`ES_ERROR_NOSINGLEPATH`	Unable to construct single a iteration path through database that allows the aggregator to access all required database fields.
`ES_ERROR_INVALIDFIELDTYPE`	Aggregate result field is not an integer or double, or the type of a pre-existing field in `rcls` does not match that of the required output.
`ES_ERROR_STACKOVERFLOW`	Unable to implement formula due to too many required temporary variables. Solution is to split formula into multiple formulae.

Description

Prepare a query plan for the aggregator to execute. Requires that all key, result, filter and formula fields have already been specified.

The aggregator generates a program (known as a query plan) using the iterator (struct es_mbi ) API to traverse an input database and populate a root node in a result database. rdef is the schema of the result database and rcls is the name of the (root) result class.

For each key and result field, es_mba_prepare() adds a field definition to rcls. rcls is created if it does not yet exist in rdef. If rcls already exists, the key and result fields are merged into it. es_mba_prepare() fails with a ES_ERROR_INVALIDFIELDTYPE error code if the type of any pre-existing field in rcls clashes with the type of any new key and result field with the same name.

es_mba_prepare() attempts to find a single iteration path through the database that will allow it to pick-up all required database fields.

The query plan involves the traversal of a single root node, plus all required child and descendant nodes, using es_mbi_beginfetch() and es_mbi_incfetch(). Any field that cannot be found in this path is acquired by calling es_mbi_findfetch() against other root and associated descendent nodes. Relevent foreign keys required by es_mbi_findfetch() must be available in the initial iteration path.

es_mba_prepare() attempts to pick the most optimal route through the database by minimizing the set of additional es_mbi_findfetch() calls and redundant fetches. If such a route is not possible, es_mba_prepare() fails with a ES_ERROR_NOSINGLEPATH error code.

A textual summary of the query plan is assigned to the queryplan parameter (or not if queryplan is set to NULL).

Implementation of any specified formulae is included in the query plan. If any one formula requires the use of too many temporary variables, es_mba_prepare() will fail with a ES_ERROR_STACKOVERFLOW error. The solution is to break up the formula into seperate pieces.

Once es_mba_prepare() successfully completes it can be executed against input and result databases instances via es_mba_exec().

[Back To Reference] [Back To Reference/es_mba]