some notes for a less obscure api
simpler query api