Exporting and Importing System-Defined Aggregate Definitions

AtScale supports migrating a cube's system-defined aggregate definitions from one system to another as of version 2021.2.0. Aggregate definitions may be exported to a file and then imported into a separate AtScale system where the same cube has been published. This feature is useful when businesses wish to:

1. Eliminate the aggregate training step on a production system. This can be accomplished by migrating a set of System-Defined aggregates from a staging system that was created as part of the business's testing process. This process may be automated using the corresponding Export and Import API's.
2. Migrate aggregate definitions from a Production system to a Staging system to support performance tuning activities.

In order to migrate System-Defined Aggregates from one system to another, the following restrictions apply:

1. System-Defined Aggregates can only be moved between cubes with the same Cube ID. The Cube ID is an internal, globally unique identifier, that is stored in the Project export file. To migrate System-Defined aggregate definitions from one system to another, the project must first be imported into the target system and then published.
2. Aggregate definitions are only portable between instances of AtScale that are of the same release version. System-Defined Aggregate definitions cannot be imported to AtScale versions that are older than the source system. Importing System-Defined Aggregates from older versions of AtScale to newer versions is likely to work, however backwards compatibility is not guaranteed.
3. Aggregate definitions that already exist in the target system will not fail the import operation, however they will be ignored by the importer and reported back to the user as duplicates.

info

Attention

NOTE: User-Defined Aggregates (UDA's) are part of the Project definition. UDA definitions are included with the Project Export and Import functionality and are not included in System-Defined export files.

Before you begin

1. Ensure that your target system (where you want to import aggregate definitions) is the same or newer AtScale release version than the source system. For best results, the two systems should be the same AtScale version.

2. Ensure that your source and target systems have the same published cube definition. Exporting, Importing, and Publishing your project into the target system will ensure that you have the correct Cube ID, cube version and UDA's deployed to your target Engine.

3. Users who export aggregates must have the following (Org-scoped) role permissions: Read Published Projects, View Aggregates, Login, Publish Projects

4. Users who import aggregates must have the following permissions:

   • Run-time Cube permission: Query
   • Org-scoped role permissions: Read Published Projects, Manage Aggregates, View Aggregates, Login, Publish Projects

Export Procedure

After your source system has the desired set of aggregates defined for a published project, you may export the system-defined aggregates with the following procedure.

1. Go to the Published Project Page by clicking: PROJECTS > YOUR PROJECT NAME. Under the "PUBLISHED" section, click the name of the published Project.
2. Click the "Build" tab.
3. Authorized users will see the "EXPORT AGGREGATE DEFINTIONS" section. Click the "DOWNLOAD" button. See the "Before You Begin" section for a description of the required permissions.
4. The system will download a file containing the aggregate definitions named after your Org, Project, Cube and suffixed with "_AggDefs.json"

Import Procedure

note

NOTE: Importing System-Defined aggregate definitions will immediately queue the aggregates for building. Users who wish to avoid adding the additional aggregate build load to the data warehouse(s) during busy times may wish to perform the import during off-peak hours.

A System-Defined Aggregate Definition export file may be imported to another system with the following procedure.

1. Ensure that the target system has an identical copy of the Project and Cube. This may be accomplished by first exporting and importing the Project .xml file, followed by publishing the project.

2. On the target system, go to the Published Project Page by clicking: PROJECTS > YOUR PROJECT NAME. Under the "PUBLISHED" section, click the name of the published Project.

3. Click the "Build" tab.

4. Authorized users will see the "IMPORT AGGREGATE DEFINTIONS" section. Click the "BROWSE" button. See the "Before You Begin" section for a description of the required permissions.

5. Browse to the export file and click "Open" to begin the upload.

6. If the file is invalid, corrupt, or excessively large, then the file will be rejected. You will see a red error message in the lower right-hand section of the browser window describing the problem.

7. If the file is valid, Design Center will display the "Import Aggregate Definitions" dialog box and will allow you to do the following:

   1. See the count of aggregates contained in the file.
   2. Optionally ignore the Partition Key and Distribution Key portions of the aggregate definitions. This feature is useful if you wish to test the performance of an aggregate set without the partition or distribution key configurations.
   3. Remap Connections from the source data warehouses to the connections defined in the target system. Note that if you remap to a data warehouse connection that does not support the same data types as the source data warehouse, then the imported aggregate definitions will fail to build.

8. Click the "Aggregate Definitions Import Details" link to display the results of the import operation. This report includes the following information:

   1. The AtScale version number that produced the definition file.
   2. The number of aggregate definitions that were imported.
   3. The number of aggregate definitions that were ignored.
   4. The list of each aggregate definition along with its import status and reason.

9. The Aggregate Definitions are immediately queued for instance creation.

What to do next

• Click the top-level AGGREGATES tab to monitor the build status of individual aggregate definitions.