Comment Commands
Comment Summary
The comment-summary command provides a high-level overview of how many comments have been written and by whom.
View Comments
You can view the comments in the current tenant:
dshell/SAMPLE:>view-comments +-----------+-------------------------+-----------------------------------------------+ |Author |Keys |Comment | +-----------+-------------------------+-----------------------------------------------+ |Jason Jones|Day: 2 |Yeah | | |Month: December | | | |Row: 1 | | | |Year: 2016 | | |Jason Jones|Market: New York |Test comment | | |Measures: COGS | | | |Product: Root Beer | | | |Scenario: Variance | | | |Year: Jan | | |Jason Jones|Key: 1 |foo | | |Year: 2016 | | ...
The view-comments command also takes --author, --include-key-spec and --exclude-key-spec parameters to specify that the comments displayed should have the given author or key spec, using standard comment key-specification syntax.
Delete Comments
Comments can be deleted using delete-comments. Without any parameters, all comments are deleted. The delete-comments command also accepts the standard --author, --include-key-spec and --exclude-key-spec parameters.
Copy Comments
The comment copy functionality can be used to copy comments within the same tenant. This command allows for specifying comments based on key value pairs to include or exclude, to adjust the POV of the comments, the author, and more. Consider a Dodeca tenant that contains the following comments:
dshell/SAMPLE:>view-comments
+-----------+-------------------------+----------------------------------------------------------------------------------+ |Author |Keys |Comment | +-----------+-------------------------+----------------------------------------------------------------------------------+ |Jason Jones|Market: West Seattle |Lower sales due to planned road work during the month | | |Measure: Sales | | | |Scenario: Budget | | | |Time: Jan | | | |Year: FY2020 | | |Jason Jones|Market: Northgate |Closure of competing store in same neighborhood to provide significant sales boost| | |Measure: Sales | | | |Scenario: Budget | | | |Time: Feb | | | |Year: FY2020 | | |Jason Jones|Market: Downtown Flagship|Higher sales from customers avoiding West Seattle location | | |Measure: Sales | | | |Scenario: Budget | | | |Time: Jan | | | |Year: FY2020 | | +-----------+-------------------------+----------------------------------------------------------------------------------+
In this example, there are three comments for three different locations and a total of two different time periods (Jan and Feb). The comment copy command allows us to do several things with the comments. For example, we may wish to copy the comments and specify a new time period:
dshell/SAMPLE:>copy-comments --add-key-spec Time=Mar
+-----------+-------------------------+----------------------------------------------------------------------------------+ |Author |Keys |Comment | +-----------+-------------------------+----------------------------------------------------------------------------------+ |Jason Jones|Measure: Sales |Lower sales due to planned road work during the month | | |Time: Mar | | | |Year: FY2020 | | | |Market: West Seattle | | | |Scenario: Budget | | |Jason Jones|Measure: Sales |Closure of competing store in same neighborhood to provide significant sales boost| | |Time: Mar | | | |Year: FY2020 | | | |Market: Northgate | | | |Scenario: Budget | | |Jason Jones|Measure: Sales |Higher sales from customers avoiding West Seattle location | | |Time: Mar | | | |Year: FY2020 | | | |Market: Downtown Flagship| | | |Scenario: Budget | | +-----------+-------------------------+----------------------------------------------------------------------------------+
The --add-key-spec directive allows for specifying a series of key values that should be added or updated on each comment intersection. Similarly, we can copy the comments and remove a portion of the key value pairs:
dshell/SAMPLE:>copy-comments --remove-key-spec Scenario
+-----------+-------------------------+----------------------------------------------------------------------------------+ |Author |Keys |Comment | +-----------+-------------------------+----------------------------------------------------------------------------------+ |Jason Jones|Measure: Sales |Higher sales from customers avoiding West Seattle location | | |Time: Jan | | | |Year: FY2020 | | | |Market: Downtown Flagship| | |Jason Jones|Measure: Sales |Closure of competing store in same neighborhood to provide significant sales boost| | |Time: Feb | | | |Year: FY2020 | | | |Market: Northgate | | |Jason Jones|Measure: Sales |Lower sales due to planned road work during the month | | |Time: Jan | | | |Year: FY2020 | | | |Market: West Seattle | | +-----------+-------------------------+----------------------------------------------------------------------------------+
We can delete multiple keys at once by separating them with a comma:
dshell/SAMPLE:>copy-comments --remove-key-spec Scenario,Year
+-----------+-------------------------+----------------------------------------------------------------------------------+ |Author |Keys |Comment | +-----------+-------------------------+----------------------------------------------------------------------------------+ |Jason Jones|Measure: Sales |Closure of competing store in same neighborhood to provide significant sales boost| | |Time: Feb | | | |Market: Northgate | | |Jason Jones|Measure: Sales |Lower sales due to planned road work during the month | | |Time: Jan | | | |Market: West Seattle | | |Jason Jones|Measure: Sales |Higher sales from customers avoiding West Seattle location | | |Time: Jan | | | |Market: Downtown Flagship| | +-----------+-------------------------+----------------------------------------------------------------------------------+
We may wish to only operate on comments with a certain intersection. The --include-key-spec parameter can be used to specify a set of key value pairs to filter on.
In the following example, only comments with an existing key of Time=Feb will be operated on and will have their Year set to FY2021:
copy-comments --include-key-spec Time=Feb --add-key-spec Year=FY2021
+-----------+-----------------+----------------------------------------------------------------------------------+ |Author |Keys |Comment | +-----------+-----------------+----------------------------------------------------------------------------------+ |Jason Jones|Measure: Sales |Closure of competing store in same neighborhood to provide significant sales boost| | |Time: Feb | | | |Year: FY2021 | | | |Market: Northgate| | | |Scenario: Budget | | +-----------+-----------------+----------------------------------------------------------------------------------+
Multiple filters can be specified in a single --include-key-spec specification. For example, the following command specifies that comments with an intersection where Time equals Jan and Market equals West Seattle (notice the quotes since the key value contains spaces) are to be operated on:
copy-comments --include-key-spec "Time=Jan,Market=West Seattle" --add-key-spec Year=FY2021
The quotes surround the entire parameter value (i.e. everything after --include-key-spec and before --add-key-spec rather than the individual member names.
You can specify multiple include filters by separating them with a semi-colon. For example:
copy-comments --include-key-spec "Time=Jan,Market=West Seattle;Market=Northgate" --add-key-spec Year=FY2021
The preceding comment command specifies that there are multiple types of comment intersections to consider:
-
Any comments that have both
Time=JanandMarket=West Seattleor -
Any comments that have
Market=Northgate
You may need to filter out some comments that match certain criteria. For example, we could extend the previous example:
copy-comments --include-key-spec "Time=Jan,Market=West Seattle;Market=Northgate" --exclude-key-spec Time=Feb --add-key-spec Year=FY2021
It can be read as follows:
Copy comments where the comment POV is Time=Jan and Market=West Seattle or where Market=Northgate (without any regard for Time), but exclude anything with a POV where Time=Feb. Lastly, add or update the comment POV so that Year=FY2021.
On any given comment update command you may also use some additional parameters such as updating the comment author, or optionally setting the comment’s "updated" date to the current time/date:
copy-comments --include-key-spec "Time=Jan,Market=West Seattle;Market=Northgate" --exclude-key-spec Time=Feb --add-key-spec Year=FY2021 --new-author "Tim Tow" --updated
+-------+--------------------+-----------------------------------------------------+ |Author |Keys |Comment | +-------+--------------------+-----------------------------------------------------+ |Tim Tow|Measure: Sales |Lower sales due to planned road work during the month| | |Time: Jan | | | |Year: FY2021 | | | |Market: West Seattle| | | |Scenario: Budget | | +-------+--------------------+-----------------------------------------------------+
The common "comment key specification" format also allows for specifying the key/value to be matched in more advanced ways. Typically the key specification is in the form Key=Value but it can also be specified in other ways. For example, without a value specifies to filter where the comment simply has Market as a key in its intersection, but with ANY value.:
view-comments --include-key-spec "Market"
Lastly, the key can be omitted in order to filter on the value only without respect to the key:
view-comments --include-key-spec "=Budget"
View Comments
You can view, export, and import comments. Viewing is useful to get a sense of what comments exist and which intersections an export/import will target. You can export comments to an XML file to be imported to a different tenant, database, or both. You may also specify which intersections should be specifically included or excluded in the import.
To view all comments in the current tenant, you can simply use the view-comments command:
view-comments
With output such as the following:
+-----------+-------------------------+---------------------------------------------+ |Author |Keys |Comment | +-----------+-------------------------+---------------------------------------------+ |Jason Jones|Day: 2 |Comment 1 | | |Month: December | | | |Row: 1 | | | |Year: 2016 | | |Jason Jones|Market: New York |Test comment | | |Measures: COGS | | | |Product: Root Beer | | | |Scenario: Variance | | | |Year: Jan | | +-----------+-------------------------+---------------------------------------------+
The view-comments command (as well as the export and import commands) also allow for specifying
an include and exclude "key spec" or key specification.
This lets you filter the comments to include/exclude such that all the comments meet all of the specified criteria. By way of a simple example, you may wish to export all comments that contain as part of their intersection the key of "Market" with a value of "New York". That can be specified as follows:
view-comments --include-key-spec "Market=New York"
Note that the whole key spec is in quotes since one of the values contains a space in it.
You may instead decide that you want to view/export all comments that simply have a key named Market, but with any value. This can be specified as follows:
view-comments --include-key-spec "Market="
You may want to specify just comments where the value is "West" but for whatever reason it doesn’t matter what the key is:
view-comments --include-key-spec "=West"
You can also specify that comments should have multiple keys and values, such as those comments that have Market set to West but also where Measures is set to Sales:
view-comments --include-key-spec "Market=West,Measures=Sales"
Again, not that the exported comments must satisfy all of the specified key specs, not just some of them.
You may want to exclude certain combinations as well. This works similarly to the include key spec in that the excluded comments must match all of the specifications. For example:
view-comments --include-key-spec "Market" --exclude-key-spec "Market=New York,Year=Jan"
The preceding example would include comments that have Market as part of their key set (with any value), while also excluding those comments that have Market set to New York AND have Year set to Jan. Comments that have Market set to New York but that have Year set to something besides Jan will not be excluded.