def get_predefined_folder_contents(connection: Connection,
folder_type: int,
project_id: Optional[str] = None,
offset: int = 0,
limit: int = 5000,
error_msg: Optional[str] = None):
"""Get contents of a pre-defined folder.
Args:
connection: MicroStrategy REST API connection object
folder_type (int): predefined folder type, from `EnumDSSXMLFolderNames`
project_id (string, optional): id of project
offset (int, optional): Starting point within the collection of returned
results. Used to control paging behavior. Default is 0.
limit (int, optional): Maximum number of items returned for a single
request. Used to control paging behavior. Use -1 for no limit.
Default is 5000.
Returns:
Complete HTTP response object.
"""
if project_id is None:
connection._validate_project_selected()
project_id = connection.project_id
return connection.get(
url=f"{connection.base_url}/api/folders/preDefined/{folder_type}",
headers={'X-MSTR-ProjectID': project_id},
params={
'offset': offset,
'limit': limit
})
def get_predefined_folder_contents_async(future_session: "FuturesSession",
connection: Connection,
folder_type: int,
project_id: Optional[str] = None,
offset: int = 0,
limit: int = 5000):
"""Get contents of a pre-defined folder.
Args:
future_session(object): `FuturesSession` object to call MicroStrategy
REST Server asynchronously
connection: MicroStrategy REST API connection object
folder_type (int): predefined folder type, from `EnumDSSXMLFolderNames`
project_id (string, optional): id of project
offset (int, optional): Starting point within the collection of returned
results. Used to control paging behavior. Default is 0.
limit (int, optional): Maximum number of items returned for a single
request. Used to control paging behavior. Use -1 for no limit.
Default is 5000.
Returns:
Complete Future object.
"""
if project_id is None:
connection._validate_project_selected()
project_id = connection.project_id
url = f"{connection.base_url}/api/folders/preDefined/{folder_type}"
headers = {'X-MSTR-ProjectID': project_id}
params = {'offset': offset, 'limit': limit}
return future_session.get(url=url, headers=headers, params=params)
def __init__(self, connection: Connection, id: str, name: Optional[str] = None,
instance_id: Optional[str] = None, parallel: bool = True,
progress_bar: bool = True):
"""Initialize an instance of a cube by its id.
Note:
Parameter `name` is not used when fetching. `id` is always used to
uniquely identify cube.
Args:
connection: MicroStrategy connection object returned by
`connection.Connection()`.
id (str): Identifier of a pre-existing cube containing
the required data.
name (str): Name of a cube.
instance_id (str): Identifier of an instance if cube instance has
been already initialized, None by default.
parallel (bool, optional): If True (default), utilize optimal number
of threads to increase the download speed. If False, this
feature will be disabled.
progress_bar(bool, optional): If True (default), show the download
progress bar.
"""
super().__init__(connection, id, name=name, instance_id=instance_id, parallel=parallel,
progress_bar=progress_bar, subtype=self._OBJECT_SUBTYPE)
connection._validate_project_selected()
self._get_definition()
def delete_inactive_caches(connection: Connection, days_diff: str = 30,
nodes: Union[str, List[str]] = None) -> List[CubeCache]:
"""Delete inactive caches which have `hit_count` equals 0 and their
`last_time_updated` was earlier than `days_diff` before from given `nodes`.
When `nodes` are `None` (default value) then all nodes are retrieved from
the cluster.
Args:
connection: MicroStrategy connection object returned by
`connection.Connection()`
days_diff (int, optional): number of days to determine whether to delete
cache when its `hit_count` equals 0. Default value is 30.
nodes (list of strings or string, optional): names of nodes from which
caches will be deleted. By default, it equals `None` and in that
case all nodes' names are loaded from the cluster.
Return:
list with cache objects which were deleted
"""
connection._validate_project_selected()
caches = list_cube_caches(connection, nodes)
# delete caches which fulfill requirements to be treated as inactive
deleted_caches = []
for cache in caches:
today = datetime.now(timezone.utc)
if (cache.hit_count == 0
and (today - _get_datetime(cache.last_update_time)).days > days_diff):
cache.delete(force=True)
deleted_caches.append(cache)
return deleted_caches
def list_all_cubes(connection: Connection, name_begins: Optional[str] = None,
to_dictionary: bool = False, limit: Optional[int] = None,
**filters) -> Union[List[Union["OlapCube", "SuperCube"]], List[dict]]:
"""Get list of Cube objects (OlapCube or SuperCube) or dicts with them.
Optionally filter cubes by specifying 'name_begins'.
Optionally use `to_dictionary` to choose output format.
Wildcards available for 'name_begins':
? - any character
* - 0 or more of any characters
e.g. name_begins = ?onny will return Sonny and Tonny
Args:
connection: MicroStrategy connection object returned by
`connection.Connection()`
name_begins (string, optional): characters that the cube name must begin
with
to_dictionary (bool, optional): If True returns dict, by default (False)
returns SuperCube/OlapCube objects
limit (integer, optional): limit the number of elements returned. If
None all object are returned.
**filters: Available filter parameters: ['id', 'name', 'type',
'subtype', 'date_created', 'date_modified', 'version', 'owner',
'ext_type', 'view_media', 'certified_info']
Returns:
list with OlapCubes and SuperCubes or list of dictionaries
"""
connection._validate_project_selected()
objects_ = full_search(connection, project=connection.project_id, name=name_begins,
object_types=[ObjectSubTypes.OLAP_CUBE, ObjectSubTypes.SUPER_CUBE],
pattern=SearchPattern.BEGIN_WITH, limit=limit, **filters)
if to_dictionary:
return objects_
else:
all_cubes = []
for object_ in objects_:
cube_subtype = object_['subtype']
if cube_subtype == int(ObjectSubTypes.OLAP_CUBE):
from .olap_cube import OlapCube
all_cubes.append(OlapCube.from_dict(object_, connection))
elif cube_subtype == int(ObjectSubTypes.SUPER_CUBE):
from .super_cube import SuperCube
all_cubes.append(SuperCube.from_dict(object_, connection))
return all_cubes
def get_my_personal_objects_contents(connection: Connection,
project_id: Optional[str] = None):
"""Get contents of My Personal Objects folder.
Args:
connection: MicroStrategy REST API connection object
project_id (string, optional): id of project
Returns:
Complete HTTP response object.
"""
if project_id is None:
connection._validate_project_selected()
project_id = connection.project_id
return connection.get(
url=f"{connection.base_url}/api/folders/myPersonalObjects",
headers={'X-MSTR-ProjectID': project_id})
def __init__(self, connection: Connection, id: str, instance_id: Optional[str] = None,
parallel: bool = True, progress_bar: bool = True):
"""Initialize an instance of a report.
Args:
connection: MicroStrategy connection object returned by
`connection.Connection()`.
id (str): Identifier of a pre-existing report containing
the required data.
instance_id (str): Identifier of an instance if report instance has
been already initialized, NULL by default.
parallel (bool, optional): If True (default), utilize optimal number
of threads to increase the download speed. If False, this
feature will be disabled.
progress_bar(bool, optional): If True (default), show the download
progress bar.
"""
connection._validate_project_selected()
super().__init__(connection, id, instance_id=instance_id, parallel=parallel,
progress_bar=progress_bar)
def list_reports(connection: Connection, name_begins: Optional[str] = None,
to_dictionary: bool = False, limit: Optional[int] = None,
**filters) -> Union[List["Report"], List[dict]]:
"""Get list of Report objects or dicts with them.
Optionally filter reports by specifying 'name_begins'.
Optionally use `to_dictionary` to choose output format.
Wildcards available for 'name_begins':
? - any character
* - 0 or more of any characters
e.g. name_begins = ?onny will return Sonny and Tonny
Args:
connection: MicroStrategy connection object returned by
`connection.Connection()`
name_begins (string, optional): characters that the report name must
begin with
to_dictionary (bool, optional): If True returns dict, by default (False)
returns Report objects
limit (integer, optional): limit the number of elements returned. If
None all object are returned.
**filters: Available filter parameters: ['id', 'name', 'type',
'subtype', 'date_created', 'date_modified', 'version', 'owner',
'ext_type', 'view_media', 'certified_info']
Returns:
list with Report objects or list of dictionaries
"""
connection._validate_project_selected()
objects_ = full_search(connection, object_types=ObjectTypes.REPORT_DEFINITION,
project=connection.project_id, name=name_begins,
pattern=SearchPattern.BEGIN_WITH, limit=limit, **filters)
if to_dictionary:
return objects_
else:
return [Report.from_dict(obj_, connection) for obj_ in objects_]
def load_cube(
connection: Connection, cube_id: Optional[str] = None, cube_name: Optional[str] = None,
folder_id: Optional[str] = None, instance_id: Optional[str] = None
) -> Union["OlapCube", "SuperCube", List[Union["OlapCube", "SuperCube"]]]:
"""Load single cube specified by either 'cube_id' or both 'cube_name' and
'folder_id'.
It is also possible to load cube by providing only `cube_name`, but in that
case we may retrieve more than one cube as cube's name is unique only within
a folder.
`instance_id` is used only when a single cube is retrieved.
Args:
connection: MicroStrategy connection object returned by
`connection.Connection()`
cube_id(string, optional): ID of cube
cube_name(string, optional): name of cube
folder_id(string, optional): ID of folder in which the cube is stored
instance_id (str, optional): Identifier of an instance if cube instance
has been already initialized. Will be used if only one cube is
found. `None` by default.
Returns:
object of type OlapCube or SuperCube based on the subtype of a cube
returned from metadata.
Raises:
ValueError when neither `cube_id` nor `cube_name` are provided.
"""
connection._validate_project_selected()
if cube_id:
if cube_name:
msg = "Both `cube_id` and `cube_name` provided. Loading cube based on `cube_id`."
exception_handler(msg, Warning, False)
elif folder_id:
msg = ("Both `cube_id` and `folder_id` provided. "
"Loading cube based on `cube_id` from all folders.")
exception_handler(msg, Warning, False)
objects_ = full_search(connection, project=connection.project_id,
object_types=[ObjectSubTypes.OLAP_CUBE, ObjectSubTypes.SUPER_CUBE],
pattern=SearchPattern.EXACTLY, id=cube_id)
elif not cube_name:
msg = "Specify either `cube_id` or `cube_name`."
raise ValueError(msg)
else: # getting cube by `cube_name` and optionally `folder_id`
objects_ = full_search(connection, project=connection.project_id, name=cube_name,
object_types=[ObjectSubTypes.OLAP_CUBE, ObjectSubTypes.SUPER_CUBE],
pattern=SearchPattern.EXACTLY, root=folder_id)
ret_cubes = []
for object_ in objects_:
object_ = object_ if len(objects_) > 1 else {**object_, "instance_id": instance_id}
ret_cubes.append(choose_cube(connection, object_))
ret_cubes = [tmp for tmp in ret_cubes if tmp] # remove `None` values
if len(ret_cubes) == 0:
exception_handler("Cube was not found.", Warning, False)
return None
elif len(ret_cubes) == 1:
return ret_cubes[0]
else:
exception_handler(f"More than one cube with name {cube_name} was loaded.", Warning, False)
return ret_cubes
def __init__(self,
connection: Connection,
id: Optional[str] = None,
name: Optional[str] = None,
description: Optional[str] = None,
instance_id: Optional[str] = None,
progress_bar: bool = True,
parallel: bool = True):
"""Initialize super cube.
When creating new super cube, provide its `name` and an optional
`description`.
When updating a pre-existing super cube, provide its `id`. This
identifier will be then used to initialize super cube.
Args:
connection: MicroStrategy connection object returned by
`connection.Connection()`.
id (str, optional): Identifier of a pre-existing super cube.
Used when updating a pre-existing super cube.
name (str): Name of the super cube.
description (str, optional): Description of the super cube. Must be
less than or equal to 250 characters.
instance_id (str): Identifier of an instance if cube instance has
been already initialized, NULL by default.
progress_bar(bool, optional): If True (default), show the upload
progress bar.
parallel (bool, optional): If True (default), utilize optimal number
of threads to increase the download speed. If False, this
feature will be disabled.
"""
if name is not None:
self.__check_param_str(name,
msg="Super cube name should be a string.")
self.__check_param_len(
name,
msg=
f"Super cube name should be <= {self.__MAX_DESC_LEN} characters.",
max_length=self.__MAX_DESC_LEN)
if description is not None:
self.__check_param_str(
description, msg="Super cube description should be a string.")
self.__check_param_len(
description,
msg="Super cube description should be <= {} characters.".
format(self.__MAX_DESC_LEN),
max_length=self.__MAX_DESC_LEN)
connection._validate_project_selected()
if id is not None:
super().__init__(connection=connection,
id=id,
instance_id=instance_id,
parallel=parallel,
progress_bar=progress_bar)
else:
self._init_variables(connection=connection,
name=name,
description=description,
progress_bar=progress_bar,
parallel=parallel)