Skip to main content

Defining Term Lists

Term lists provide a way to customize an InterSystems IRIS® data platform Business Intelligence model without programming. This page describes how to define them.

Also see Accessing the BI Samples.

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.

Tip:

You can use term lists to define matching dictionaries for use with unstructured data. See Using Unstructured Data in Cubes.

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:

The Term List Manager with no open term list. The available buttons include New, Open, Save, Save As, Delete, and Export.

On this page you can do the following:

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 generated description: icon term list add term.

    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 generated description: icon term list add field on the right. Or select the New Field button generated description: icon term list add field alt.

    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 generated description: icon term list remove field 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.

Exporting a Term List

To export a term list:

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

  2. Select Export. The system generates a file.

    Depending on your browser settings, the browser then either saves the file automatically (in the default download directory for this browser) or opens the file in a default application.

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.

Importing a Term List

To import a term list:

  1. In the right area, for CSV File to import, select Browse... and navigate to the file.

  2. Select Import.

    InterSystems IRIS examines the name of the term list as contained in this file. Then:

    • If the system already has a saved term list with the same name, the system asks if you want to overwrite that term list. If you potentially want to overwrite the term list, select Yes. Otherwise, select Cancel to cancel the import action.

      If you select Yes, the system imports the file and displays the new definition of the term list, but does not save the change.

    • If the system does not yet contain a saved term list with the same name, the system imports the file and displays the new term list, but does not save the new term list.

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

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.

FeedbackOpens in a new tab