Presentation
IMPORTANT NOTICE : This version of the Copper API is deprecated and its removal is planned for the ActivePivot 5.9.0 release. We strongly advise ActivePivot developers to instead use the Copper 2 API when planning new developments.
The new version of the Copper API is available from ActivePivot version 5.8.3 and will be officially released with ActivePivot 5.9.0.
CoPPer is an API that helps you describe the measures of an ActivePivot Cube.
It's main goal is to provide a simple, Spark-alike and comprehensive API to create all the measures an ActivePivot project will need.
Secondary goals are:
- Provide tools to better debug and understand a query processing.
- Provide the ability to change the descriptions created by CoPPer on a running cube (hot replacement).
This user guide is aimed at ActivePivot Server developers, but we'll force ourselves not to rely on any prior-knowledge about post-processors, locations (thus get aggregates queries), analysis hierarchies, prefetchers or subcube.
Hence, newcomers should be able to use CoPPer with the least ActivePivot specific training, and all these technicalities will be concern of the Product Center only. However, prior to reading this, one should be familiar already with the following concepts: Datastore, store references, cube dimensions / hierarchies / levels, context values and MDX query language.
There will be multiple variants of CoPPer in the future, but for now we will use it to add measures on a cube whose dimensions, hierarchies and levels are already defined, on top of an already defined datastore with an already defined selection. The datastore can contain data or be empty for CoPPer to work.
So we use CoPPer as a IDescriptionPostProcessor that will change a cube description containing only the dimensions in order to add the measures.
Why "CoPPer"?... CoPPer is an acronym of "Core PP". It means the Post-Processors logic is now moved to the Core Product and should not be a concern (complex code) in your custom projects anymore. Copper (the material) happens to have also a very good Electrical conductivity, which is something you will need a lot in a data pipeline hardware, as opposed to sparks.
Status
CoPPer is released with ActivePivot 5.7.0. There is already a wide range of working calculations that anybody can use and they are described in examples (see below). You are encouraged to test them and report us any issue you encounter while trying these examples on your projects. You can also try to write calculations without following any examples if you think it matches a use-case you have in your project, but if you do so there are higher risk on hitting current limitations of CoPPer. You should anyway report us the issues you encounter this way: it will help us prioritize the next developments when having associated use-cases, or at least improve our error messages if they weren't helpful.
The hot replacement feature is not available yet, you can only use CoPPer to create the descriptions of your measures in the description of the cube of your project.
Retro-compatibility
There are some use-cases that are yet not covered by CoPPer, and there are some optimizations that you performed in an already existing project in your post-processors that have no equivalent in CoPPer. To ease your transition to CoPPer in these situations CoPPer has a retro-compatibility mechanism allowing you to use your post-processor along CoPPer code.
The cube description you build in your project can include your post-processors before your call to .withDescriptionPostProcessor(new CopperActivePivotDescriptionPostProcessor(...))
, and you can:
- use measures created by CoPPer in your post-processors as underlying measures
- use your post-processors within your CoPPer calculations, via
context.getPostProcessor(measureName)
that returns a column that can be used in your computations
The dataset returned by context.createDatasetFromFacts
even contains directly all the post-processors you created in your project with their measure name as column name, so you can directly use them here.
This way you can start migrating progressively your projects: you can first migrate all pre-aggregated measures, then all the post-processors whose behavior is close to the examples given above. Or if a part of a complex post-processor is close to one of the examples you can break it down and keep only the complex part outside CoPPer. Then you can try to migrate the rest and report us any issue you encounter so that we can prioritize the next developments on CoPPer.