Write an API usage doc: query examples, use cases

Hopefully it will eventually graduate into a more mature "intended and
supported use cases" document.