Ok ok, here's the deal. Queries are so important that they needed their own section. Calm down Dwight we'll handle that now. The site- query elements are incredibly powerful aspects of HAXcms theming that deserve their own section anyway.
"Give me all of the
Always. This is by far the most powerful element in our library. It can query the site structure and effectively return anything, anywhere that matches the criteria. It is for exact criteria matching though so you won't be getting children of page X unless you specifically requested them.
This is great for getting things like getting all the pages that don't have parents (top level items) which is exactly how the site-top-menu tag does it in conjunction with a dom-repeat tag (in that example).
A menu slice query is one which takes part of a hierarchy and chops it out to return the items.
The dynamic leveling flag would allow you to create a query that analyzes the current active item (as example). And then say "Always give me 2-3 levels below this". In that instance you've got a dynamic sub-set of children being returned.
This can be useful for a block that always shows the children of the current page in a documentation site.
A site render query attempts to standardize the practice of wiring site-query up to something visual. It requires you supply something visual to get going and has the unfortunate limitation though that what you render must not be dynamic in nature.
When you have a static set of items you want to query once and have it be dynamic based on site infrastructure yet not be changing dynamically during site view.
As we haven't rolled this into any themes at the time, this could be useful for placing a "latest posts" block or "upcoming events" block. Anything that's dynamic based on the data being passed in but yet unchanging once it's loaded. Think of this as a simple "views" construct if you are from the Drupal worldview.