Adding Dimensions to the SAMDbServer

Follow these 4 steps to add dimensions to the SAMDbServer.

1. Study / Know Your Data Model

First, you must know your data model and how you want the joins to be written. Since you are putting in place logic that will hide the SQL details from users, someone must know how the SQL is to be written. That someone is use, the sam_db_server developer.

2. Check for Table Usage in Existing Dimensions

Before deciding what course of action you need to take to add a dimension, you must first know if the table you will be querying from is already included in the known lists of dimensions. Check the existing dimensions for the query that you are trying to edit. Notice the alias name, and the fact that a table may be used more than once for totally different meanings in teh SQL joins.

3. Adding New Columns as Dimensions

When you are adding new columns as dimensions for tables that you already have dimensions defined for, you only need to add data for the new dimension into the Dimensions tables. But, if the table (well, really the alias) that you are querying from is not included in the query logic yet, then you must complete both the steps in this section and the steps in the next section on Adding Dimensions that Require New Tables.

When adding simply more columns, you can do so using the simple sam_admin command, sam_admin add dimension. Below are some examples, which can be run on d0mino.fnal.gov.

  setup sam_admin
  sam_admin add dimension ;# it will tell you the rest of the options
  sam_admin add dimension --name=kbyte_file_size --table=data_files \
            --column=kbyte_file_size --type=number --desc="File size in KBytes"
  sam_admin add mc dimension --name=pythia.topmass --desc="Pythia top mass"

  Note: These commands will prompt you for your Oracle username and password.

The details on what the sam_admin command does are included below for reference only.

4. Adding Dimensions that Require New Tables

If you are adding new tables to the dimension capabilities, you will need to perform these steps in order to ensure that the dimension query utility knows how to resolve the joins. These must be performed in development, as they require you to change code in sam_db_server. As such, you will have to follow the sam_db_server release cycle before these changes are available to the integration and production versions of SAM.

If you are simply adding new dimensions for columns in tables that are already used, then you can skip this section.