[enhancement] improved query builder methods and javadoc