An aggregate is a function that returns information about a set of query results. For example, the SUM aggregate adds all the query results together and returns the result. An aggregate is invoked in SQL as a single function but is implemented as one or more support functions.
You can use BladeSmith to create new, user-defined aggregates that implement user-defined routines.
You can define two aggregates that have the same name but operate on different data types. An aggregate acts as a template: the aggregate support functions must have the same names for both aggregates. If you overload an aggregate, you cannot add, remove, or change the names of its support functions. Use your new object prefix to begin the name of your aggregate to avoid accidentally overloading an aggregate in another DataBlade module.
The following table describes the properties you specify when you create an aggregate.
| Property | Default Value | Description |
|---|---|---|
| Aggregate name | Aggregate | The name of the aggregate function. If you are
overloading an aggregate, the name can be the name of an existing aggregate;
otherwise, the name must be unique. New aggregate names must begin
with the new object prefix.
See Aggregate Name for more information. |
| Language | C | Which language to use for the aggregate functions:
C or Java.
You must set server compatibility to 9.2 or later to generate code for Java projects. You need the IBM Informix Dynamic Server with J/Foundation upgrade to IBM Informix Dynamic Server to enable Java services. |
| Iteration type | None | The data type on which the aggregate function
operates.
See Iteration Type for restrictions. |
| Initialization parameter | No | Optional. Used only for aggregates whose behavior
can be changed dynamically.
See Initialization Parameter for more information. |
| Return type | None | The data type of the result of the aggregate function. |
| State type | None | The data type of the intermediate aggregation
state. The state type is often POINTER.
See State Type for more information. |
| Initialization function | AggregateInit | The function called before the aggregation begins.
Not required if the state and iteration data types are the same and
there is no initialization parameter.
See Initialization Function for more information. |
| Iteration function | AggregateIter | Called once for every value that is aggregated.
By default, this function accepts null values.
See Iteration Function for more information. |
| Combine function | AggregateComb | Optional. Merges results from parallel iterations.
See Combine Function for more information. |
| Final function | AggregateFinl | Performs computations on the combined state,
cleans up memory, and returns the final value.
See Final Function for more information. |
For information on how aggregates behave, see the IBM Informix: DataBlade API Programmer's Guide.
The following sections describe properties of aggregates.
Use the new object prefix to begin the name of your new aggregate. The aggregate name cannot be the same as another user-defined routine or aggregate unless you are overloading an existing user-defined aggregate. For more information on the new object prefix, see New Object Prefix.
You cannot use the following data types as aggregate iteration types:
The initialization parameter is an argument in the initialization function to customize the aggregation computation. For example, if you defined an aggregate to return the top n values of a query, your initialization parameter can be 3 to select the top three.
The state type holds the partial result information during the aggregation computation. The database server never accesses the state type, so it can be any data type or structure appropriate for the partial results. For example, if you have an aggregate that returns the three largest values from a query result set, your state type can be an array of three integers.
If you are overloading an existing aggregate, the state type must be different for each aggregate.
Select the POINTER data type from the data type list to indicate that your data type is not known to the database server.
The initialization function initializes the data structures required by the rest of the aggregation computation. For example, it can set up smart large objects or temporary files for storing intermediate results.
The initialization function can take an optional initialization parameter to customize the aggregate computation.
The initialization function is not required for simple binary operators that have a state type that is the same as the iteration type.
The iteration function merges a single value of the iteration type with the partial result of the state type and returns the updated partial result.
You can specify whether the iteration function handles null values. If it does not, any null values returned by the query are ignored. If it does handle null values, the iteration function includes them in its computations.
The database server can break up the aggregation computation into several pieces and compute them in parallel. Each piece is computed sequentially; then the results from all pieces are combined into a single result using the combine function. The parallel computation must give the same result as the sequential computation.
The combine function merges partial results of the state type and returns the updated partial result. It can also perform clean-up work by releasing resources acquired by the initialization function.
The combine function can be the same as the iterator function if the aggregate is derived from a simple binary operator whose result type is the same as the state type.
The final function converts a partial result of the state type into the result type. It can also release resources acquired by the initialization function to clean up the result type.
If you do not include a final function, the database server returns the final state type. The final function is not required for aggregates derived from simple binary operators whose result type is the same as the state type.
Home | [ Top of Page | Previous Page | Next Page | Contents | Index ]