Skip to main content

Pentaho+ documentation has moved!

The new product documentation portal is here. Check it out now at


Hitachi Vantara Lumada and Pentaho Documentation

Creating link dimensions

Parent article

Dimensions organize attributes and measures so that users can answer business questions quickly. The most common dimension used is a time dimension, but dimensions are also used to classify people (such as customers), geographical places, and product lines.

Shared Dimensions are dimensions which can be shared for later use. Shared dimensions are particularly useful if you are connected to a Pentaho Repository or your workstation is shared by different users. They allow you to define and save your annotations, and then share them with other users. The Link Dimension annotation allows you to reuse a previously created shared dimension. For example, if you want to create a generic dimension for reuse, such as a standard time dimension, you can create a Shared Dimension and then link directly to that dimension's key. Linking to the dimension key will import all hierarchies from the Shared Dimension into your data model, resulting in a star schema which joins the shared dimension table to the fact table.

When creating a shared dimension, you will need to select a field to use as a Dimension Key which allows you to identify and use the Shared Dimension in your transformation. For example, in the Shared Dimension step, you can select the field Year and annotate it as a Dimension Key. You may also select the field Year again along with the fields Month and Week to annotate as attributes. Then, in the Annotate Stream step, select the field Year to annotate as a Link Dimension. Here, select the Shared Dimension previously created using the Year field. All annotations defined in the Shared Dimension will be populated in run time. When the model is published, the annotations Year, Month, and Week will be in the model.

NoteIf you are using link dimensions as part of your Streamlined Data Refinery (SDR) process, be aware that link dimension annotations are dependent on shared dimensions, and shared dimensions cannot use a data service for their source. Therefore, if you select a Pentaho Data Service as the source of your model in the Build Model job entry, the link dimensions which you have defined here will not be linked to your model. See Pentaho Data Services for more information about data services.

Create a link dimension

Before you begin

This step assumes you have created a shared dimension which you want to use.
These steps guide you through creating a link dimension using the Annotate Stream step.


  1. If you haven't done so already, complete steps 1-7 in Use the Annotate Stream step.

  2. Select Link Dimension from the Actions drop-down menu. The Name - Value table auto-populates with a list of annotation properties for the dimension.

    Dimension NameEnter a name for the dimension. Note that you can overwrite the dimension name set in the Shared Dimension step.
    Shared DimensionEnter or select a previously created Shared Dimension to link to from the drop-down menu.
    Create link dimension
  3. Use the Previous and Next buttons to navigate through the fields. When finished, click OK to save your annotations and close the dialog box, or Cancel to close the dialog box without saving your annotations.

Next steps

Remember that before your link dimension can be used by others, you must create a dimension key for the shared dimension to link to. When creating annotations, you can use a single field more than once, so you will be able to use the same field for both the key and to create annotations.

Create a dimension key

Before your link dimension can be used by others, you must create a dimension key for the shared dimension to link to.
NoteYou can create multiple annotations on the same field. For example, you might want to create an attribute and a dimension key on the same field, such as Year, in your time dimension.


  1. If you haven't done so already, complete steps 1-7 in Use the Annotate Stream step.

  2. From the list in the Annotations table, choose a field to use as the dimension key by double-clicking it.

    For example, you may want to use the field Calendar Year as the dimension key for the shared dimension Year. Optionally, you can select the field in the Annotations table and then click the Edit (Pencil icon) in the upper-right corner.The Annotate dialog box appears for the selected field.
  3. Select Create Dimension Key from the Actions drop-down menu for the field.

    The Name - Value table auto-populates with the name and value of the dimension key. You can edit the value to use as the dimension key.
  4. Click OK to save the annotation and close the dialog box.

    In the Shared Dimension dialog box, the selected field will now appear with the summary that it is the key for the shared dimension. For example, the field Calendar Year may display Calendar Year is key for dimension Year in the Summary column.