| Title: | Interface for 'MicroStrategy' REST API |
|---|---|
| Description: | Interface for creating data sets and extracting data through the 'MicroStrategy' REST API. Access the demo API at <https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html>. |
| Authors: | Piotr Kowal [aut, cre] |
| Maintainer: | Piotr Kowal <[email protected]> |
| License: | Apache License 2.0 | file LICENSE |
| Version: | 11.3.5.101 |
| Built: | 2025-02-17 05:01:03 UTC |
| Source: | https://github.com/cran/mstrio |
Allows to establish, renew, check status and close the connection with MicroStrategy Intelligence Server.
base_urlURL of the MicroStrategy REST API server.
usernameYour username.
passwordYour password.
project_nameName of the connected MicroStrategy Project. One of project name or project id is necessary.
project_idID of the connected MicroStrategy Project. One of project name or project id is necessary.
login_modeSpecifies authentication mode to use. Standard = 1 (default) or LDAP = 16.
ssl_verifyIf True (default), verifies the server's SSL certificates with each request.
web_versionThe current web version
iserver_versionThe current I-Server version
auth_tokenThe authentication token returned by the I-Server
cookiesCookies
identity_tokenIdentity token for delegated session. Used for connection initialized by GUI.
verboseIf True (default), displays additional messages.
new()
Establishes new connection with MicroStrategy Intelligence Server.
Connection$new( base_url, username = NULL, password = NULL, project_name = NULL, project_id = NULL, login_mode = 1, ssl_verify = TRUE, proxies = NULL, identity_token = NULL, verbose = TRUE )
base_urlURL of the MicroStrategy REST API server.
usernameYour username.
passwordYour password.
project_nameName of the connected MicroStrategy Project. One of project name or project id is necessary.
project_idID of the connected MicroStrategy Project. One of project name or project id is necessary.
login_modeSpecifies authentication mode to use. Standard = 1 (default) or LDAP = 16.
ssl_verifyIf True (default), verifies the server's SSL certificates with each request.
proxiesIf NULL (default) proxy is not defined. To set proxy use formula: (<username>:<password>@)<ip_address>:<port> ()-optional
identity_tokenIdentity token for delegated session. Used for connection initialized by GUI.
verboseIf True, displays additional messages. FALSE by default.
A new "Connection" object.
connect()
Establishes new connection with MicroStrategy Intelligence Server, or renews active connection.
Connection$connect()
delegate()
Delegates identity token to get authentication token and connect to MicroStrategy Intelligence Server
Connection$delegate()
get_identity_token()
Gets identity token using existing authentication token
Connection$get_identity_token()
close()
Closes a connection with MicroStrategy REST API.
Connection$close()
renew()
Renews connection with MicroStrategy REST API.
Connection$renew()
status()
Displays status of the connection with MicroStrategy REST API.
Connection$status()
clone()
The objects of this class are cloneable with this method.
Connection$clone(deep = FALSE)
deepWhether to make a deep clone.
## Not run: # Create a connection object. connection = Connection$new(base_url, username, password, project_name) # Connect or renew connection. connection$connect() # Check connection status. connection$status() # Renew connection to reset timeout counter. connection$renew() # Close connection. connection$close() ## End(Not run)## Not run: # Create a connection object. connection = Connection$new(base_url, username, password, project_name) # Connect or renew connection. connection$connect() # Check connection status. connection$status() # Renew connection to reset timeout counter. connection$renew() # Close connection. connection$close() ## End(Not run)
Access, filter, publish, and extract data from MicroStrategy in-memory cubes
Create a Cube object to load basic information on a cube dataset. Specify subset of cube to be fetched through apply_filters() and clear_filters(). Fetch dataset through to_dataframe() method.
connectionMicroStrategy connection object
cube_idIdentifier of a report.
parallelIf TRUE, downloads cube data asynchronously. FALSE by default.
nameCube name.
owner_idID of Cube owner.
pathExact path of the cube location.
last_modifiedDate of latest Cube modification.
sizeCube size.
statusCube status.
attributesCube attributes.
metricsCube metrics
attr_elementsCube attribute elements.
selected_attributesAttributes selected for filtering.
selected_metricsMetrics selected for filtering.
selected_attr_elementsAttribute elements selected for filtering.
dataframeDataframe containing data fetched from the Cube.
dataframe_listList of dataframes split to match tables in Cube.
instance_idIdentifier of an instance if cube instance has been already initialized.
new()
Initialize an instance of a cube.
Cube$new(connection, cube_id, instance_id = NULL, parallel = FALSE)
connectionMicroStrategy connection object. See Connection class.
cube_idIdentifier of a pre-existing cube containing the required data.
instance_idIdentifier of an instance if cube instance has been already initialized, NULL by default.
parallel(bool, optional): If True, utilize optimal number of threads to increase the download speed. If False (default), this feature will be disabled.
to_dataframe()
Extract contents of a cube into a R Data Frame.
Cube$to_dataframe(limit = NULL, multi_df = FALSE, callback = function(x, y) {
})limit(int, optional): Used to control data extraction behaviour on cubes with a large number of rows. By default the limit is calculated automatically. If TRUE, overrides automatic limit.
multi_dfIf True (default), returns a list of dataframes resembling the table structure of the cube. If FALSE, returns one dataframe.
callbackused by the GUI to extract the progress information.
Dataframe with data fetched from the given Cube.
apply_filters()
Apply filters on the cube data so only the chosen attributes, metrics, and attribute elements are retrieved from the Intelligence Server.
Cube$apply_filters( attributes = NULL, metrics = NULL, attr_elements = NULL, operator = "In" )
attributes(list or None, optional): ID numbers of attributes to be included in the filter. If list is empty, no attributes will be selected and metric data will be aggregated.
metrics(list or None, optional): ID numbers of metrics to be included in the filter. If list is empty, no metrics will be selected.
attr_elements(list or None, optional): Attributes' elements to be included in the filter.
operator(character, optional): Supported view filter operators are either "In" or "NotIn". This defines whether data will include ("In") or exclude ("NotIn") the supplied attr_elements values.
clear_filters()
Clear previously set filters, allowing all attributes, metrics, and attribute elements to be retrieved.
Cube$clear_filters()
get_attr_elements()
Load all attribute elements of the Cube. Accessible via Cube$attr_elements Fetching attriubte elements will also allow for validating attriute elements by the filter object.
Cube$get_attr_elements(limit = 50000, verbose = TRUE)
verboseIf TRUE, displays list of attribute elements.
update()
Update single-table cube easily with the data frame stored in the Cube instance (cube$dataframe). Before the update, make sure that the data frame has been modified.
Cube$update(update_policy = "update")
update_policy(character) Update operation to perform. One of 'add' (inserts new, unique rows), 'update' (updates data in existing rows and columns), 'upsert' (updates existing data and inserts new rows), or 'replace' (replaces the existing data with new data).
save_as()
Creates a new single-table cube with the data frame stored in the Cube instance (cube$dataframe). Before the update, make sure that the data exists.
Cube$save_as(name, description = NULL, folder_id = NULL, table_name = NULL)
name(character): Name of the dataset. Must be less than or equal to 250 characters.
description(character, optional): Description of the dataset. Must be less than or equal to 250 characters.
folder_idID of the shared folder that the dataset should be created within. If 'None', defaults to the user's My Reports folder.
table_name(character, optional) Name of the table. If NULL, the first table name of the original cube will be used.
clone()
The objects of this class are cloneable with this method.
Cube$clone(deep = FALSE)
deepWhether to make a deep clone.
## Not run: # Create a connection object. connection = Connection$new(base_url, username, password, project_name) # Create a cube object. my_cube <- Cube$new(connection=conn, cube_id="...") # See attributes and metrics in the report. my_cube$attributes my_cube$metrics my_cube$attr_elements # Specify attributes and metrics (columns) to be fetched. my_cube$apply_filters(attributes = my_report$attributes[1:2], metrics = my_report$metrics[1:2]) # See the selection of attributes, metrics and attribute elements. my_cube$selected_attributes my_cube$selected_metrics my_cube$selected_attr_elements # Clear filtering to load a full dataset. my_cube$clear_filters() # Fetch data from the Intelligence Server. my_cube$to_dataframe() # See the dataframe. my_cube$dataframe ## End(Not run)## Not run: # Create a connection object. connection = Connection$new(base_url, username, password, project_name) # Create a cube object. my_cube <- Cube$new(connection=conn, cube_id="...") # See attributes and metrics in the report. my_cube$attributes my_cube$metrics my_cube$attr_elements # Specify attributes and metrics (columns) to be fetched. my_cube$apply_filters(attributes = my_report$attributes[1:2], metrics = my_report$metrics[1:2]) # See the selection of attributes, metrics and attribute elements. my_cube$selected_attributes my_cube$selected_metrics my_cube$selected_attr_elements # Clear filtering to load a full dataset. my_cube$clear_filters() # Fetch data from the Intelligence Server. my_cube$to_dataframe() # See the dataframe. my_cube$dataframe ## End(Not run)
When creating a new dataset, provide a dataset name and an optional description. When updating a pre-existing dataset, provide the dataset identifier. Tables are added to the dataset in an iterative manner using 'add_table()'.
connectionMicroStrategy connection object
nameName of the dataset
descriptionDescription of the dataset. Must be less than or equal to 250 characters
folder_idIf specified the dataset will be saved in this folder
dataset_idIdentifier of a pre-existing dataset. Used when updating a pre-existing dataset
owner_idOwner ID
pathCube path
modification_timeLast modification time, "yyyy-MM-dd HH:mm:ss" in UTC
sizeCube size
cube_stateCube status,for example, 0=unpublished, 1=publishing, 64=ready
verboseIf True (default), displays additional messages.
new()
Interface for creating, updating, and deleting MicroStrategy in-memory datasets.
Dataset$new( connection, name = NULL, description = NULL, dataset_id = NULL, verbose = TRUE )
connectionMicroStrategy connection object returned by 'Connection$New()'.
name(character): Name of the dataset.
description(character, optional): Description of the dataset. Must be less than or equal to 250 characters.
dataset_id(character, optional): Identifier of a pre-existing dataset. Used when updating a pre-existing dataset.
verboseSetting to control the amount of feedback from the I-Server.
When creating a new dataset, provide a dataset name and an optional description. When updating a pre-existing dataset, provide the dataset identifier. Tables are added to the dataset in an iterative manner using 'add_table()'.
A new 'Datasets' object
add_table()
Add a data.frame to a collection of tables which are later used to update the MicroStrategy dataset
Dataset$add_table( name, data_frame, update_policy, to_metric = NULL, to_attribute = NULL )
name(character): Logical name of the table that is visible to users of the dataset in MicroStrategy.
data_frame('data.frame'): R data.frame to add or update.
update_policy(character): Update operation to perform. One of 'add' (inserts new, unique rows), 'update' (updates data in existing rows and columns), 'upsert' (updates existing data and inserts new rows), or 'replace' (replaces the existing data with new data).
to_metric(optional, vector): By default, R numeric data types are treated as metrics in the MicroStrategy dataset while character and date types are treated as attributes. For example, a column of integer-like strings ("1", "2", "3") would, by default, be an attribute in the newly created dataset. If the intent is to format this data as a metric, provide the respective column name as a character vector in 'to_metric' parameter.
to_attribute(optional, vector): Logical opposite of 'to_metric'. Helpful for formatting an integer-based row identifier as a primary key in the dataset.
Add tables to the dataset in an iterative manner using 'add_table()'.
create()
Create a new dataset.
Dataset$create( folder_id = NULL, auto_upload = TRUE, auto_publish = TRUE, chunksize = 1e+05 )
folder_idID of the shared folder that the dataset should be created within. If 'None', defaults to the user's My Reports folder.
auto_upload(default TRUE) If True, automatically uploads the data to the I-Server. If False, simply creates the dataset definition but does not upload data to it.
auto_publish(default TRUE) If True, automatically publishes the data used to create the dataset definition. If False, simply creates the dataset but does not publish it. To publish the dataset, data has to be uploaded first.
chunksize(int, optional) Number of rows to transmit to the I-Server with each request when uploading.
update()
Updates an existing dataset with new data.
Dataset$update(chunksize = 1e+05, auto_publish = TRUE)
chunksize(int, optional): Number of rows to transmit to the I-Server with each request when uploading.
auto_publish(default TRUE) If True, automatically publishes the data. If False, data will be uploaded but the cube will not be published
publish()
Publish the uploaded data to the selected dataset. A dataset can be published just once.
Dataset$publish()
publish_status()
Check the status of data that was uploaded to a dataset.
Dataset$publish_status()
Response status code
delete()
Delete a dataset that was previously created using the REST API.
Dataset$delete()
Response object from the Intelligence Server acknowledging the deletion process.
certify()
Certify a dataset that was previously creted using the REST API
Dataset$certify()
Response object from the Intelligence Server acknowledging the certification process.
clone()
The objects of this class are cloneable with this method.
Dataset$clone(deep = FALSE)
deepWhether to make a deep clone.
## Not run: # Create data frames df1 <- data.frame("id" = c(1, 2, 3, 4, 5), "first_name" = c("Jason", "Molly", "Tina", "Jake", "Amy"), "last_name" = c("Miller", "Jacobson", "Turner", "Milner", "Cooze")) df2 <- data.frame("id" = c(1, 2, 3, 4, 5), "age" = c(42, 52, 36, 24, 73), "state" = c("VA", "NC", "WY", "CA", "CA"), "salary" = c(50000, 100000, 75000, 85000, 250000)) # Create a list of tables containing one or more tables and their names my_dataset <- Dataset$new(connection=conn, name="HR Analysis") my_dataset$add_table("Employees", df1, "add") my_dataset$add_table("Salaries", df2, "add") my_dataset$create() # By default Dataset$create() will upload the data to the Intelligence Server and publish the dataset. # If you just want to create the dataset but not upload the row-level data, use Dataset$create(auto_upload=FALSE) # followed by Dataset$update() Dataset$publish() # When the source data changes and users need the latest data for analysis and reporting in # MicroStrategy, mstrio allows you to update the previously created dataset. ds <- Dataset$new(connection=conn, dataset_id="...") ds$add_table(name = "Stores", data_frame = stores_df, update_policy = 'update') ds$add_table(name = "Sales", data_frame = stores_df, update_policy = 'upsert') ds$update(auto_publish=TRUE) # By default Dataset$update() will upload the data to the Intelligence Server and publish the dataset. # If you just want to update the dataset but not publish the row-level data, use Dataset$update(auto_publish=FALSE) # By default, the raw data is transmitted to the server in increments of 100,000 rows. On very # large datasets (>1 GB), it is beneficial to increase the number of rows transmitted to the # Intelligence Server with each request. Do this with the chunksize parameter: ds$update(chunksize = 500000) # If you want to cerfify an existing dataset, use ds$certify() ## End(Not run)## Not run: # Create data frames df1 <- data.frame("id" = c(1, 2, 3, 4, 5), "first_name" = c("Jason", "Molly", "Tina", "Jake", "Amy"), "last_name" = c("Miller", "Jacobson", "Turner", "Milner", "Cooze")) df2 <- data.frame("id" = c(1, 2, 3, 4, 5), "age" = c(42, 52, 36, 24, 73), "state" = c("VA", "NC", "WY", "CA", "CA"), "salary" = c(50000, 100000, 75000, 85000, 250000)) # Create a list of tables containing one or more tables and their names my_dataset <- Dataset$new(connection=conn, name="HR Analysis") my_dataset$add_table("Employees", df1, "add") my_dataset$add_table("Salaries", df2, "add") my_dataset$create() # By default Dataset$create() will upload the data to the Intelligence Server and publish the dataset. # If you just want to create the dataset but not upload the row-level data, use Dataset$create(auto_upload=FALSE) # followed by Dataset$update() Dataset$publish() # When the source data changes and users need the latest data for analysis and reporting in # MicroStrategy, mstrio allows you to update the previously created dataset. ds <- Dataset$new(connection=conn, dataset_id="...") ds$add_table(name = "Stores", data_frame = stores_df, update_policy = 'update') ds$add_table(name = "Sales", data_frame = stores_df, update_policy = 'upsert') ds$update(auto_publish=TRUE) # By default Dataset$update() will upload the data to the Intelligence Server and publish the dataset. # If you just want to update the dataset but not publish the row-level data, use Dataset$update(auto_publish=FALSE) # By default, the raw data is transmitted to the server in increments of 100,000 rows. On very # large datasets (>1 GB), it is beneficial to increase the number of rows transmitted to the # Intelligence Server with each request. Do this with the chunksize parameter: ds$update(chunksize = 500000) # If you want to cerfify an existing dataset, use ds$certify() ## End(Not run)
Access, filter, publish, and extract data from in-memory reports. Create a Report object to load basic information on a report dataset. Specify subset of report to be fetched through Report$apply_filters() and Report$clear_filters() . Fetch dataset through Report$to_dataframe() method.
connectionMicroStrategy connection object
report_idIdentifier of a report.
parallelIf TRUE, downloads report data asynchronously. FALSE by default.
nameReport name.
attributesReport attributes.
metricsReport metrics
attr_elementsReport attribute elements.
selected_attributesAttributes selected for filtering.
selected_metricsMetrics selected for filtering.
selected_attr_elementsAttribute elements selected for filtering.
dataframeDataframe containing data fetched from the Report.
cross_tabboolean for filtering cross tabbed reports logic
cross_tab_filtersview filters for cross tab reports
instance_idIdentifier of an instance if report instance has been already initialized.
new()
Initialize an instance of a report.
Report$new(connection, report_id, instance_id = NULL, parallel = FALSE)
connectionMicroStrategy connection object. See Connection class.
report_idIdentifier of a pre-existing report containing the required data.
instance_idIdentifier of an instance if report instance has been already initialized, NULL by default.
parallel(bool, optional): If True, utilize optimal number of threads to increase the download speed. If False (default), this feature will be disabled.
to_dataframe()
Extract contents of a Report into a R Data Frame.
Report$to_dataframe(limit = NULL, callback = function(x, y) {
})limit(int, optional): Used to control data extraction behaviour on report with a large number of rows. By default the limit is calculated automatically. If TRUE, overrides automatic limit.
callbackused by the GUI to extract the progress information
Dataframe with data fetched from the given Report.
apply_filters()
Apply filters on the report data so only the chosen attributes, metrics, and attribute elements are retrieved from the Intelligence Server.
Report$apply_filters( attributes = NULL, metrics = NULL, attr_elements = NULL, operator = "In" )
attributes(list or None, optional): ID numbers of attributes to be included in the filter. If list is empty, no attributes will be selected and metric data will be aggregated.
metrics(list or None, optional): ID numbers of metrics to be included in the filter. If list is empty, no metrics will be selected.
attr_elements(list or None, optional): Attributes' elements to be included in the filter.
operator(character, optional): Supported view filter operators are either "In" or "NotIn". This defines whether data will include ("In") or exclude ("NotIn") the supplied attr_elements values.
clear_filters()
Clear previously set filters, allowing all attributes, metrics, and attribute elements to be retrieved.
Report$clear_filters()
get_attr_elements()
Load all attribute elements of the Report. Accessible via Report$attr_elements. Fetching attriubte elements will also allow for validating attriute elements by the filter object.
Report$get_attr_elements(limit = 50000, verbose = TRUE)
limitHow many rows of data to fetch per request.
verboseIf TRUE, displays list of attribute elements.
clone()
The objects of this class are cloneable with this method.
Report$clone(deep = FALSE)
deepWhether to make a deep clone.
## Not run: # Create a connection object. connection = Connection$new(base_url, username, password, project_name) # Create a report object. my_report <- Report$new(connection, report_id) # See attributes and metrics in the report. my_report$attributes my_report$metrics my_report$attr_elements # Specify attributes and metrics (columns) to be fetched. my_report$apply_filters(attributes = my_report$attributes[1:2], metrics = my_report$metrics[1:2]) # See the selection of attributes, metrics and attribute elements. my_report$selected_attributes my_report$selected_metrics my_report$selected_attr_elements # Clear filtering to load a full dataset. my_report$clear_filters() # Fetch data from the Intelligence Server. my_report$to_dataframe() # See the dataframe. my_report$dataframe ## End(Not run)## Not run: # Create a connection object. connection = Connection$new(base_url, username, password, project_name) # Create a report object. my_report <- Report$new(connection, report_id) # See attributes and metrics in the report. my_report$attributes my_report$metrics my_report$attr_elements # Specify attributes and metrics (columns) to be fetched. my_report$apply_filters(attributes = my_report$attributes[1:2], metrics = my_report$metrics[1:2]) # See the selection of attributes, metrics and attribute elements. my_report$selected_attributes my_report$selected_metrics my_report$selected_attr_elements # Clear filtering to load a full dataset. my_report$clear_filters() # Fetch data from the Intelligence Server. my_report$to_dataframe() # See the dataframe. my_report$dataframe ## End(Not run)