Next Previous Up Contents
Next: Running Jobs tab
Up: Table Access Protocol (TAP) Query
Previous: Select Service tab
TAP window with Enter Query tab visible
The Enter Query tab of the TAP load dialogue
displays information about the service you have selected to query,
principally what tables are available and what columns they have,
and allows you to enter the query text and some additional options
about how the query is to be executed.
The panel has three parts:
Table Metadata,
Service Capabilities, and
ADQL Text.
The Table Metadata panel displays information about
the tables held by the selected service.
When the panel is first displayed the service is contacted to obtain
this information, and a progress bar will appear until it has arrived.
If the service does not provide it in an appropriate form, nothing
can be shown; it's still possible to submit a query, but you'll need
some other way of knowing what tables and columns are available.
Once the metadata has loaded, the following information will be
available:
-
Service
- The service URL selected in the Select Service tab.
It also notes the number of tables available from this service.
-
Table
- This selector contains an entry for each table contained in the
remote database. There may be just one, or there may be hundreds.
When you select one, information about it is displayed below.
An expanded title or description may also be displayed next to the
selector - hovering over this description with the mouse
may provide further detail in a tool tip.
-
Columns
- Tabulates metadata about each of the columns in the remote
table selected in the Table selector above.
Column names, types, descriptions, UCDs etc are shown.
Columns which are known to be indexed within the remote database
have the "Indexed" column ticked; this may help to to formulate
efficient queries.
-
Foreign Keys
- If the service provides information about foreign keys
(links between fields in different tables in the database)
they will be tabulated here. They may help you to formulate
efficient queries.
The Service Capabilities panel shows capability
metadata that the service provides about itself; again, this has to
be loaded from the server and may not appear immediately.
It contains the following information:
-
Query Language
- Shows what query languages, and what versions, are available.
If there is more than one listed, you can choose which language
you want to submit your query in, but if you choose something
which is not a variant of ADQL it may not work.
-
Max Rows
- Selector which shows the maximum number of output rows
that the service is
willing to deliver as the result of a query under normal circumstances.
Entries in this list value may be marked "(default)" or "(max)".
You can change this value by typing in a different number, as long as
it does not exceed the server's maximum.
This value is here to protect the user, as well as the service, from
inadvertently requesting an unduly large output table.
Note that if the construction "
TOP nnn
" is used in the ADQL,
the nnn
limit may override the value supplied here.
-
Uploads
- Indicates if table uploads are permitted, and perhaps what is the
largest upload size (in terms of rows and/or bytes) which will be
accepted.
See below for more about table uploads.
The ADQL Text panel is where you can enter the actual
query text for the request.
It has the following parts:
-
Synchronous checkbox
- Determines whether your job will be executed on the server in
synchronous or asychronous mode (check the box for synchronous).
Synchronous means that TOPCAT sends the query to the server and
waits for the result as the response of the same HTTP request.
It's simpler and faster, but if the job takes a long time,
the request may time out and the results be lost.
In asynchronous mode TOPCAT sends the query to the server and gets
a message back telling it where to look for information about the
job's progress; TOPCAT then keeps polling the server to find out
when it has completed.
Synchronous is suitable for short jobs (it may typically execute
with a few seconds less delay), but for longer jobs aysnchronous is
more reliable. It is possible to submit an asynchronous job
on one day from one machine, and pick up the results on a different
day from another machine, using another invocation of TOPCAT or of
a different application altogther.
-
Examples button
- This button presents you with a short menu of example queries.
These are tailored to the table metadata obtained for this service,
and, where appropriate, to the table currently selected by the
Table selector and/or the table list in the Control Window,
so they should in most cases be runnable as they stand
(though there is no guarantee they will produce useful results).
A better idea though is to use them as starting points for your
own queries. By picking one which is something like what you want
to do, you can hopefully work out the syntax for the query you need
without having to read the ADQL specification.
Some of the options in the list may be disabled,
depending on what capabilities the service has declared.
In some cases, especially ones using geometric functions, the
service may reject the example, since TOPCAT can't always tell
which functions are supported by the server.
-
Clear button
- Clicking this button clears any text currently shown in the
text entry field.
-
Parse Errors button
- If a syntax error is detected in the entered ADQL text, it
will be highlighted in the text field, and this button will be
enabled. Clicking this button will show a popup window with
more detail on the error.
-
Text entry field
- This is where you enter the text of the ADQL query you wish to make.
The syntax of ADQL (Astronomical Data Query Language) is defined by an
IVOA Recommendation;
it is effectively a dialect of SQL, but a good way to write a query
is to start with one of the examples from the Examples
button above.
If any errors are detected in the syntax of the ADQL as entered,
they are highlighted in pink as in the figure above.
Some services permit Table Uploads
(at time of writing only the GAVO service implements this capability,
but hopefully more will do so in future).
What this means is that you can upload tables from TOPCAT into the
remote database and perform queries on your table directly.
In this way you can perform joins between your own tables
(anything loaded into TOPCAT) and any of the tables in the remote
database. This is extremely powerful feature.
To take advantage of it, you just need to use a special form for
the table name to reference a TOPCAT-based table:
you write "TAP_UPLOAD.t<n>
", where
<n>
is the ID number of the table in TOPCAT,
that is the number before the colon in the
Control Window Table List.
So, if a table identified as "1: messier.xml
"
in the table list, you can reference it in ADQL as
"TAP_UPLOAD.t1
".
Note the table uploaded in this way is the
Apparent Table corresponding to the
given ID number.
As you enter the query text, it will be checked for syntax errors.
If an error is found, the place in the text which appears to have caused it
will be highlighted in pink (as in the figure above).
To see more detail on the error, click the Parse Errors button.
The checking itself is reasonably reliable, but the position of the
highlighted error, and the text of the error message, can sometimes
be a bit misleading, so don't take the details too seriously.
The error highlighting is just used as a warning, you are not prevented
from submitting a query marked as erroneous, since
in some cases TAP services may accept ADQL which is not strictly correct,
and in some cases the error checking may not be perfect.
Having entered suitable query text,
click the OK button at the bottom of the window
to submit the job. When you do this, one of two things will happen.
In synchronous mode, the Load Window will appear,
and the progress will indicate when loading is complete in the normal way.
In asynchronous mode, you will be taken to the
Running Jobs tab
where you can see the progress of your submitted job.
Next Previous Up Contents
Next: Running Jobs tab
Up: Table Access Protocol (TAP) Query
Previous: Select Service tab
TOPCAT - Tool for OPerations on Catalogues And Tables
Starlink User Note253
TOPCAT web page:
http://www.starlink.ac.uk/topcat/
Author email:
m.b.taylor@bristol.ac.uk
Mailing list:
topcat-user@bristol.ac.uk