add some commentary on query api