Module 4 - Using the GHO/XMart command line tools

This module provides a set of examples demonstrating how to use the GHO/XMart command line tool suite to perform various tasks against the GHO/XMart database.

Example 1 - Retrieving summary metadata
Example 2 - Retrieving a dimension codelist
Example 3 - Retrieving a set of facts using a slice
Example 4 - Retrieving data and metadata in an alternate output format
Example 5 - Retrieving versioned data
Example 6 - Loading a set of facts into the database
Example 7 - Validating a fact load file
Example 8 - Voiding a set of facts in the database
Example 9 - Deleting facts from the database
Example 10 - Loading new dimension members
Example 11 - Creating a new dimension
Example 12 - Creating a new attribute
Example 18 - Creating a new dataset
Example 13 - Editing dimension member attributes
Example 14 - Editing fact attributes
Example 15 - Publishing or unpublishing a set of facts
Example 16 - Deleting a dimension member
Example 17 - Deleting a dimension

Example 1 - Retrieving summary metadata

Data and metadata retrieval is achieved using the xmart-get command. To get the summary metadata, that describes the list of available Datasets, Dimensions, and Attributes which which you can formulate queries, use the -summary option as follows:

xmart-get -summary

This will produce an output in a human readable format similar to:

METADATA SUMMARY

DATASETS (16)

     COUNTRY_YEARLY_CORE_UNITS (CYCU)
     COUNTRY_YEARLY_BASIC_DATA (CYBD)
     COUNTRY_YEARLY_LIFE_MEASURES (CYLM)

ATTRIBUTES (26)

     DS_CODE (DS)
     FIPS_CODE (FIPS)
     IOC_CODE (IOC)
     ISO2_CODE (ISO2)

DIMENSIONS (88)

     Indicator (GHO)
     Indicator Categories (GHOCAT)
     Data Source (DATASOURCE)
     GBDCHILDCAUSES (GBDCHILDCAUSES)

text in parentheses at the end of each line is the XMart database code for the item in question. The number in parentheses after the DATASETS, ATTRIBUTES, and DIMENSIONS headers represents the code count for each item. See Example 4 for how to retrieve data in an alternate output format.

Example 2 - Retrieving a dimension codelist

Once we have the list of available dimension codes, we can retrieve the list of dimension members associated with a specific dimension. Such a query is made using the -dimension parameter. For example, to retrieve the list of countries, using the XMart code COUNTRY use the following:

xmart-get -dimension COUNTRY

This will give a result similar to:

DIMENSION Country (COUNTRY)

     Afghanistan (AFG)
     Albania (ALB)
     Algeria (DZA)
     Andorra (AND)
     Angola (AGO)
     Antigua and Barbuda (ATG)
     Argentina (ARG)
     Armenia (ARM)

The text in parentheses represents the XMart code for the particular dimension member, the rest if the default display string. See Example 4 for how to retrieve data in an alternate output format.

Example 3 - Retrieving a set of facts using a slice

Sets of facts are retrieved using a slice, specified using the -slice parameter. For example, retrieving regional life expectancy data from the Global Health Observatory for the year 2011 would require the following slice GHO:WHOSIS_000001;COUNTRY:-;REGION:AMR;REGION:SEAR;REGION:EMR;REGION:EUR;REGION:AFR;REGION:WPR;YEAR:2011. The command to retrieve this is:

xmart-get -slice "GHO:WHOSIS_000001;COUNTRY:-;REGION:AMR;REGION:SEAR;REGION:EMR;REGION:EUR;REGION:AFR;REGION:WPR;YEAR:2011"

Giving a result simlar to:

FACT
  ATTRIBUTES
    XMart ID:              728572
    Published:             true
    Dataset:               REGIONAL_YEARLY_CORE_SUMS (RYCS)
    Slice:                 RYCS/YEAR:2011;REGION:AFR;SEX:MLE;GHO:WHOSIS_000001
    Effective Date:        1900-01-01 00:00:00.0
    End Date:              2900-12-31 00:00:00.0
  DIMENSIONS
    Year:                  2011 (YEAR:2011)
    WHO region:            Africa (REGION:AFR)
    Sex:                   Male (SEX:MLE)
    Indicator:             Life expectancy at birth (years) (GHO:WHOSIS_000001)
  VALUE:
    Display String:        55

FACT
  ATTRIBUTES
    XMart ID:              728574
    Published:             true
    Dataset:               REGIONAL_YEARLY_CORE_SUMS (RYCS)
    Slice:                 RYCS/YEAR:2011;REGION:AMR;SEX:MLE;GHO:WHOSIS_000001
    Effective Date:        1900-01-01 00:00:00.0
    End Date:              2900-12-31 00:00:00.0
  DIMENSIONS
    Year:                  2011 (YEAR:2011)
    WHO region:            Americas (REGION:AMR)
    Sex:                   Male (SEX:MLE)
    Indicator:             Life expectancy at birth (years) (GHO:WHOSIS_000001)
  VALUE:
    Display String:        73

As in the previous examples, this result can be retrieved in other formats. see Example 4.

Example 4 - Retrieving data and metadata in an alternate output format

Alternate formats can be specified using the -format parameter. The following options are supported:

`default`	If no `format` parameter is specified, this default format is used. It provides a human readable summary of the data or metadata requested.
`excel`	Generates an Excel spreadsheet of the result of the query using SpreadsheetML.
`csv`	Generates a basic CSV file of the result of the query.
`xmart`	Generates a GHO/XMart CSV file that can then be reloaded through the GHO/XMart loading commands.
`xml`	Generates GHO/XMart XML.

Any format can be specified for any type of data retrieval. For example, we can restate the commands from examples 1 through 3 to use the xml, excel, and xmart formats respectively as follows:

xmart-get -summary -format xml

<?xml version="1.0" encoding="UTF-8"?><GHO>
<Metadata>
<Dataset Label="CYCU">
<Display>COUNTRY_YEARLY_CORE_UNITS</Display>
</Dataset>
<Dataset Label="CYBD">
<Display>COUNTRY_YEARLY_BASIC_DATA</Display>
</Dataset>
<Attribute Label="DS">
<Display>DS_CODE</Display>
</Attribute>
<Attribute Label="FIPS">
<Display>FIPS_CODE</Display>
</Attribute>
<Dimension Label="GBDCHILDCAUSES">
<Display>GBDCHILDCAUSES</Display>
</Dimension>
<Dimension Label="ICD10CAUSEGROUP">
<Display>ICD10CAUSEGROUP</Display>
</Dimension>
<Dimension Label="ICD10CHAPTER">
<Display>ICD10CHAPTER</Display>
</Dimension>

Note that the XML returned is the same XML that is returned via the athena web services.

xmart-get -dimension COUNTRY -format excel

<?xml version="1.0" encoding="UTF-8"?>
<Workbook xmlns:o="urn:schemas-microsoft-com:office"
          xmlns:x="urn:schemas-microsoft-com:excel"
          xmlns:ss="urn:schemas-microsoft-com:spreadsheet"
          xmlns:html="http://www.w3.org/TR/REC-html40"
          xmlns="urn:schemas-microsoft-com:office:spreadsheet">
   <DocumentProperties xmlns="urn:schemas-microsoft-com:office:office">
      <Author>Global Health Observatory</Author>
      <Created/>
      <Company>World Health Organization</Company>
      <Version>1.0</Version>
   </DocumentProperties>
   <Styles>
      <Style ss:ID="Default" ss:Name="Normal">
         <Alignment ss:Vertical="Bottom"/>
         <Borders/>
         <Font ss:Size="10"/>
         <Interior/>
             :

SpreadsheetML is an XML schema - for this type of output, you should redirect the result to a file in order to open it with Excel or some other compatible spreadsheet application.

xmart-get -slice "GHO:WHOSIS_000001;COUNTRY:-;REGION:AMR;REGION:SEAR;REGION:EMR;REGION:EUR;REGION:AFR;REGION:WPR;YEAR:2011" -format xmart

"Dataset","GHO","YEAR","REGION","SEX","Display","Numeric","Low","High","Comments"
"RYCS","WHOSIS_000001","2011","AFR","MLE","55","54.97",,,""
"RYCS","WHOSIS_000001","2011","AMR","MLE","73","73.47",,,""
"RYCS","WHOSIS_000001","2011","SEAR","MLE","65","65.04",,,""
"RYCS","WHOSIS_000001","2011","WPR","MLE","74","74.18",,,""
"RYCS","WHOSIS_000001","2011","EMR","FMLE","70","70.2",,,""
"RYCS","WHOSIS_000001","2011","EUR","FMLE","79","79.43",,,""
"RYCS","WHOSIS_000001","2011","AFR","BTSX","56","56.26",,,""
"RYCS","WHOSIS_000001","2011","EUR","BTSX","76","75.89",,,""
"RYCS","WHOSIS_000001","2011","SEAR","BTSX","67","66.74",,,""
"RYCS","WHOSIS_000001","2011","EMR","MLE","67","66.83",,,""
"RYCS","WHOSIS_000001","2011","EUR","MLE","72","72.3",,,""
"RYCS","WHOSIS_000001","2011","AFR","FMLE","58","57.55",,,""
"RYCS","WHOSIS_000001","2011","AMR","FMLE","79","79.12",,,""
"RYCS","WHOSIS_000001","2011","SEAR","FMLE","69","68.56",,,""
"RYCS","WHOSIS_000001","2011","WPR","FMLE","78","78.16",,,""
"RYCS","WHOSIS_000001","2011","AMR","BTSX","76","76.29",,,""
"RYCS","WHOSIS_000001","2011","EMR","BTSX","68","68.44",,,""
"RYCS","WHOSIS_000001","2011","WPR","BTSX","76","76.13",,,""

Example 5 - Retrieving versioned data

The tool set allows you to retrieve data as of a different date rather retrieving the present data. This allows you to see the result of a data query as it would have appeared at some particular point in the past, or the future if you have loaded data that has an effective date set to a date in the future. The tool parameter for this purpose is -asof and takes a UTC timestamp in the following format:

YYYY-MM-DDTHH:MM:SSZ

Where YYYY is the year, MM is the month number (january is 01, December is 12), and DD is the day. You must specify the time as well, where HH is the hour in 24 hour format, MM is the minutes, and SS is the seconds. Note that you must separate the two comopnents with a T character, and terminate with a Z to denote UTC time. For examples, April 1, 2012 at 6:30 pm Geneva time would be rendered as

2012-04-01T15:30:00Z

If we wish to retreive the data from Example 3 as it would have appeared on April 1 2013, at 6:30pm, we issue the command:

xmart-get -slice "GHO:WHOSIS_000001;COUNTRY:-;REGION:AMR;REGION:SEAR;REGION:EMR;REGION:EUR;REGION:AFR;REGION:WPR;YEAR:2011" -format xmart -asof 2012-12-01T12:00:00Z

which give us the result:

"Dataset","GHO","YEAR","REGION","SEX","Display","Numeric","Low","High","Comments"
"RYCS","WHOSIS_000001","2011","AFR","MLE","55","54.97",,,""
"RYCS","WHOSIS_000001","2011","AMR","MLE","73","73.47",,,""
"RYCS","WHOSIS_000001","2011","SEAR","MLE","65","65.04",,,""
"RYCS","WHOSIS_000001","2011","WPR","MLE","74","74.18",,,""
"RYCS","WHOSIS_000001","2011","EMR","FMLE","70","70.2",,,""
"RYCS","WHOSIS_000001","2011","EUR","FMLE","79","79.43",,,""
"RYCS","WHOSIS_000001","2011","AFR","BTSX","56","56.26",,,""
"RYCS","WHOSIS_000001","2011","EUR","BTSX","76","75.89",,,""
"RYCS","WHOSIS_000001","2011","SEAR","BTSX","67","66.74",,,""
"RYCS","WHOSIS_000001","2011","EMR","MLE","67","66.83",,,""
"RYCS","WHOSIS_000001","2011","EUR","MLE","72","72.3",,,""
"RYCS","WHOSIS_000001","2011","AFR","FMLE","58","57.55",,,""
"RYCS","WHOSIS_000001","2011","AMR","FMLE","79","79.12",,,""
"RYCS","WHOSIS_000001","2011","SEAR","FMLE","69","68.56",,,""
"RYCS","WHOSIS_000001","2011","WPR","FMLE","78","78.16",,,""
"RYCS","WHOSIS_000001","2011","AMR","BTSX","76","76.29",,,""
"RYCS","WHOSIS_000001","2011","EMR","BTSX","68","68.44",,,""
"RYCS","WHOSIS_000001","2011","WPR","BTSX","76","76.13",,,""

Example 6 - Loading a set of facts into the database

Facts are loaded into the system using a CSV data file format. The structure is the same as what is produced by the xmart output format rendered by the xmart-get command. The mandatory header row consists of a "Dataset" column, followed by one or more dimension code colums, a display string "Display" column, followed by "Numeric","Low","High", and "Comments" columns. If you wish to add attributes to the fact, include additional columns after "Comments" containing the desired attribute code. Each fact is fully rendered on one row. If a cell does not have a value for a particular dimension, that dimension will not be set for that specific fact, allowing you to mix-and-match facts from several different indicators and having different logical structures within the same file. When loading new data for an existing data set, a simply way of getting a starting structure is simply to query the indicator in xmart format and extract the header row. For example, to produce an update to the life expectancy at birth data, WHOSIS_000001 you would make the command:

xmart-get -slice "GHO:WHOSIS_000001" -format xmart

The extracted header row is

"Dataset","GHO","YEAR","REGION","WORLDBANKINCOMEGROUP","COUNTRY","SEX","PUBLISHSTATE","Display","Numeric","Low","High","Comments"

For this example, we will add a small set of regional data for the indicator "Acquired Post-Mortem Ambulatory Syndrome (PMAS), reported cases", ZOMBIE_0001. We will also include an attribute, SOURCE, that indicates the source of the data Here is the data set:

"Dataset","GHO","YEAR","REGION","WORLDBANKINCOMEGROUP","COUNTRY","SEX","PUBLISHSTATE","Display","Numeric","Low","High","Comments","SOURCE"
"RYCS","ZOMBIE_0001","2012","AMR",,,"BTSX","DRAFT","128000",,,,"","WHO"
"RYCS","ZOMBIE_0001","2012","SEAR",,,"BTSX","DRAFT","200",,,,"","WHO"
"RYCS","ZOMBIE_0001","2012","EMR",,,"BTSX","DRAFT","300",,,,"","WHO"
"RYCS","ZOMBIE_0001","2012","WPR",,,"BTSX","DRAFT","150",,,,"","WHO"
"RYCS","ZOMBIE_0001","2012","EUR",,,"BTSX","DRAFT","64000",,,,"","WHO"
"RYCS","ZOMBIE_0001","2012","AFR",,,"BTSX","DRAFT","200",,,,"","WHO"

We store this data in the file data1.csv and load it with the following command:

xmart-load-facts -input data1.csv -verbose

You should always use the verbose option for this operation in order to produce diagnostic outputs that indicate the current state of the load process. Note that the loader will abort on error. It will fully validate facts before altering the database.
The default behaviour is to void synonym facts - this means that if there is a fact in the database that matches the dimension structure of a fact being loaded, the database fact will be marked as void. This has the appearance of it being deleted but it can be retrieved by providing an asof date to xmart-get that is prior to the new data load.
The handling of synonyms is controlled by the -synonyms option - it can be set to the following values:

`void`	This is the default - if a synonym is encountered it will be voided in the database. This is the slowest option but also the safest. When in doubt, do this.
`ignore`	Synonyms will be ignored. This means that it is possible for the database to contain duplicate facts. Note that duplicate facts can have conflicting values. Use this option when you are not worried about the presence of duplicates. Either because you dont mind or because you know that you are loading data that does not have current duplicates in the system.
`abort`	The tool will abort (and not load anything) if it encounters a synonym

Note also that by default, the xmart-load-facts command loads new data with the IsPublished XMart flag set to false. This indicates to an XMart system that the fact is not meant to be publicly viewable. You can overide this with the -ispublished parameter. This version of our load command will make the data immediately public:

xmart-load-facts -input data1.csv -verbose -ispublished

By default the xmart-load-facts command expects the input file to be encoded in UTF-8. If it is not, you must specify the file's character encoding using the parameter -charset. For example, if you produced a CSV file using Microsoft Excel, the character encoding is likely to be CP1252 You would load this file using a command such as :

xmart-load-facts -input file.csv -verbose -charset cp1252

Example 7 - Validating a fact load file

It is possible to validate a load file for syntax correctness and for existing metadata codes without loading data into the database by using the parameter -count all. This will give you a summary count of metadata components, by code, as well as list the unrecognized codes. Unrecognized codes must be separately loaded into the system using the appropriate tools (see the examples below).
If we wish to simply validate the file data1.csv from Example 6 we would use the command:

xmart-load-facts -input data1.csv -verbose -count all

which gives us the result:

WARNING: Statistics mode, no data will be loaded into XMart
ROW 2: Processing fact:
ROW 2:      Constructing new Fact object
ROW 2:      Setting Fact dimension codes
ROW 3: Processing fact:
ROW 3:      Constructing new Fact object
ROW 3:      Setting Fact dimension codes
ROW 4: Processing fact:
ROW 4:      Constructing new Fact object
ROW 4:      Setting Fact dimension codes
ROW 5: Processing fact:
ROW 5:      Constructing new Fact object
ROW 5:      Setting Fact dimension codes
ROW 6: Processing fact:
ROW 6:      Constructing new Fact object
ROW 6:      Setting Fact dimension codes
ROW 7: Processing fact:
ROW 7:      Constructing new Fact object
ROW 7:      Setting Fact dimension codes

Statistics

Total number of facts: 6

     Indicator (GHO) instance counts
          6  Acquired Post-Mortem Ambulatory Syndrome (PMAS), reported cases (GHO:ZOMBIE_0001)
          TOTAL: 6 instances (1 distinct)

     GHO Publish state (PUBLISHSTATE) instance counts
          6  Draft (PUBLISHSTATE:DRAFT)
          TOTAL: 6 instances (1 distinct)

     WHO region (REGION) instance counts
          1  Africa (REGION:AFR)
          1  Americas (REGION:AMR)
          1  Eastern Mediterranean (REGION:EMR)
          1  Europe (REGION:EUR)
          1  South-East Asia (REGION:SEAR)
          1  Western Pacific (REGION:WPR)
          TOTAL: 6 instances (6 distinct)

     Sex (SEX) instance counts
          6  Both sexes (SEX:BTSX)
          TOTAL: 6 instances (1 distinct)

     Year (YEAR) instance counts
          6  2012 (YEAR:2012)
          TOTAL: 6 instances (1 distinct)

Example 8 - Voiding a set of facts in the database

Voiding is the prefered method of removing data - it removes it from general access but keeps a trace in the database. This is useful both to maintain historical archives for retro-actively changing data sets, but also as an error recovery mechanism. Data to be voided is identified by a slice specification, like in xmart-get To void the ZOMBIE_0001 data that we have just loaded, issue the following command:

xmart-void -slice "GHO:ZOMBIE_0001"

You can verify that the data is no longer available by using an xmart-get command on the same slice, as follows:

xmart-get -slice "GHO:ZOMBIE_0001"

You can also recover the data by using an xmart-get command with an approrpriate asof date, as described in Example 5.

Example 9 - Deleting facts from the database

Facts can be delete from the database using the xmart-delete option. This command is to be used only in special circumstances where voiding facts would be inappropriate. It is usually only acceptable when delete incorrectly loaded data that has not been published. Note that the xmart-delete command works on facts that are not voided. In oder to delete the data we have loaded in Example 7 we would issue the following command:

xmart-delete -slice "GHO:ZOMBIE_0001" -verbose

Example 10 - Loading new dimension members

New dimension members are listed in a CSV data file with a fixed structure with the following header row:

"DimensionCode","DimensionMemberCode","DisplayString","DisplaySequence","URL"

After the "URL" column, you may also list out attribute columns if nescessary A simple way of getting the appropriate header with commonly used attributes of dimension members is to use the xmart-get command to query for the dimension member list of the dimension you wish to edit or expand. For example, if we wish to add a new indicator (dimension GHO in the Global Health Observatory) we would issue the command:

xmart-get -dimension GHO -format xmart > file.csv

The first line of file.csv contains our header:

"DimensionCode","DimensionMemberCode","DisplayString","DisplaySequence","URL"

To add a new dimension member, simply create a new file with the appropriate header row and fill in one additional row per new member, following CSV conventions. For example, if we wish to add a new indicator for "Acquired Post-Morem Ambulatory Syndrome (PMAS), reported cases, we could create a file containing:

"DimensionCode","DimensionMemberCode","DisplayString","DisplaySequence","URL"
"GHO","TEST_0001","Acquired Post-Mortem Ambulatory Syndrome (PMAS), reported cases","2","http://en.wikipedia.org/wiki/Zombie"

Assuming the file is called file1.csv, we would load it into the system using the command:

xmart-load-dimension-members -input file1.csv -verbose

Note that if the Dimension and Dimension Member code pair already exist, the tool will update the representation of that code in the database. This allows you to correct or clarify codes as nescessary.

By default the xmart-load-dimension-members command expects the input file to be encoded in UTF-8. If it is not, you must specify the file's character encoding using the parameter -charset. For example, if you produced a CSV file using Microsoft Excel, the character encoding is likely to be CP1252 You would load this file using a command such as :

xmart-load-dimension-members -input file.csv -verbose -charset cp1252

Example 11 - Creating a new dimension

Example 12 - Creating a new attribute

To create new attributes, make a CSV file with the following structure:

"AttributeCode","EntityType","EntityCode","DisplayString"

For our example, we'll create a COMMENT attribute so that we can add footnotes to DATASOURCE Dimension Members. We therefore create the CSV file comment.csv, containing:

"AttributeCode","EntityType","EntityCode","DisplayString"
"COMMENT","CORE_DIMENSION","DATASOURCE","Comment"

and we load this into the system with the command:

xmart-load-attributes -input comment.csv -verbose

We can now load or update dimension members with this new attribute - see Example 13

By default the xmart-load-attributes command expects the input file to be encoded in UTF-8. If it is not, you must specify the file's character encoding using the parameter -charset. For example, if you produced a CSV file using Microsoft Excel, the character encoding is likely to be CP1252 You would load this file using a command such as :

xmart-load-attributes -input file.csv -verbose -charset cp1252

Example 13 - Editing dimension member attributes

For this example, we are going to chage the DisplaySequence attribute of the country code for Canada to 5000.
In order to edit the components of an existing dimension member, you must first retrieve it. The most effective way of doing this is to get the current dimension to which the dimension, in the GHO/XMart upload format:

xmart-get -dimension "COUNTRY" -format xmart -profile ghoprod > myFile.csv

Now that we have the COUNTRY dimension in the file myFile.csv, we can edit the file to remove everything except the line for the country code that we are interested in modifying, CAN, and the file header. We edit the line to update the DisplaySequence value to 5000 and save it. The final file will look something like this:

"DimensionCode","DimensionMemberCode","DisplayString","DisplaySequence","URL" "COUNTRY","CAN","Canada","5000",""

Note that this is the minimum structure required to describe a dimension member. Your instance of the database may contain more attributes than this. You may either leave them in the file, or you can remove them along with the corresponding header labels. The xmart-load-dimension-members command will only change those attributes it finds, it will not change anything else not present in the file.
We now reload the new version of the dimension member stored in the file myFile.csv with the following command:

xmart-load-dimension-members -input myFile.csv -profile ghoprod

You can validate that the operation was successfull by re-running the first command in this example and verifying that the row containing the freshly edited code now contains the updated attributes.

Example 14 - Editing fact attributes

Example 15 - Publishing or unpublishing a set of facts

Sets of facts can be published or unpublished, as per the XMart IsPublished field using the commands xmart-publish and xmart-unpublish. Both commands take a -slice parameter to select which facts to (un)publish. For example, if we wish to publish the data loaded in Example 6 we would use the command:

xmart-publish -slice "GHO:ZOMBIE_0001"

To unpublish this data, use the command:

xmart-unpublish -slice "GHO:ZOMBIE_0001"

You can verify that the operation is successfull by retrieving the same slice using the xmart-get command with the default output format. Each fact will have an entry indicating it's publishing status:

xmart-get -slice "GHO:ZOMBIE_0001"

Here is a sample fact returned by this command:

FACT
  ATTRIBUTES
    XMart ID:              1392988
    Published:             false 
    Dataset:               REGIONAL_YEARLY_CORE_SUMS (RYCS)
    Slice:                 RYCS/YEAR:2012;REGION:AFR;SEX:BTSX;PUBLISHSTATE:DRAFT;GHO:ZOMBIE_0001
    Effective Date:        2013-11-07 15:33:22.04
    End Date:              2900-12-31 00:00:00.0
  DIMENSIONS
    Year:                  2012 (YEAR:2012)
    WHO region:            Africa (REGION:AFR)
    Sex:                   Both sexes (SEX:BTSX)
    GHO Publish state:     Draft (PUBLISHSTATE:DRAFT)
    Indicator:             Acquired Post-Mortem Ambulatory Syndrome (PMAS), reported cases (GHO:ZOMBIE_0001)
  VALUE:
    Display String:        200

Example 16 - Deleting a dimension member

A dimension member can only be deleted if it has never been used by any fact, including voided facts. This operation is intended solely to clean up the data base in case of an erroneous metadata load. Use the command xmart-delete with the command line option -dimensionmember followed by one fully qualified dimension member code, for example COUNTRY:CAN. For example, if we have inadevertantly loaded an incorrect country code, say COUNTRY:AAFG for Afghanistan, the following command will delete it:

        xmart-delete -dimensionmember COUNTRY:AAFG

Note that the command will fail if the code is currently in use, or if the code does not exist. When a code is deleted, any associated attributes are also deleted. You may only delete one code at a time.

Example 17 - Deleting a dimension

A dimension can only be deleted if if has never been used by any fact, including voided facts. The purpose of this function is the same as for deleting a dimension member as described in Example 16. If you wish to delete an unused dimension, use the xmart-delete command with the command line option -dimension. For example if we wish to delete the dimension SCRATCH_DIMENSION we would use the command:

        xmart-delete -dimension SCRATCH_DIMENSION

Note that the command will fail if any dimension member of the specified dimension is used by any fact. When the dimension is deleted, all associated dimension members as well as associated attributes will be deleted as well. You may only delete one dimension at a time.

Example 18 - Creating a new dataset

A new dataset entry can be created with the command xmart-load-datasets. The command will read a CSV input file containing the codes and display labels for the datasets that you wish to create. If you specify an existing dataset code in the file, the display label for the dataset will be updated. The CSV file format consists of two columns, "DatasetCode" and "DisplayString". For example:

        "DatasetCode","DisplayString"
        "DS1","Dataset number 1"
        "DS2","Dataset number 2"

If we name the example file above datasets.csv, the command to create or update these entries would be (with verbose output):

        xmart-load-datasets -input datasets.csv  -verbose

By default the xmart-load-datasets command expects the input file to be encoded in UTF-8. If it is not, you must specify the file's character encoding using the parameter -charset. For example, if you produced a CSV file using Microsoft Excel, the character encoding is likely to be CP1252 You would load this file using a command such as :

xmart-load-datasets -input file.csv -verbose -charset cp1252