Comparing ensure_table, add_table, and queue_table in a Views handler

I wanted to briefly describe the difference between these three various methods used inside of the query method within a custom views handler class.  ensure_table, add_table, and queue_table all add tables to the query being constructed.  Though how is is accomplished varies.  Typically using ensure_table is the best way to go, especially if you don't know the difference.  It is the safest and it's pretty hard to screw something up using this method.  But as you need to do more complicated joins the other methods become necessary.

ensure_table checks a few different things to make sure it doesn't add the table needlessly, or break anything.  First it checks to see if the table already exists on the query, this is unique to ensure_table.  If the table has not already been joined it then ensures the path of the table.  Meaning that it checks the views_data structure to see if there is a "path" from the base table of the view to your proposed table.  This is the most restrictive because it relies upon a defined set of data that maps tables to one another.  In most cases this is something that is defined by the module creating the new table.  But if you are creating a custom table for one time use it might be overkill to define the whole view structure.  After ensuring the path the ensure_table method will call queue_table which I will describe later.  Using ensure_table will NOT work if you are joining to the same table multiple times.

add_table like ensure table calls both ensure_path and if successful calls queue_table.  This is what you need to use if you want multiple joins to the same table.

Lastly, queue_table, the function called by both of the previous methods can be called directly.  This will NOT ensure the path, which, if your using custom tables or an obscure module the mapping view data may not be available requiring you to just force the table into the query.  Of course this comes with a disclaimer... you can break your views pretty good just using the queue_table, and you don't want to use this you plan on re-using your custom module or contributing it.

For most of you, who are just skimming this article, the following diagram gives a quick view of how these functions add tables to a query.