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

Pentaho Metadata Editor


Parent article

This section provides you with information and instructions to help you use the Pentaho Metadata Editor, a tool that allows you to build metadata models and domains. There is sample data available if you want to test Metadata Editor before importing your own data. This sample data is included in the Pentaho download.

To use the Pentaho Metadata Editor, you must have database administrator (DBA) skills. You need to know how to perform the following tasks: import tables, create relationships between tables, assign aggregations, add categories, and assign security. You should have an extensive knowledge of your databases, and know what type of data your business users want. These skills will allow you to map a business user model (logical model) to a complex relational database. This lets your users create Pentaho reports without a DBA's assistance.

A conceptual overview of relational data modeling


Metadata in Pentaho is based on relational data modeling, which maps the physical structure of your database into a logical business model.

Learn more

Get started with the Pentaho Metadata Editor

The following steps demonstrate how to use an example metadata model that is already deployed with the Pentaho Server.


NoteThe Pentaho Metadata Editor and the Pentaho Server must be running before you can begin.


  1. In the main window of the Metadata Editor, go to File Import from XMI File.

  2. Navigate to your installation of the Pentaho Server.

    For example, if you used the installer, navigate to pentaho/server/pentaho-server/pentaho-solutions. There can be several root pentaho-solution folders and each of them may contain one metadata model repository.
  3. Open the steel-wheels folder and click [MyBusinessModel].xmi where [myBusinessModel] is the name you have given the model. The .xmi file is the repository for Pentaho-related metadata and business views.

  4. Type Sample Data in the Save Model dialog box. If you see the message,

    This model already exists...
    click Yes to continue.This step processes the file and displays the structure of the repository (connections and business models) in the navigation pane on the left. Pentaho Metadata Editor, Sample Data file
  5. Log in to the User Console, and click New Report.

    Pentaho Metadata Editor, Select Data Source tab The Human Resources, Inventory, and Orders business models are displayed.

Create a domain

A metadata domain is a Pentaho term that represents all of the business objects created, stored and used in the metadata layer. A domain may consist of one or more connections, one or more models, security information, business tables, business views, categories, columns and concepts. You can create and save multiple metadata domains using the Metadata Editor.

Learn more

Apply metadata properties and concepts

When you created your domain, you modeled your database in a manner that is more intuitive than its physical representation. Next, you should define your metadata. The Pentaho metadata paradigm uses the term concept to mean a collection of metadata properties that can be applied to a given business object, such as a business table or column, for example.

Learn more

Publish a domain


You can share an XML representation of your domain with a Pentaho solution that your Pentaho Server recognizes, so that the server can access the metadata domain and its contents.

Learn more

Importing and exporting domains


When you save a domain, it is stored in a metadata repository. The Pentaho Server does not use the metadata repository. Instead, it accesses an XML file exported from the Pentaho Metadata Editor. Exporting your domain is a good way to ensure safe backups of your domains. When you import a new domain, it becomes the active domain in the Pentaho Metadata Editor.

Import a domain

Perform the following steps to import a domain:


  1. In the Pentaho Metadata Editor, go to File Import From XMI File.

    NoteYou may be prompted to save the currently active model if you have any unsaved changes pending.
  2. In the file browser, select your domain file and click OK.

  3. In the Save Model dialog box, type a name for the domain.

    If you enter the name of an existing domain, that domain is overwritten by the import.

Export a domain

Perform the following steps to export a domain:


  1. In the Pentaho Metadata Editor, go to File Export to XMI File.

    NoteYou may be prompted to save the currently active model if you have any unsaved changes pending.
  2. Type a file name and select a location to save your file.

    The default extension for a metadata domain XML file is .xmi.
  3. Click Save.


Once you have entered a name for your export file, the domain is exported to that file. You can inspect the export file using a text editor to view the underlying XML code.

Domain backup and recovery


Each domain can be saved to the Common Warehouse Metadata (CWM) repository with any name you like. The Save and Save As options are available from both the Pentaho Metadata Editor file menu and the toolbar. Each time a domain is saved to the repository, a recovery export file of the domain is saved to the file system, under the .pentaho-meta directory. This directory is typically located in the your home directory. The recovery file contains the last successfully saved state of the domain. The files are named recovery_[studio:domainname].xmi.

Domain restoration may be necessary if you need to revert to the last known good state of your domain in the event of repository errors or corruption. You can restore a domain to the last saved state by importing a recovery file.

Advanced topics


The following topics help to extend your knowledge of Metadata Editor beyond basic setup and use:




See our list of common problems and resolutions.

Learn more