Skip to main content

This is documentation for Caché and Ensemble. See the InterSystems IRIS version of this content.Opens in a new tab

Please read this important announcement about the future of Caché and Ensemble maintenanceOpens in a new tab. Contact your account team to migrate to InterSystems IRIS.

Reference Information for Cube Classes

The Architect creates and modifies cube classes, which you can also create and edit directly in Studio. This appendix provides reference information on these classes. It discusses the following topics:

Also see “When to Recompile and Rebuild,” earlier in this book, as well as “Using Advanced Features of Cubes and Subject Areas” in the Advanced DeepSee Modeling Guide.

Requirements for a Cube Class

To define a cube, create a class that meets the following requirements:

  • It must extend %DeepSee.CubeDefinitionOpens in a new tab.

  • It must contain an XData block named Cube

  • For this XData block, XMLNamespace must be specified as follows:

    XMLNamespace = "http://www.intersystems.com/deepsee"

  • The root element within the XData block must be <cube> and this element must follow the requirements described in the rest of this appendix.

  • It is useful, but not required, for the class to specify the DependsOn compiler keyword so that this class is compiled only after the source class of the cube is compiled and can be used.

  • The class can define the DOMAIN parameter, which specifies the domain to which any localized strings belong. For example:

    Parameter DOMAIN = "PATIENTSAMPLE";

    For details, see the chapter “Performing Localization” in the DeepSee Implementation Guide.

For example:

Class DeepSee.Model.PatientsCube Extends %DeepSee.CubeDefinition [DependsOn=DeepSee.Study.Patient]
{

XData Cube [ XMLNamespace = "http://www.intersystems.com/deepsee" ]
{
<cube 
name="Patients"  
 owner="_SYSTEM"
 caption="Patients"
 sourceClass="DeepSee.Study.Patient"
 other_cube_options...
>

<measure measure_definition/>
...

<dimension dimension_definition/>
...

</cube>
}

Studio provides assistance as you type. For example:

generated description: studio assistance

Common Attributes in a Cube

Most of the elements in the cube have the following attributes, which are listed here for brevity:

Attribute Purpose
name Logical name of the element for use in MDX queries against this cube. See “Names for Model Elements,” earlier in this book.
displayName (Optional) Localized name of this element for use in user interfaces. If you do not specify this attribute, the user interface instead displays the value specified by the name attribute. For details, see the chapter “Performing Localization” in the DeepSee Implementation Guide.
description (Optional) Description of this element.
disabled (Optional) Controls whether the compiler uses this element. If this attribute is "true" then the compiler ignores the element; this is equivalent to commenting out the element. By default, this attribute is "false"
additionalDescription (Optional) Additional notes about this element, for display only within the Architect and Studio.

<cube>

The <cube> element is the root element in the XData block. This element contains the following contents:

Attribute or Element Purpose
name, displayName, description, disabled See “Common Attributes in a Cube” earlier in this appendix.
sourceClass Complete package and class name of the base class used by this cube. See “Possible Source Classes for a Cube” earlier in this book.
owner (Optional) Name of owner of cube.
resource (Optional) Name of the resource used to control access to this cube, when it is accessed via the DeepSee Architect. See the DeepSee Implementation Guide.
caption (Optional) Caption to display in the Analyzer and other utilities when working with this cube.
countMeasureCaption (Optional) Caption to use for the default measure, which counts records. The default caption is Count. Internally, the name of the measure is %Count.
countMeasureName (Optional) Name to use for the default measure, which counts records. The default name of this measure is %Count.
defaultListing (Optional) Specify the logical name of the <listing> to use as the default in this cube. See “<listing>,” later in this appendix.
nullReplacement (Optional) Specifies the string to use as the member name if the source data for a level is null. For example, specify nullReplacement="None"

This option is overridden by the nullReplacement attribute, if specified, for a given <level>.
bucketSize (Optional) Specifies the size of the caching buckets used for this cube. A group is 64,000 contiguous rows, and a bucket is an integer multiple of groups. The default bucket size is 8. That is, by default, the first 512,000 rows are bucket number 1, the next 512,000 rows are bucket number 2, and so on.

In some cases, you may want to increase this value if you expect to have a large number of facts and do not expect many updates to older values within the cube. If you change this value, be sure to delete all cached results for this cube. To do so, call the %KillCache() method of the cube definition class.

actionClass (Optional) Specifies an associated KPI class that defines actions that are available for pivot tables based on this cube. Specify the full package and class name of a subclass of %DeepSee.KPIOpens in a new tab.
maxFacts (Optional) Specifies the maximum number of rows in the fact table. This determines the number of rows of the base table that the system uses when building the cube. Use this attribute to assist in debugging when you do not want to process the entire base table. By default, all rows of the base table are processed.
bitmapChunkInMemory (Optional) Controls how DeepSee builds the indices: using a process-private global (slower but does not lead to <STORE> errors) or entirely in memory (faster). The default is "false", in which case DeepSee uses a process-private global for temporary storage while it builds in the indices.

If your cube does not contain a large number of indices (dimensions and measures) and does not contain dimensions with very large numbers of members, you can use "true" for faster performance. It is worthwhile to try this setting; if you encounter <STORE> errors when you build the cube, then change the value back to the default.
initialBuildOrder (Optional) Used to construct an optional ORDER BY clause for use when building the entire cube; does not affect incremental updates. Specify a comma-separated list of fields in the source table. You can use the SQL keywords ASC and DESC. For example: "Age DESC,Gender"
buildRestriction (Optional) Specifies an optional WHERE clause to use when building or updating the cube; this causes the cube to use a subset of the records. Specify an SQL comparison expression that uses fields in the source table. For example: Gender='F'. Has no effect on a cube based on a data connector.
abstract (Optional) See “Using Cube Inheritance to Define Reusable Elements,” in the Advanced DeepSee Modeling Guide.
inheritsFrom
disableListingGroups (Optional) Specify this attribute as "true" if you want to prevent anyone from defining a listing group that uses this cube as a target. The default is "false". See “Compiling a Listing Group,” earlier in this book.
version (Optional) See the appendix “Using Cube Versions” in the DeepSee Implementation Guide.
defaultMeasure, defaultMember, precompute Do not use.
<measure> (Optional) You can include zero or more <measure> elements, each of which defines a measure.
<dimension> (Optional) You can include zero or more <dimension> elements, each of which defines a dimension.
<listing> (Optional) You can include zero or more <listing> elements, each of which defines a listing, to be available in the Analyzer.
<listingField> (Optional) You can include zero or more <listingField> elements, each of which defines a listing, to be available in the Analyzer.
<namedSet> (Optional) You can include zero or more <namedSet> elements, each of which defines a named set, which is an alias for a member or for a set of members.
<calculatedMember> (Optional) You can include zero or more <calculatedMember> elements, each of which defines a member that is calculated in terms of other members. This is typically used to define measures that are calculated based on other measures.
<relationship> (Optional) You can include zero or more <relationship> elements. A <relationship> element connects another cube to your cube so that you can use levels of that other cube when you query your own cube.
<index> (Optional) You can include zero or more <index> elements, each of which defines an optional, custom index on the fact table. This can be useful if you plan to run SQL queries on the fact table. For information on the fact table, see “Details for the Fact and Dimension Tables.”
<expression> (Optional) You can include zero or more <expression> elements, each of which defines an expression (typically an intermediate value), for use in the definition of one or more measures or dimensions. Values of expressions are not stored but are available during cube build time.

For example:

<cube 
name="Patients"  
 owner="_SYSTEM"
 caption="Patients"
 sourceClass="DeepSee.Study.Patient"
 >
...

<measure>

The <measure> element defines a measure; your cube can have any number of measures. This element has the following attributes:

Attribute Purpose
name, displayName, description, disabled See “Common Attributes in a Cube” earlier in this appendix.
sourceProperty Specify one of these attributes in almost the same way that you would specify Property or Expression in the Architect; see “Specifying the Source Values for a Dimension or Level” and “Details for Source Expressions,” earlier in this book. Notes:

  • For sourceProperty, use the same value you would enter for Property, enclosed within single quotes.

    For example: sourceProperty='Age'

  • For sourceExpression, use the same value you would enter for Expression, enclosed within single quotes.

    For example: sourceExpression='%source.property/100'

You can enclose the value in double quotes instead if the value itself does not contain any double quotes. For example: sourceExpression="%source.property/100"
sourceExpression
type (Optional) Specifies the data type for the measure. Most measures are numeric, which is the default. See “Specifying the Measure Type.”
iKnowSource, iKnowDomain, iKnowDictionaries, iKnowParameters (Optional) See “Using Unstructured Data in Cubes (iKnow)” in the Advanced DeepSee Modeling Guide.
aggregate (Optional) Specifies how to aggregate values for this measure, whenever combining multiple records. If you specify this, use one of the following values:

  • "SUM"

  • "COUNT" — Counts the records for which the source data has a non-null (and nonzero) value.

  • "MAX" — Uses the largest value in the set.

  • "MIN" — Uses the smallest value in the set.

  • "AVG" — Calculates the average value for the set.

For a boolean or a string measure, this attribute must be "COUNT".
hidden (Optional) If hidden="true" then the measure is defined and can be used in queries, but is not listed as an available measure in the Analyzer. This lets you define measures that serve as intermediate calculations.
scale (Optional) Specifies the number of decimal places to keep. By default, scale is 0, and DeepSee rounds each measure value to a whole number before writing it to the fact table.
linkClass, linkProperty (Optional) See “Linking to Another Table.”
searchable (Optional) If searchable="true" then DeepSee displays this measure as an option in advanced filters, where you can create filter expressions that refer to the measure value (typically to compare the measure value to a constant).

For a searchable measure, DeepSee adds an additional index, if appropriate, to support these expressions. See “Measure Search Expressions” in the DeepSee MDX Reference. A searchable measure cannot include square brackets or commas ([],) in its name.

Note that it may be possible to use a measure as a searchable measure in a manual MDX query even if it is not marked as searchable="true".

In all cases, the measure is also available for use in the same way as any other measure.
factName

(Optional) Name, in the generated fact table, for the column that corresponds to this measure. If this attribute is null, the system generates a name. This option does not apply to iKnow measures. Be sure not to use an SQL reserved word. For a list of the SQL reserved words, see “Reserved Words” in the Caché SQL Reference. The name must start with either a letter or a percent sign (%). If the first character is %, the second character must be Z or z. For more details on restrictions, see “Class Members” in the appendix “Rules and Guidelines for Identifiers” in the Caché Programming Orientation Guide. Also, do not use fact or listing, in any combination of lowercase and uppercase characters.
factSelectivity (Optional, not used by DeepSee) Value to override the generated selectivity of the property in the fact table class. DeepSee queries do not use this parameter. This option is intended for cases where SQL is used directly against the generated fact table and the generated selectivity needs to be overridden.

Specify a positive value less than or equal to 1. For details, see SetFieldSelectivity() in %SYSTEM.SQLOpens in a new tab.
formatString (Optional) Controls how the values are displayed. See “formatString Details.”
units (Optional) Indicates the units in which the measure value is expressed. Currently this attribute is provided only for general information.
listingFilterOperator and listingFilterValue (Optional) These attributes specify an optional additional filter that is applied when a user selects this measure in a pivot table and then displays a listing. For details, see “Specifying Additional Filtering for Listings,” in the chapter “Defining Measures.”

For example:

<measure name="Test Score" sourceProperty="TestScore" aggregate="SUM"/>
<measure name="Avg Test Score" sourceProperty="TestScore" aggregate="AVG"/>
<measure name="Allergy Count" 
   sourceExpression="##class(Cubes.StudyPatients).GetAllergyCount(%source.%ID)"/>

Notice that the Allergy Count measure uses a utility method that is defined within the cube class.

%COUNT Measure

DeepSee includes a predefined measure named %COUNT, which returns the number of facts in a query.

Measures Dimension

DeepSee automatically creates the Measures dimension, and places all measures into it.

formatString Details

The formatString attribute is a pieced string as follows:

Format^Color

  • For the Format piece, specify a string that consists of one to four subpieces as follows:

    positive_format;negative_format;zero_format;missing_format;

    Where positive_format controls how a positive value is displayed, negative_format controls how a negative value is displayed, zero_format controls how zero is displayed, and missing_format controls how a missing value is displayed.

    For details, see “Specifying a Format String,” earlier in this book.

  • For the Color piece, specify a string that consists of one to four subpieces as follows:

    positive_color;negative_color;zero_color;missing_color;

    Where positive_color controls the color for a positive value, negative_color controls the color for a negative value, zero_color controls the color for zero, and missing_color controls the color for a missing value.

    For each of these, specify a CSS color nameOpens in a new tab or a hex color codeOpens in a new tab.

For date measures, use the following variation:

%date%^Color

Where Color is as given above. The %date% piece formats the date according to the default date format for the current process.

<dimension>

The <dimension> element defines a dimension, which contains one or more hierarchies, each of which contains one or more levels. Your cube can have any number of dimensions.

The <dimension> element has the following contents:

Attribute or Element Purpose
name, displayName, description, disabled See “Common Attributes in a Cube” earlier in this appendix.
sourceProperty Specify one of these attributes in almost the same way that you would specify Property or Expression in the Architect; see “Defining the Source Values for a Dimension or Level.” Notes:

  • For sourceProperty, use the same value you would enter for Property, enclosed within single quotes.

    For example: sourceProperty='Age'

  • For soureExpression, use the same value you would enter for Expression, enclosed within single quotes.

    For example: sourceExpression='%source.property_"ABC"'

You can enclose the value in double quotes instead if the value itself does not contain any double quotes. For example: sourceExpression="%source.property"
sourceExpression
type Specify one of the following:

calendar (Optional) Specify this only if type is "time". The calendar attribute specifies the calendar to use when assigning records into members of time levels. Use "gregorian" (the default) for the Gregorian calendar. Or use "hijriTabular" or "hijriObserved" for a Hijri calendar.
iKnowMeasure and iKnowType (Optional) See “Using Unstructured Data in Cubes (iKnow)” in the Advanced DeepSee Modeling Guide.
hasAll (Optional) Indicates whether this dimension has an All Level. The default is "true".
allCaption (Optional) Name used for the All Level and All Member for this dimension. The default name is All dimension, where dimension is the dimension name.
allDisplayName (Optional) Specifies the localized name used for the All member. If you do not specify this attribute, the user interface instead displays the value specified by the allCaption attribute.
hidden (Optional) If hidden="true" then the dimension is defined and can be used in queries, but the Analyzer does not list the dimension as available for use. The default is "false".
showHierarchies (Optional) Controls whether the Analyzer displays the hierarchy names within this dimension. Specify one of the following:

  • "default" — Display the hierarchy names only if there is more than one hierarchy.

  • "true" — Always display the hierarchy names.

  • "false" — Never display the hierarchy names.

This attribute has no effect on the queries themselves.
sharesFrom (Optional) See “Defining a Shared Dimension,” in the Advanced DeepSee Modeling Guide. Do not specify this option for date dimensions, which are automatically shared.
dimensionClass (Optional) See “Defining Computed Dimensions” in the Advanced DeepSee Modeling Guide.
<hierarchy> Specifies a hierarchy within this dimension. You must include at least one <hierarchy> element and can include multiple <hierarchy> elements.

<hierarchy>

The <hierarchy> element specifies a hierarchy within the given dimension. This element has the following contents:

Attribute or Element Purpose
name, displayName, description, disabled See “Common Attributes in a Cube,” earlier in this appendix.
hidden (Optional) If hidden="true" then the hierarchy is defined and can be used in queries, but the Analyzer does not list the hierarchy and its levels as available for use. The default is "false".
<level> Specifies a level within this hierarchy. You must include at least one <level> element and you can include multiple <level> elements.

<level>

The <level> element specifies a level within the given hierarchy. It has the following contents:

Attribute Purpose
name, displayName, description, disabled See “Common Attributes in a Cube,” earlier in this appendix.
sourceProperty, sourceExpression Specify one of these attributes. The syntax is almost the same as you would use for Property or Expression in the Architect; see “Defining the Source Values for a Dimension or Level.” Notes:

  • For sourceProperty, use the same value you would enter for Property, enclosed within single quotes.

    For example: sourceProperty='Age'

  • For sourceExpression, use the same value you would enter for Expression, enclosed within single quotes.

    For example: sourceExpression='%source.property_"ABC"'

You can enclose the value in double quotes instead if the value itself does not contain any double quotes. For example: sourceExpression="%source.property"

For the requirements for levels within a time or age dimension, see “Defining a Time Level” and “Defining an Age Level.”

For levels in an iKnow dimension, sourceProperty and sourceExpression are ignored, because these levels use a different mechanism to specify the source values. See “Using Unstructured Data in Cubes (iKnow)” in the Advanced DeepSee Modeling Guide.
timeFunction Only for levels within a time or age dimension. See “Defining a Time Level” and “Defining an Age Level.”
timeOffset (Optional) Only for levels within a time dimension. See “Specifying a Date Offset.”
timeFormat (Optional) Only for levels within a time dimension. See “Specifying a Time Format” in the chapter “Details of Defining Levels.”
list (Optional) If this attribute is "true" then the source value is expected to be a list, and each item in the list becomes a member of this level.

The default is "false".

By default, the list is expected to be in $LIST format. To use a string consisting of a character-delimited list, specify listDelimiter.A list-based level cannot have parent levels or child levels.
listDelimiter (Optional) Specifies the delimiter used to separate items in the list that is used as the source data for the level. Use this if the list is a character-separated list.
nullReplacement (Optional) Specifies the string to use as the member name if the source data for this level is null. For example, specify nullReplacement="No City".
rangeExpression (Optional) For numeric data, this specifies how to assign numeric values to bins (each bin is a member of this level). For other data, this specifies replacement values. This attribute also controls the default order of the members of this level. See the subsections “Defining a Basic Range Expression” and “Defining a Compact Multi-Range Expression.”
useDisplayValue (Optional) For properties that have values for the DISPLAYLIST and VALUELIST parameters, this attribute specifies which value to include in the index. If this attribute is "false" (the default), the system uses the value given by VALUELIST; if this attribute is "true", the system uses the value given by DISPLAYLIST.

This option is ignored if you specify linkClass and linkProperty.
sort (Optional) Specifies how to sort members of this level by default. For a level in a time dimension, specify "asc" or "desc"

For a level in a data dimension, specify "asc", "asc numeric", "desc", or "desc numeric"
linkClass, linkProperty (Optional) See “Linking to Another Table.”
factName

(Optional) Name, in the generated fact table, for the column that corresponds to this level. If this attribute is null, DeepSee generates a name. This option does not apply to time levels or iKnow levels.

See the comments for factName for <measure>.
dependsOn (Optional) Specifies the level (or relationship) on which this level has a dependency. Specify the full MDX identifier of the level (or relationship) . Or specify a comma-separated list of MDX level (or relationship) identifiers. See “Defining Dependencies Between Levels in Different Hierarchies.” This attribute is completely unrelated to the DependsOn compiler keyword.
useAsFilter (Optional) Specifies whether the level can be used as a filter control in the dashboard. If this attribute is "true" (the default), users can select this level when adding a filter control; if this attribute is "false", the level is not listed as an option. The purpose of this option is only to reduce the number of choices seen in the Dashboard Editor, and there is no effect on the Analyzer or on the engine.
factSelectivity (Optional, not used by DeepSee) Value to override the generated selectivity of the property in the generated level table. DeepSee queries do not use this parameter. This option is intended for cases where SQL is used directly against the level table and the generated selectivity needs to be overridden.

Specify a positive value less than or equal to 1. For details, see SetFieldSelectivity() in %SYSTEM.SQLOpens in a new tab.
hidden (Optional) If hidden="true" then the level is defined and can be used in queries, but the Analyzer does not list the level as available for use. The default is "false".
<member> (Optional) You can include any number of <member> elements, each of which defines a member of the level.
<property> (Optional) You can include any number of <property> elements, each of which defines a property of the level.

For example:

<level name="ZIP" sourceProperty="HomeCity.PostalCode" />

For another example, the following level definition also defines a property for that level:

<level name="City" sourceProperty="HomeCity.Name">
  <property name="Population" sourceProperty="HomeCity.Population" />

Specifying a Date Offset

In some cases, you may need a time level to match a corporate financial calendar that does not start on 1 January. For example, in many companies, the financial year starts 1 Oct. Consider the following pivot table:

generated description: fiscal year example simple

In this case, the member FY 2005 consists of records of sales between 1 October 2004 and 30 September 2005, inclusive.

To create a level like this, specify the timeOffset and timeFormat attributes of the level (which must be within a time-type dimension). This section discusses the timeOffset attribute; the next section discusses timeFormat.

The timeOffset attribute specifies an amount of time to add to the source values used in this level; this amount of time can be negative or positive. The system uses this at cube build time.

For timeOffset, specify an amount of time by specifying a string of the following form:

#y#m#d

Where # is a number, #y represents an amount of time in years, #m represents an amount of time in months, and #d represents an amount of time in days. If you omit an element, DeepSee uses zero in its place. For example, the string 3m15d represents three months and 15 days.

The most common value for timeOffset is -3m, which you use if the fiscal year starts in 1 October of the previous year. If timeOffset="-3m", DeepSee subtracts three months to each time value used in this level. For example, for this level, the date 1 Jan 2010 is converted to 1 Oct 2009.

Other levels are unaffected, even within the same dimension. This means that you can also define more granular levels that display the actual dates. For an example, see “Handling a Calendar That Has a Date Offset.”

Defining a Basic Range Expression

For rangeExpression, the basic syntax is as follows:

value_or_range:new_value;value_or_range:new_value; ... ;

Here new_value is a single value, which DeepSee treats as a string and uses as the name of a level member. Also, value_or_range is any of the following:

  • A single value such as 5 or Louisiana

  • A range in the form (value1,value2)

  • A range in the form [value1,value2]

  • A range in the form (value1,value2]

  • A range in the form [value1,value2)

In these expressions, value1 and value2 are numeric values or null (that is, omitted from the expression). The left and right parentheses indicate that the range is not inclusive at the given endpoint. The left and right square brackets indicate that the range is inclusive at the given endpoint. For example, (45,49] represents all values greater than 45 and less than or equal to 49.

Defining a Compact Multi-Range Expression

In some cases, it is necessary to define many ranges for a given level, which can be a tedious process. Also the resulting range expression (when viewed in Studio) is difficult to read. In such cases, you may want to use the following alternative syntax for the value of rangeExpression:

rangeExpression="[start:increment:end]:replacement;"

Or use the appropriate parenthesis in place of either square bracket (details below).

This syntax generates a series of ranges.

Here, start is the numeric start value of the first range, end is the numeric end value of the last range, and increment is the numeric value by which the ranges are defined. The first range extends from start to start plus increment, and so on.

Also, replacement is an expression that is used as the replacement value. Within replacement, you can use the following elements:

  • %1 — is replaced with the start value of the range

  • %2 — is replaced with the end value of the range

  • $$$eval(expression) — causes the system to evaluate the contained expression. For example: $$$eval(%2-1) returns the end value of the range minus one

The square brackets or parentheses affect how the start and end values are treated, in the generated start and end ranges:

  • A square bracket causes the value to be included in the range.

  • A parenthesis causes the value to be excluded from the range.

At the intermediate range boundaries, the boundary value is always assigned to the upper range, rather than the lower range. That is, for intermediate ranges, the opening bracket is always [ and the closing bracket is always ).

Consider the following range expression:

rangeExpression="[0:30:90]:%1 to $$$eval(%2-1);"

This generates the same members as the following longer form:

rangeExpression="[0,30):0 to 29;[30,60):30 to 59;[60,90]:60 to 90;"

If the value end - start is not an integer multiple of increment , the last range extends beyond end. For example, consider the following range expression:

rangeExpression="[0:30:100]:%1 to $$$eval(%2-1);"

This generates the same members as the following longer form:

rangeExpression="[0,30):0 to 29;[30,60):30 to 59;[60,90):60 to 90;[90,119]:90 to 119;"

<member>

The <member> element is primarily for advanced use. See “Manually Specifying the Members of a Level,” in the chapter “Using Additional Advanced Features of Cubes and Subject Areas” in the Advanced DeepSee Modeling Guide.

The <member> element has the following contents:

Attribute Purpose
name, displayName, description, disabled See “Common Attributes in a Cube,” earlier in this appendix.
spec If the level is contained in a dimension that has type="computed", specify the SQL query that returns the IDs of the fact table rows (or the source table rows) that this member uses.

In other cases, optionally specify the value to use as the member key. If you omit this, name becomes the member key.

<property>

A level may contain zero or more custom level properties. These are properties whose value is derived from the source data and is associated with a specific member of a level. For example, the city level could include properties such as population or ZIP code. For each city, there would be one value of each of these properties.

The <property> element has the following contents:

Attribute Purpose
name, displayName, description, disabled See “Common Attributes in a Cube,” earlier in this appendix.
sourceProperty Specify one of these attributes in almost the same way that you would specify Property or Expression in the Architect; see “Specifying the Source Values for a Dimension or Level” and “Details for Source Expressions.” Notes:

  • For sourceProperty, use the same value you would enter for Property, enclosed within single quotes.

    For example: sourceProperty='MyProp'

  • For sourceExpression, use the same value you would enter for Expression, enclosed within single quotes.

    For example: sourceExpression='%source.MyProp_"ABC"'

You can enclose the value in double quotes instead if the value itself does not contain any double quotes. For example: sourceExpression="%source.MyProp"
sourceExpression
sort (Optional) Specifies how to use this property to sort members of the level that contains this property. You can sort a level by multiple properties; if you do, the sorting is applied in the order in which you define the <property> elements; the first property controls the primary sort, the second property controls the secondary sort, and so on.

Specify "asc", "asc numeric", "desc", or "desc numeric"

By default, the property does not affect the sort order of the members.
isName (Optional) If "true", this attribute specifies that, for a given level member, DeepSee should use the value of this property to specify the names of that member.

Specify either "true" or "false" (the default).
isDescription (Optional) If "true", this attribute specifies that, for a given member, DeepSee should use the value of this property as the tooltip for the member. Specify either "true" or "false" (the default).
isReference (Optional) If "true", this attribute specifies that DeepSee should not store the property value, but should instead define the property as an SQL computed field that refers to the original source tables. If you specify isReference="true", the level must be defined so that the member keys are the IDs of the records on which the level (and its properties) are based.
useDisplayValue (Optional) For class properties that have values for the DISPLAYLIST and VALUELIST parameters, this attribute specifies which value to use for the property. If this attribute is "true" (the default), the system uses the value given by DISPLAYLIST; if this attribute is "false", the system uses the value given by VALUELIST.
linkClass, linkProperty (Optional) See “Linking to Another Table.”
factName (Optional) Name used (in the generated dimension table) for the column that corresponds to this property. If this attribute is null, DeepSee generates a name. You do not need to worry about this unless you plan to issue SQL queries directly against the generated dimension table.

Despite the name of this attribute, properties are not contained in the fact table. They are contained in the table that corresponds to the level to which the property belongs.

See the comments for factName for <measure>.
formatString (Optional) Controls how the values are displayed. See “formatString Details,” earlier in this appendix. In the format string, you can also use the special character 0, which serves as a placeholder for leading zeros. For example, 00000 would show a five-digit number padded with leading zeros.
hidden (Optional) If hidden="true" then the property is defined and can be used in queries, but is not listed as an available property in the Analyzer.

For example:

<property name="Population" sourceProperty="City.Population"/>

Intrinsic Properties

For each level, DeepSee also automatically defines a set of intrinsic properties. These are listed in the DeepSee MDX Reference.

<listing>

A cube can contain zero or more named listings. These are available in the Analyzer.

The default listing for a cube is either the listing specified in the defaultListing attribute for the <cube> element (if specified) or the first <listing> element contained in the <cube>.

The <listing> element has the following contents:

Attribute Purpose
name, displayName, description, disabled See “Common Attributes in a Cube,” earlier in this appendix.
fieldList Comma-separated list of fields to display. For options, see “Specifying a Simple Listing,” earlier in this book. For options in a data connector listing, see “Specifying a Data Connector Listing.”
formatList List (delimited by carets) of CSSOpens in a new tab formatting instructions for the listing. Each piece of the list is applied to the corresponding column in the listing. This list must have the same number of elements as there are columns, and each list element must have one of the following forms:

  • {CSS formatting instruction}, for example, {text-align:center;} — Formats the corresponding column.

    You can use {text-align:left;} or {text-align:center;}. Other instructions are ignored.

  • display:none; — Hides the corresponding column.

  • Null — Displays the corresponding column in the default style.
orderBy Applies only to simple listings. This attribute is a comma-separated list of fields by which to sort the listing. The overall sort is controlled by the first field in the list, the secondary sort is controlled by the second field, and so on.

After a field name, you can include the ASC or DESC keyword to sort in ascending or descending order, respectively. For additional options, see “Specifying a Simple Listing,” earlier in this book.

This attribute is ignored if the source is a data connector.
sourceClass Specifies the data connector, if any, on which this listing is based. If you specify this attribute, specify the name of a class that extends %DeepSee.DataConnectorOpens in a new tab. See the DeepSee Implementation Guide.
sql Specifies the custom SQL query, if any, for this listing. See “Specifying a Custom Listing,” earlier in this book.
listingType (Optional) Specifies the format of the listing. The default is "table". If you instead specify "map" the system displays a map-type listing, which displays a map with points marked by latitude and longitude. In this case, the listing query must contain the fields Latitude and Longitude (case-sensitive). See “Defining a Map-type Listing,” earlier in this book.
resource (Optional) Name of the resource used to control access to this listing. See the DeepSee Implementation Guide.

There are three kinds of listings, considering their sources:

  • Basic listings, which directly use the source table used by the cube

  • Data connector listings (which use data connectors)

  • Custom listings (which use custom queries)

In all cases, the system creates and uses an SQL query.

The following table indicates which attributes of <listing> you specify for these kinds of listings:

Kind of Listing fieldList orderBy sourceClass sql
Basic Required Optional Do not specify; this attribute would take precedence. Do not specify; this attribute would take precedence.
Data connector Optional Ignored Required Ignored
Custom Ignored Ignored Do not specify; this attribute would take precedence. Required

<listingField>

A cube can define zero or more listing fields that enable end users to create custom listings in the Analyzer (see “Creating a Custom Listing” in Using the DeepSee Analyzer).

Note:

DeepSee supports another kind of custom listing — a listing that does not necessarily use the source table of the cube. See “Defining a Custom Listing” in the chapter “Defining Listings.”

The <listingField> element has the following contents:

Attribute Purpose
name, displayName, description, disabled See “Common Attributes in a Cube,” earlier in this appendix.
fieldExpression SQL expression that refers to a field in the source table or (via arrow syntax, for example) to a field in a related table. If you specify displayName, do not specify an alias within the SQL expression. Conversely, if you specify an alias within the SQL expression, displayName is ignored and the field name cannot be localized. For details, see “Creating a Listing Field,” earlier in this book.
resource (Optional) Name of the resource used to control access to this listing field. See the DeepSee Implementation Guide.

For example:

<listingField name="PatientID" displayName="PatientID" fieldExpression="PatientID" />
<listingField name="Age" displayName="Age" fieldExpression="Age" />
<listingField name="Gender" displayName="Gender" fieldExpression="Gender" />
<listingField name="Test Score" displayName="Test Score" fieldExpression="TestScore" />
<listingField name="City" displayName="City" fieldExpression="HomeCity->Name" />
<listingField name="Doctor" displayName="Doctor" fieldExpression="PrimaryCarePhysician->LastName" />

<calculatedMember>

A cube can contain zero or more calculated members. A calculated member is a member that is defined in terms of other members. You can add two kinds of calculated member:

  • You can define a new measure that is based on other measures. For example, you can define a measure via a formula like the following:

    Measure 3 = (Measure 1 + Measure 2) / Measure 2)

    This is not the exact syntax.

  • You can define a new member that is based on other non-measure members. For example, you could create a Primary Colors member that combines the red, yellow, and blue members of the Favorite Color dimension.

    The new Primary Colors member refers to all the records of the fact table that correspond to the red, yellow, or blue members.

In MDX, a measure is considered to be a member, which is why both kinds of calculated elements are considered to be calculated members.

Note:

When you use this element to define a measure, the cube command in the MDX shell does not currently list this measure. You can, however, use the set in the MDX shell or in the query API.

The <calculatedMember> element has the following contents:

Attribute Purpose
name, displayName, description, disabled See “Common Attributes in a Cube,” earlier in this appendix. For the name attribute, DeepSee does not check whether the name is already in use. If you use a name that was previously used by another member of this dimension, you are overriding that member.
dimension Dimension to which this member belongs.
valueExpression MDX expression that defines the values for this member in terms of references to other members. For simple but common scenarios, see “Defining Calculated Elements” in Using the DeepSee Analyzer. For details and examples, see the DeepSee MDX Reference.
formatString (Optional) Controls how the values are displayed. See “Specifying a Format String.”
units (Optional) Indicates the units in which the measure value is expressed. Currently this attribute is provided only for general information.
listingFilter (Optional, applies only if dimension is "measures") Specifies an additional filter that is used when a user displays this calculated measure in a pivot table and then requests a detail listing. See “Specifying Additional Filtering for Listings for a Calculated Measure,” earlier in this book.

For example:

<calculatedMember name="Avg Age" dimension="MEASURES" valueExpression="[MEASURES].[Age]/[MEASURES].[%COUNT]"/>

In any context where you use this calculated member, DeepSee first evaluates the Age and Patient Count measures in that context and then performs the division.

Note:

You can define a calculated member in two other ways:

  • Within an MDX query by using the WITH clause.

  • Within the CREATE MEMBER statement.

    This is useful only within the MDX Shell.

See the DeepSee MDX Reference.

<namedSet>

A cube can contain zero or more named sets. A named set is an alias for a member or for a set of members. You can use named sets for rows or columns in your queries, and DeepSee substitutes the member or the set when you run the query.

Note:

When you define a named set, the cube command in the MDX shell does not list this set. You can, however, use the set in the MDX shell or in the query API.

The <namedSet> element has the following contents:

Attribute Purpose
name, displayName, description, disabled See “Common Attributes in a Cube,” earlier in this appendix. For the name attribute, DeepSee does not check whether the name is already in use. If you use a name that was previously used by another named set, you are overriding that named set.
setExpression MDX expression that returns a member or a set of members. For details and examples, see the DeepSee MDX Reference.

For example:

<namedSet name="SampleSet" setExpression="[homed].[h1].[city].MEMBERS" />
Note:

You can define a named set in two other ways:

  • Within an MDX query by using the WITH clause.

  • Within the CREATE SET statement.

See the DeepSee MDX Reference.

<relationship>

To define a one-way relationship from one cube to another cube, you define a <relationship> element in the first cube.

To define a two-way relationship, you define two complementary <relationship> elements, one in each cube.

The <relationship> element has the following attributes:

Attribute Purpose
name Name of the relationship. You use this logical name in MDX queries to use levels of the other cube. Typically this is the name of the other cube.
displayName, description, disabled See “Common Attributes in a Cube,” earlier in this appendix.
relatedCube Logical name of the other cube.
inverse Value of the name attribute in the <relationship> element in the other cube.
cardinality Cardinality of the relationship.
sourceProperty See “Defining a One-Way Relationship” and “Defining a Two-Way Relationship” in “Defining Cube-Cube Relationships” in the Advanced DeepSee Modeling Guide.
sourceExpression
 
nullReplacement (Optional) Specifies the string to use as the member name if the source data for this relationship is null. For example, specify nullReplacement="No City". Specify this attribute within a <relationship> that specifies sourceProperty or sourceExpression
factName

(Optional) Name used (in the fact table) for the column that corresponds to this relationship. If this attribute is null, the system generates a name.

See the comments for factName for <measure>.
linkClass, linkProperty Do not use. These are ignored.
dependsOn (Optional) Specifies the relationship on which this relationship has a dependency. Specify the logical name of the relationship. See “Defining Dependencies Between Levels in Different Hierarchies.” (Or, if the relationship depends upon a level, specify the MDX identifier of that level.)

This attribute is completely unrelated to the DependsOn compiler keyword.
Important:

When you compile the cube classes, first compile the independent cube, which is the one that does not define a source property or source expression for the relationship. To control the compilation order, specify the DependsOn keyword in the class definition of the dependent cube.

Similarly, you must build the independent cube first. The DependsOn keyword has no effect on the order in which cubes are built.

The following table summarizes which keywords to specify in each of scenarios:

Attribute In a One-way Relationship... In a Two-way Relationship...
inverse Omit this Specify this in both cubes
cardinality Use "one"

  • In the dependent cube, use "one"

  • In the independent cube, use "many"
sourceProperty or sourceExpression Specify as usual Applicable only in the dependent cube
factName Specify as usual Applicable only in the dependent cube; ignored in the other cube

For examples, see in “Defining Cube-Cube Relationships” in the Advanced DeepSee Modeling Guide.

<expression>

The <expression> element defines an optional expression that has a value for each row in the source table. Your cube can have any number of expressions.

The <expression> element has the following contents:

Attribute Purpose
name, description, disabled See “Common Attributes in a Cube,” earlier in this appendix.
sourceProperty, sourceExpression See the Advanced DeepSee Modeling Guide.
displayName, factName, linkClass, linkProperty Do not specify these attributes.

<index>

The <index> element specifies an optional, custom index that you add to the fact table. DeepSee does not use this index (because it automatically adds the indices that it needs).

You can add a custom index if you plan to access the fact table via SQL. The <index> element has the following contents:

Attribute Purpose
name, displayName, description, disabled See “Common Attributes in a Cube,” earlier in this appendix.
type Specifies the type of index. Use "bitmap", "bitslice", "index", or "key".
properties Specifies the fields of the fact table on which this index is based. Specify a comma-separated list of properties of the fact table class.

For example:

<index name="IndexName" type="bitmap"  properties="MxAge,DxGender"/>
Tip:

Remember that you can specify the factName attribute for most levels and measures, to control the names of the properties in the generated fact table class.

Next sectionReference Information for Subject Area Classes
Previous sectionDefining Listing Groups
FeedbackOpens in a new tab