NOTE: This page is a work in progress, and the information described here is subject to change.




The SQL Compiler Query Debugger visualizes various stages of query compilation, optimization, and code generation. It requires open source Qt GUI toolkit for GUI front-end and a VNC running server on the Linux/CentOS machine.


The Debugger is in the form of a dynamic-link library (, which is loaded into sqlci process at run time.


Building the SQL Compiler Query Debugger


The GUI Debugger is integrated into Trafodion’s build system, which means it is built along with Trafodion, and both in debug or release version. The source code is in sql/SqlCompilerDebugger. It is also an optional part, it won't get built if you leave environment variable QT_TOOLKIT empty in If you want to build it, you need Qt 4.8.5, but be aware that it is available under LGPL license, which is not compatible with ASF software distributions.

sudo yum install qt-devel
export QT_TOOLKIT=<a path such that $QT_TOOLKIT/bin/qmake can be executed>

cd $TRAF_HOME/../sql/SqlCompilerDebugger
chmod +x

Invoking the SQL Compiler Query Debugger


Invoking in a VNC Session


To use the Debugger in a VNC session:


  1. Run a VNC server in your linux machine, connect to the machine with a VNC client.
  2. In your VNC session, open a terminal, start a sqlci session.
  3. In sqlci, prefix the query with the keyword display:

    display select * from table1;the window of Debugger will display.


Invoking in GDB


In gdb session, if you want to see the tree structure of an ItemExpr or RelExpr, you can call displayTree() of the node(the node object should be an ExprNode, e.g. p ((ExprNode*)obj)->displayTree()). this will bring up a window visualizing the tree structure. Clicking "continue" button will close the window and return to your gdb session.


Using the SQL Compiler Query Debugger


Breakpoints Dialog Box


When you launch the Debugger, the Breakpoints dialog box appears first:



Breakpoints dialog box.png

This dialog box is to set stop points at important phases for debugging. At any time, you can open the Breakpoints dialog box and change the configuration by clicking on the hand icon Hand.png on the toolbar or by selecting Options > Breakpoints… from the menu.


Main Window


After any breakpoint is set, the main window appears. It contains several subwindows to display the query tree, item expressions, properties, and steps for optimizing the query.



Main window.png

Main Window Menus


All functionality of the debugger can be found in main window's menu.



Main window menu.png



The File menu is currently unavailable.





Tools menu.png

The Tools menu provides following informations, which are displayed as sub-windows:


Memo...Toggles visibility of Memo window
Properties...Shows properties of a selected node in the query tree
ItemExpr...Shows expression tree of an item expression
Query Analysis...Shows query analysis detail, this is available only in phases of AFTER_ANALYZE, AFTER_OPT1, and AFTER_OPT2




Options menu.png


ContinueConctrols SQL execution to continue and stop after next phase of compilation
Breakpoints...Sets breakpoints at the phases where you are interested




Memo menu.png


The Memo menu controls process of optimization. For more information, see Memo Viewer.


StepExecutes one optimization step
StepGrpContinues and stops at a group specified in the group input widget, ignoring other input widgets
StepExprContinues and stops at an expression specified in both the group input widget and the expression input widget
StepTaskNumContinues and stops at a task number specified in the task input widget
StepTaskContinues and stops at a selected task in the task list
FinishPassFinishes the current optimization pass
FinishFinishes all optimization passes




View menu.png


ToolbarShows or hides the toolbar
Status BarShows or hides the status bar



Window menu.png



CascadeArranges sub-windows so that they overlap
TileArranges sub-windows so that there are no overlapping tiles



Help menu.png



Help TopicsOpens the help topics, but is currently unavailable
About sqldbg...Shows the version of the debugger




The toolbar displays icons for frequently used functionalities. It appears as follows:




SQL Query Viewer


The SQL Query Viewer, which is the default sub-window inside the parent window, shows relational expression tree of the debugged query. You cannot close that sub-window.


Title of the sub-window indicates the current phase.


The SQL Query Viewer window displays these columns:


SQL Query TreeRelational expression node name
CostPlease provide a description.
Operator CostsPlease provide a description.
RowsPlease provide a description.
Expr TypePlease provide a description.



SQL Query Viewer.png

Right-clicking each node pops up a context menu with these options:


ItemExpr...Displays the item expression tree associated with the selected relational expression in a new subwindow
Properties...Displays the properties of the selected relational expression
UpdateMemo...Updates the information in a memo view


Item Expression Viewer


To open the Item Expression Viewer, select ItemExpr... in popup menu or click ItemExpr icon.png.


The Item Expression Viewer displays these columns:


Item ExpressionItem expression node name
Value IDPlease provide a description.
TypePlease provide a description.



Item Expression Viewer.png

Property Browser


To open the Property Browser, select Properties... from context menu.


Property names are highlighted with a gray background. Each property is separated with the next property by "----------end----------" notation.


Select or clear the check boxes to show or hide properties, 

Property Browser.png



Memo Viewer


The optimization process begins after the normalization phase and currently has two passes. You can use the Memo Viewer to step through the optimization process, and use toolbar icons or menu options to single-step or set breakpoints at specific groups, expressions, tasks, task numbers.


The Memo Viewer appears below the SQL Query Viewer. To show or hide the Memo Viewer, click the M icon.png.


The Memo Viewer has three panels:




Memo Viewer.png

Memo Grid


The Memo Grid provides visualization of memo (a global object). Cells in the grid represent physical or logical expressions or plans. Each row has its own group ID. The first column of every row is a group type, not an expression.


To the right of the Memo Grid are the GroupExpr, and Task settings. As optimization steps forward, the contents of the Memo Grid, Task List, and Context List are updated, as well as those three settings. Sometimes, Expr6.png diplays -1, which means that the current task does not work on any expression or plan of the current group.


When you click a cell in the Memo Grid, the following events are triggerd:


  • The SQL Query Viewer displays the tree of the selected expression.
  • The Task List is not affected.
  • The Context List displays the contexts of the current group.
  • If the cell is a plan, the plan's context will be marked green in the Context List.



Memo Grid.png

Task List



Task List.png

Context List


The Context List displays the contexts associated with the currently selected group. When you select a plan in the Memo Grid, its context icon will be marked green. If you select a context in the Context List, its solution (if any) will be marked in the Memo Grid. At most, only one cell can be marked with a solution at a time.



Context List.png

Update Memo


To update the memo, right-click a node in the SQL Query Viewer and click the UpdateMemo option in popup menu. The debugger updates the Memo Grid and its input widgets according to the group and expression number of the selected node, and it also updates the Context List according to the group.


Memo Toolbar Options

Memo options.png



Forward icon.pngAdvances to the next optimization task and updates all the memo panels.
Task num icon.pngStops at the task number specified in the Task setting.
Task icon.pngAfter selecting a task in the Task List, click this button to start and stop optimization at the selected task.
Group num icon.pngGoes to and stops at the group number specified in the Group setting, ignoring the Expr setting.
Stop icon.pngStops at the expression specified by the Group and Expr settings.

Note: Sometimes the value in Expr is -1 because no expression or plan is being processed for the current task. In that case, the debugger will stop at any expression of the specified group number. This is what happens when you click the Group num icon.png button.

Finish current pass icon.pngFinishes the current optimization pass. The Yellow finish current icon.png button does the same thing.
Finish all icon.pngFinishes all optimization passes.


Note: For the best results, you should run a query more than once to gather information about its maximum task number, group number, and expression number.


Grid Legend


The legend at the bottom of the window identifies what each symbol in the Memo Grid means.

Grid legend.png



TDB Tree Viewer


The debugger also displays the TDB tree generated by the compiler.



TDB Tree Viewer.png

The TDB Tree Viewer displays these columns:


TDB DisplayTDB node name
ExpressionsPlease provide a description.
MDAM DisjunctsPlease provide a description.


To view the list of expressions associated with a TDB node, click the appropriate expression column.



TDB expressions.png

The expressions window displays these columns:


ExpressionPlease provide a description.
TypePlease provide a description.
ClausesPlease provide a description.
Ver.Please provide a description.
FlagPlease provide a description.
Len.Please provide a description.