Defining Term Lists

Overview of Term Lists

Term lists provide a way to customize a Business Intelligence model without programming. A term list is a simple (but extendable) list of key and value pairs. The key values must be unique within the list. You can extend the term list by adding custom fields. You can use term lists in the following ways:

• You can use a term list to define additional data to use in the cube. In this case, the term list is used when the cube is built. For example, you can use a term list to define a set of values to use as properties of a level. Or you could use a term list to provide an alternative set of names for the level members.

• You can use a term list at run time to access additional values. (In this case, you use the LOOKUP and %LOOKUP functions.)

• You can use a term list at run time to build a set of members, typically for use in a filter. In this case, you must specify a term list pattern. You use the term list with the %TERMLIST function.

Accessing the Term List Manager

To define and modify term lists, you use the Term List Manager. To access this tool:

1. Select the InterSystems Launcher and then select Management Portal.

   Depending on your security, you may be prompted to log in with an InterSystems IRIS username and password.

2. Switch to the appropriate namespace as follows:

   1. Select the name of the current namespace to open the list of available namespaces.

   2. From the list, select the appropriate namespace.

3. Select Analytics > Tools > Term List Manager.

The Term List Manager page initially looks like this:

On this page you can do the following:

• Create new term lists. Select New and continue as described in Defining a Term List.

• Open and modify existing term lists. Select Open, select a term list, and continue as described in Defining a Term List.

• Export and import term lists. See Exporting and Importing Term Lists.

Defining a Term List

To define a term list, select New. The system displays a dialog box that asks for the name of the new term list. Enter a name and select OK. Then do the following tasks as needed:

• Enter descriptive information about the term list into the following optional fields on the Details tab:

  • Caption — Optional caption for the term list

  • Subject Area — Select the subject area where this term list will be used

  • Description — Longer description of the term list

  For information on Pattern, see Specifying the Pattern for a Term List.

• Add terms. To do so, select Add Term on the right. Or select the New Term button .

  A new row is added to the bottom of the term list.

• Add custom fields. To do so, enter a value into Field Name and then select the Add Field button on the right. Or select the New Field button .

  A new column is added on the right side of the term list.

• Enter values into cells. To enter a value, select a cell and type a value. Then move the cursor to another cell, press Enter, or select OK.

• Remove a term. To do so, select the row for the term and select Remove Term on the Details tab.

• Remove a custom field. To do so, select the column for the custom field and select the Remove Field button on the right.

Then save the term list. To do so, select Save or Save As. If you select Save As, specify a new name and then select OK.

Specifying the Pattern for a Term List

The %TERMLIST function returns a set that, by default, consists of members that are identified by the keys in the term list, in combination with the term list pattern.

If you intend to use a term list with the %TERMLIST function, then define the term list as follows:

• For each term, specify the value field as a member name or the numeric key.

• For Pattern, specify an expression of one of the following forms:

  • If the value field contains member names, use the form:

    [dimension name].[hierarchy name].[level name].[*]

  • If the value field contains member keys, use the form:

    [dimension name].[hierarchy name].[level name].&[*]

In either case, dimension name, hierarchy name, and level name are the names of the dimension, hierarchy, and level to which the member belongs. The asterisk represents the value in the value field. For an example, see %TERMLIST.

Exporting and Importing Term Lists

You can export term lists to comma-separated files and you can import term lists from such files.

Sample Term List File

The following shows the contents of an example term list file:

%%NAME,My Term List
%%CAPTION,My Caption
%%DESCRIPTION,My Description
%%SUBJECTAREA,HoleFoods
%%MODDATE,2014-06-06 11:31:10
Atlanta,Braves
Boston,Red Sox
New York,Yankees

As you can see, the first lines of the export contain items that start with %%; these lines contain descriptive information about the term list.

Deleting a Term List

To delete a term list:

1. Display the term list in the Term List Manager.

2. Select Delete.

3. Select OK.

Accessing Term Lists Programmatically

You can use the %DeepSee.TermListOpens in a new tab class to access term lists programmatically. This class provides class methods like the following:

• %ExportCSV()

• %GetTermLists()

• %GetValueArray()

• %Lookup()

• %TermListExists()

• And others

See the InterSystems Class Reference.