Aggregate

List & Update

This API manages the creation and listing of new aggregates.

HTTP REQUEST: GET

List all Aggregates for this Cube.

GET/api/1.0/org/{orgId}/project/{projectId}/cube/{cubeId}/aggregates

URI PARAMETERS

Name	Type	Description
orgId	string	The Organization ID (UUID) for which you are querying.
projectId	string	The Project ID (UUID) for which you are querying.
cubeId	string	The Cube ID (UUID) for which you are querying.

RESPONSES

Code	Description
200	Success.
401	This error will occur if calling user does not have access right for the API.
404	This error will occur if calling user does not have access right for the API.
500	A server error occurred. Check the logs for more details.
503	This error will occur if Design Center APIs are not enabled.

RESPONSE BODY DESCRIPTIONS

Name	Type	Description
id	string	-
name	string	-
properties	CommonProperties	-
attributes	AttributeReferences	-
partitions	PartitionReferences	-

200 Response Body

{
  "status": {
    "i18n_message": "response.ok",
    "message": "OK"
  },
  "response": {
    "aggregate": [
      {
        "id": "67d7c22e-dceb-4188-9860-068091697f9b",
        "name": "My Aggregate",
        "properties": {
          "name": "My Aggregate",
          "notes": "this is an aggregate"
        },
        "attributes": {
          "attribute-ref": [
            {
              "id": "82c14308-3f56-4244-499d-756e80488e64"
            },
            {
              "id": "cd5089b9-e228-45fa-7507-e74fcf88617d"
            },
            {
              "id": "c0bbeb6f-d74c-45f9-43c7-1e5bb8b4bf62",
              "ref-path": {
                "ref": [
                  {
                    "id": "8e5f2b5c-427c-4796-8424-13ce0963ca5a"
                  }
                ]
              }
            },
            {
              "id": "9c8cabbe-6510-48ca-9648-8bc376c649b2"
            },
            {
              "id": "3b6b9a46-22d8-4ed9-9c4b-12612dfa3675"
            },
            {
              "id": "b68a0ca1-93ba-4807-8b54-f2d2654ca71c"
            }
          ]
        },
        "partitions": {}
      }
    ]
  }
}

401 Response Body

{
  "status": {
    "code": 401,
    "i18n_message": "request.error.undefined",
    "message": "There was an unknown error handling your request"
  },
  "response": {
    "error": "Token is expired",
    "message": "Authentication Error: JWT Token Parse Failure",
    "i18n_message": "request.error.undefined",
    "code": 401,
    "more_info": {
      "url": [
        "/api/1.0/org/default/project/05a01949-3af2-44ca-4c0a-fc785dfe524e/cube/737732be-f50e-47c9-7826-920bfe0a9ef5/aggregates"
      ]
    }
  }
}

HTTP REQUEST: POST

Create one or more new Aggregate(s) for this Cube.

POST/api/1.0/org/{orgId}/project/{projectId}/cube/{cubeId}/aggregates

URI PARAMETERS

Name	Type	Description
orgId	string	The Organization ID (UUID) for which you are querying.
projectId	string	The Project ID (UUID) for which you are querying.
cubeId	string	The Cube ID (UUID) for which you are querying.

RESPONSES

Code	Description
200	Success.
401	This error will occur if calling user does not have access right for the API.
404	This error will occur if calling user does not have access right for the API.
500	A server error occurred. Check the logs for more details.
503	This error will occur if Design Center APIs are not enabled.

RESPONSE BODY DESCRIPTIONS

Name	Type	Description
id	string	-
name	string	-
properties	CommonProperties	-
attributes	AttributeReferences	-
partitions	PartitionReferences	-

200 Response Body

{
  "status": {
    "i18n_message": "response.ok",
    "message": "OK"
  },
  "response": {
    "aggregate": [
      {
        "id": "67d7c22e-dceb-4188-9860-068091697f9b",
        "name": "My Aggregate",
        "properties": {
          "name": "My Aggregate",
          "notes": "this is an aggregate"
        },
        "attributes": {
          "attribute-ref": [
            {
              "id": "82c14308-3f56-4244-499d-756e80488e64"
            },
            {
              "id": "cd5089b9-e228-45fa-7507-e74fcf88617d"
            },
            {
              "id": "c0bbeb6f-d74c-45f9-43c7-1e5bb8b4bf62",
              "ref-path": {
                "ref": [
                  {
                    "id": "8e5f2b5c-427c-4796-8424-13ce0963ca5a"
                  }
                ]
              }
            },
            {
              "id": "9c8cabbe-6510-48ca-9648-8bc376c649b2"
            },
            {
              "id": "3b6b9a46-22d8-4ed9-9c4b-12612dfa3675"
            },
            {
              "id": "b68a0ca1-93ba-4807-8b54-f2d2654ca71c"
            }
          ]
        },
        "partitions": {}
      }
    ]
  }
}

Read, Update & Delete

This API manages the Deletion and Read of Aggregates.

HTTP REQUEST: GET

Read a specific Aggregate.

GET/api/1.0/org/{orgId}/project/{projectId}/cube/{cubeId}/aggregates/{aggregateId}

URI PARAMETERS

Name	Type	Description
orgId	string	The Organization ID (UUID) for which you are querying.
projectId	string	The Project ID (UUID) for which you are querying.
cubeId	string	The Cube ID (UUID) for which you are querying.
aggregateId	string	The Aggregate ID (UUID) for which you are querying.

RESPONSES

Code	Description
200	Success.
401	This error will occur if calling user does not have access right for the API.
404	This error will occur if calling user does not have access right for the API.
500	A server error occurred. Check the logs for more details.
503	This error will occur if Design Center APIs are not enabled.

RESPONSE BODY DESCRIPTIONS

Name	Type	Description
id	string	-
name	string	-
properties	CommonProperties	-
attributes	AttributeReferences	-
partitions	PartitionReferences	-

200 Response Body

{
  "status": {
    "i18n_message": "response.ok",
    "message": "OK"
  },
  "response": {
    "aggregate": [
      {
        "id": "67d7c22e-dceb-4188-9860-068091697f9b",
        "name": "My Aggregate",
        "properties": {
          "name": "My Aggregate",
          "notes": "this is an aggregate"
        },
        "attributes": {
          "attribute-ref": [
            {
              "id": "82c14308-3f56-4244-499d-756e80488e64"
            },
            {
              "id": "cd5089b9-e228-45fa-7507-e74fcf88617d"
            },
            {
              "id": "c0bbeb6f-d74c-45f9-43c7-1e5bb8b4bf62",
              "ref-path": {
                "ref": [
                  {
                    "id": "8e5f2b5c-427c-4796-8424-13ce0963ca5a"
                  }
                ]
              }
            },
            {
              "id": "9c8cabbe-6510-48ca-9648-8bc376c649b2"
            },
            {
              "id": "3b6b9a46-22d8-4ed9-9c4b-12612dfa3675"
            },
            {
              "id": "b68a0ca1-93ba-4807-8b54-f2d2654ca71c"
            }
          ]
        },
        "partitions": {}
      }
    ]
  }
}

HTTP REQUEST: PUT

Update a specific Aggregate.

PUT/api/1.0/org/{orgId}/project/{projectId}/cube/{cubeId}/aggregates/{aggregateId}

URI PARAMETERS

Name	Type	Description
orgId	string	The Organization ID (UUID) for which you are querying.
projectId	string	The Project ID (UUID) for which you are querying.
cubeId	string	The Cube ID (UUID) for which you are querying.
aggregateId	string	The Aggregate ID (UUID) for which you are querying.

RESPONSES

Code	Description
200	Success. Returns the JSON representation of the updated aggregate definition.
401	This error will occur if calling user does not have access right for the API.
404	This error will occur if calling user does not have access right for the API.
500	A server error occurred. Check the logs for more details.
503	This error will occur if Design Center APIs are not enabled.

RESPONSE BODY DESCRIPTIONS

Name	Type	Description
id	string	-
name	string	-
properties	CommonProperties	-
attributes	AttributeReferences	-
partitions	PartitionReferences	-

200 Response Body

{
  "status": {
    "i18n_message": "response.ok",
    "message": "OK"
  },
  "response": {
    "aggregate": [
      {
        "id": "67d7c22e-dceb-4188-9860-068091697f9b",
        "name": "My Aggregate",
        "properties": {
          "name": "My Aggregate",
          "notes": "this is an aggregate"
        },
        "attributes": {
          "attribute-ref": [
            {
              "id": "82c14308-3f56-4244-499d-756e80488e64"
            },
            {
              "id": "cd5089b9-e228-45fa-7507-e74fcf88617d"
            },
            {
              "id": "c0bbeb6f-d74c-45f9-43c7-1e5bb8b4bf62",
              "ref-path": {
                "ref": [
                  {
                    "id": "8e5f2b5c-427c-4796-8424-13ce0963ca5a"
                  }
                ]
              }
            },
            {
              "id": "9c8cabbe-6510-48ca-9648-8bc376c649b2"
            },
            {
              "id": "3b6b9a46-22d8-4ed9-9c4b-12612dfa3675"
            },
            {
              "id": "b68a0ca1-93ba-4807-8b54-f2d2654ca71c"
            }
          ]
        },
        "partitions": {}
      }
    ]
  }
}

HTTP REQUEST: DELETE

Delete a specific Aggregate.

DELETE/api/1.0/org/{orgId}/project/{projectId}/cube/{cubeId}/aggregates/{aggregateId}

URI PARAMETERS

Name	Type	Description
orgId	string	The Organization ID (UUID) for which you are querying.
projectId	string	The Project ID (UUID) for which you are querying.
cubeId	string	The Cube ID (UUID) for which you are querying.
aggregateId	string	The Aggregate ID (UUID) for which you are querying.

RESPONSES

Code	Description
200	Success.
401	This error will occur if calling user does not have access right for the API.
404	This error will occur if calling user does not have access right for the API.
500	A server error occurred. Check the logs for more details.
503	This error will occur if Design Center APIs are not enabled.

200 Response Body

{
  "status": {
    "i18n_message": "response.ok",
    "message": "OK"
  },
  "response": true
}

Export

This API exports System-Defined aggregate definitions that may then be imported using the Imported to another system that has the same CubeID. Note that User-Defined Aggregates (UDA's) are not included in the export.

HTTP REQUEST: GET

Read a specific Aggregate.

GET/api/1.0/org/{orgId}/project/{projectId}/cube/{cubeId}/aggregates/export

URI PARAMETERS

Name	Type	Description
orgId	string	The Organization ID (UUID) for which you are querying.
projectId	string	The Project ID (UUID) for which you are querying.
cubeId	string	The Cube ID (UUID) for which you are querying.

RESPONSES

Code	Description
200	Success.
400	Bad Request.
401	Unauthorized AtScale user.
403	User does not have permission to access the resource.
500	A server error occurred. Check the logs for more details.
503	This error will occur if Design Center APIs are not enabled.

RESPONSE BODY DESCRIPTIONS

Name	Type	Description
atScaleExportVersion	string	The AtScale system version from which the export originated.
exportSummary	ConnectionSummaries	Summarized information such as aggregate count, grouped by Connection ID.
exportTimestamp	string	Server-generated timestamp the export file was generated.
exportOrgId	string	Source Organization
exportProjectId	string	Project ID
exportCubeId	string	Cube ID. Must exist on the target system.
aggregates	AggregateDefinitions	Aggregate Definitions. For internal use only.

200 Response Body

{
  "status": {
    "i18n_message": "response.ok",
    "message": "OK"
  },
  "response": {
    "atScaleExportVersion": "2021.2.0",
    "exportSummary": {
      "connectionIds": {
        "count": 1,
        "values": [
          "con1"
        ]
      }
    },
    "exportTimestamp": "2021-05-04T22:22:32.275Z[UTC]",
    "exportOrgId": "default",
    "exportProjectId": "f7aec09a-7d92-4455-96fe-ccae1b504b28",
    "exportCubeId": "737732be-f50e-47c9-7826-920bfe0a9ef5",
    "aggregates": {
      "count": 1,
      "values": [
        {
          "id": "0fd822f6-0fd5-40bd-9b44-d43927e1a3f2",
          "user_defined_id": null,
          "user_defined_name": null,
          "triggering_query_id": "a0a54009-42f0-4f7c-8313-3cf804d3d4b9",
          "organization_id": "default",
          "environment_id": null,
          "project_id": "f7aec09a-7d92-4455-96fe-ccae1b504b28",
          "plan_json": "//logical plan of the aggregate (JSON)",
          "created_at": "2021-04-21 16:13:18",
          "latest_instance_id": "7c582a7e-23c1-460a-ab39-909370db9de1",
          "base_type": "system_defined",
          "sub_type": "demand_defined",
          "hinted_dataset_id": null,
          "active_instance_id": "7c582a7e-23c1-460a-ab39-909370db9de1",
          "connection_id": "con1",
          "promoted_copy_of": null,
          "promoted": "false",
          "incidental_data": {
            "type": "incidental-data-set",
            "data-set-id": "f79aea6b-f115-4c0a-4c3d-a604c7bc7b23"
          }
        }
      ]
    }
  }
}

Import

This API imports System-Defined aggregate definitions exported from the UI or the /aggregates/export API. The Request Body is expected to match that of the /aggregates/export endpoint Response Body. The identical cube, as defined by Cube ID, must exist in the system for this call to succeed. This API does not support importing from newer versions to older versions of AtScale. For best results, Aggregate Definitions should be migrated between AtScale servers with identical version numbers.

HTTP REQUEST: POST

Uploads a file containing the proprietary AtScale Aggregate Definition format for System-Defined aggregates. Use the 'multipart/form-data' Content-Type header. The payload follows the form-data format with the 'file' field populated with the binary-encoded file contents. For example: { file: File_Contents_In_Binary }.

POST/api/1.0/org/{orgId}/project/{projectId}/cube/{cubeId}/aggregates/import

URI PARAMETERS

Name	Type	Description
orgId	string	The Organization ID (UUID) for which you are querying.
projectId	string	The Project ID (UUID) for which you are querying.
cubeId	string	The Cube ID (UUID) for which you are querying.

QUERY PARAMETERS

Name	Type	Description
importPartitionKeys	boolean	Whether to import partition hints in aggregate logical plans (defaults to true if unspecified).
importDistributionKeys	boolean	Whether to import distribution hints in aggregate logical plans (defaults to true if unspecified).
importReplication	boolean	Whether to import replication hints in aggregate logical plans (defaults to true if unspecified).
connectionRemap	string	originalConnId:newConnId (no remap if unspecified). Pass multiple connection Remap variables to perform muliple remap operations.

RESPONSES

Code	Description
200	Success.
400	Bad Request.
401	Unauthorized AtScale user.
403	User does not have permission to access the resource.
500	A server error occurred. Check the logs for more details.
503	This error will occur if Design Center APIs are not enabled.

RESPONSE BODY DESCRIPTIONS

Name	Type	Description
atScaleExportVersion	string	The AtScale system version from which the export originated.
exportOrgId	string	Source Organization ID.
exportProjectId	string	Project ID
importOrgId	string	ID of the Organization to which the file was imported.
importProjectId	string	ID of the Project to which the file was imported.
cubeId	string	ID of the Cube containing the aggregate definitions.
numberOfDefinitionsImported	integer	Count of aggregate definitions that were imported.
numberOfDefinitionsIgnored	integer	Count of aggregate definitions that were not imported.
aggregates	AggregateImportDetails	Count: count of the response Values array, Values[ id: Source Aggregate UUID, newID: New Aggregate UUID, Imported: True\|False, reason: Human readable reason for Imported=False.]

200 Response Body

{
  "atScaleExportVersion": "2021.2.0",
  "exportOrgId": "default",
  "exportProjectId": "f7aec09a-7d92-4455-96fe-ccae1b504b28",
  "importOrgId": "myorg",
  "importProjectId": "3dcba5b0-b730-4ed8-a0c0-d3cbdaf83a55",
  "cubeId": "737732be-f50e-47c9-7826-920bfe0a9ef5",
  "numberOfDefinitionsImported": 1,
  "numberOfDefinitionsIgnored": 2,
  "aggregates": {
    "count": 3,
    "values": [
      {
        "id": "0fd822f6-0fd5-40bd-9b44-d43927e1a3f2",
        "newId": "4650a657-5d94-4ab5-a547-2e5e18b38a93",
        "imported": true
      },
      {
        "id": "15c37c52-84cf-4c20-8a91-2ef87ccffd38",
        "imported": false,
        "reason": "The connection ID \"con4\" is unknown in Organization \"myorg\"."
      },
      {
        "id": "15c37c52-84cf-4c20-8a91-2ef87ccffd38",
        "imported": "false",
        "reason": "Aggregate definition already exists: a49f6834-4552-4366-87c7-6237598f15e7"
      }
    ]
  }
}

Additional Reference

Design Center API REFERENCE

Aggregate

List & Update

HTTP REQUEST: GET

URI PARAMETERS

RESPONSES

RESPONSE BODY DESCRIPTIONS

HTTP REQUEST: POST

URI PARAMETERS

RESPONSES

RESPONSE BODY DESCRIPTIONS

Read, Update & Delete

HTTP REQUEST: GET

URI PARAMETERS

RESPONSES

RESPONSE BODY DESCRIPTIONS

HTTP REQUEST: PUT

URI PARAMETERS

RESPONSES

RESPONSE BODY DESCRIPTIONS

HTTP REQUEST: DELETE

URI PARAMETERS

RESPONSES

Export

HTTP REQUEST: GET

URI PARAMETERS

RESPONSES

RESPONSE BODY DESCRIPTIONS

Import

HTTP REQUEST: POST

URI PARAMETERS

QUERY PARAMETERS

RESPONSES

RESPONSE BODY DESCRIPTIONS