Server specific examples

[Markus Demleitner]

Dear all,

If you attended the TAPRegExt session in Pune you may remember we
discussed how TAP servers could expose (commented) example queries to
users and clients in some "standard" way; my experience in watching
people use TOPCAT's TAP interface is that everyone starts with
examples and works on from there.  TAP clients should have a fair
chance of being able to display something tailored to a server's
contents.

In Pune we decided against having such a thing in TAPRegExt (and
hence including example queries in the capabilities endpoint).
Instead, we agreed I'd try a tap_schema.examples table.

I've done this now, and you can find it behind the access URL
http://dc.g-vo.org/tap (that's the service
ivo://org.gavo.dc/__system__/tap/run) or in HTML at

http://dc.zah.uni-heidelberg.de/__system__/adql/query/form?__nevow_form__=genForm&query=select%20*%20from%20tap_schema.examples&_TIMEOUT=5&_FORMAT=HTML&submit=Go

Now that I've done it, I have to say I don't partiularly like this
particular solution.

Firstly, I agree with (private) feedback from Mark Taylor:

> I think machine readable is good for me, and the way you've done it
> looks OK.  Having it in a TAP table is a bit heavy duty though.
> One issue is that a TAP query may be slow (e.g. queued behind all
> the other pending queries). [Issue 1]

(though I guess that's somewhat mitigated by queries against that
table always running through sync).

Then, I'd really like to have something that easily works as a simple
web resource that users can just point their browsers to -- I admit
you can get a similar effect doing a sync query with a stylesheet,
but again that feels rather heavyweight, and injecting the proper
stylesheet at the right time could be tricky.  [Issue 2]

One thing I had in mind in Pune was associating queries with tables;
in my examples, the katkat bibliography query, to name one, should be
prominently shown when people peruse the metadata of the
katkat.katkat table, whereas it's not so eminently useful for most
other tables.  One could do this in a new column within the
tap_schema.examples table, but since a single query could be
"pertaining" to multiple tables, it would be messy in one way or
another. [Issue 3]

Finally, when writing the descriptions, I found myself yearning for
markup (paragraphs, "literal" values, maybe even links).  I'm not
sure allowing something like that is a good idea, I'm just saying my
fingers ached for it. [Issue 4]


As to suggestions where to go, let me first quote Mark again:

> Since it's static data of moderate size an "/examples" endpoint would
> work better, but then somebody has to define an output format
> (could be VOTable just as you have it).

An /examples endpoint delivering a static VOTable, possibly more or
less what would come out of a TAP endpoint with the current table
structure would certainly solve issues 1 and 2 (for issue 2, it's
more straightforward to bind a pretty stylesheet tailored for the
examples to such a VOTable than it would be when pulling the document
out of a real TAP service).  Issue 3 could still be addressed if
desired, by introducing an additional column.

For issue 4, that wouldn't help (let's not even think about storing
some kind of markup, let alone HTML, within a VOTable).  If we wanted
this (and tackle issue 2 offensively), we could simply use xhtml plus
a microformat.  Standalone applications probably would not want to
display the whole example records (since they'd need to render HTML
for that), but it would be easy to get the sample queries and
relevant metadata (a name, the link for the explanation, and possibly
the tables the queries are "meant for") using either a proper XML
parser or just screen scraping.  What I have in mind could look like
this:

<div class="ivo_tap_example" id="katkatbib">
<h1 class="ivo_tap_examplename">Katkat Bibliography</h1>

<p>To search for title (or other) words in the source field of <abbr
class="ivo_tap_pertainingtable">katkat.katkat</abbr> use the
<tt>gavo_hasword</tt> locally defined function. This basically works
a bit like you'd expect from search engines: case-insensitive, and
oblivious to any context.</p>

<pre class="ivo_tap_examplequery">
SELECT * 
FROM katkat.katkat 
WHERE gavo_hasword('variable', source) 
  AND minEpoch<1900
</pre>
</div>

An application could render this as button "insert query 'Katkat
Bibliography'" with another button "More info" behind it; that
button could, e.g., just open a web browser for
http://foo.bar/tap/examples#katkatbib.


So -- what do you think?  Which of the issues posed above do you
regard as relevant?  Do you prefer a static endpoint or a tap_schema
table?  VOTable, microformatted HTML, or still something else if
static endpoint?  Or would you rather forget about the whole thing?
[For the last position, you'll probably have to try hard to convince
me...]


Cheers,

           Markus