TAP window with Use Service tab visible
The Use Service tab of the TAP load dialogue displays information about the service you have selected to query, including what tables are available and what columns they contain, 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: Metadata, Service Capabilities, and ADQL Text.
The Metadata panel displays information about the tables held by the selected service. On the left of the panel is a searchable tree summarising the schemas and tables in the service, and on the right are some tabs containing more detail. Note all this information has to be loaded from the server, so in some cases you may have to wait before it is visible.
The tree on the left contains a listing of the service's Schemas, and under them the Tables they contain. A Schema in this context is just a subject grouping that contains one or more tables. Each schema notes in brackets the number of tables it contains; you can reveal or hide the tables by clicking on the schema node's handle. If the service contains only a small number of tables it may be convenient just to scroll up and down to see them all. But for services with hundreds or thousands of tables, you may need to restrict the displayed tables to those you're interested in. To do this, type one or more search terms into the Keywords field. The nodes displayed in the tree will be filtered to include only those that match the search terms as you type them. The Name and Descrip checkboxes indicate whether you want your search terms to match tables/schemas by name and/or by description. The And/Or toggle button determines whether each displayed table/schema has to match all of the search terms or just one. So for instance if you want to list just two tables, you can type in both table full names, uncheck the Descrip control, and set the toggle button to "Or".
To the right of the tree is a tabbed panel giving detail relating to the currently selected tree node. Select a tree node by clicking on it. Each tab has a little circle next to the title which may be empty or filled, according to whether it contains information. If it's empty it's either because that information doesn't make sense for the selected node in the tree (e.g. if a schema is selected, there is no column information) or because the information has not been retrieved from the service; either it's on its way and will be filled in later, or there's an error. The tabs are as follows:
mag
click on the Unit column header.
If no table is selected in the tree, this tab will be empty.
The Service Capabilities panel shows capability metadata that the service provides about itself. This has to be loaded from the server and may not appear immediately. It contains the following information:
TOP nnn
" is used in the ADQL,
the nnn
limit may override the value supplied here.
The ADQL Text panel is where you can enter the actual query text for the request. It has the following parts:
SELECT COUNT(*) FROM table
);
the result of the query is the row count in a one-column, one-row table,
and there's not much point loading that table into TOPCAT.
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.
Note also that for various reasons the service may not be able to
accept all queries that count as syntactically valid ADQL,
so even if TOPCAT doesn't report any errors, the service may still
respond with an error message.
The Examples menu is divided into a number of sub-menus, though not all will be enabled for all services. The sub-menus are:
ivoa.obscore
table),
which describes astronomical observations in a standardised way.
You can use these to do things like search for all observations
at a particular sky position, or observation time, or waveband etc.
Only available if the service declares support for the ObsCore
data model.
rr
schema).
You can use these to do things like search for
all TAP services containing tables having columns with particular
physical meanings,
or all cone search services relating to particular wavebands, etc.
You can use queries like this to perform more sophisticated searches
for TAP services than you can do using the
Select Service tab.
Only available if the TAP service declares support for the RegTAP
data model (i.e. if it hosts an IVOA searchable registry).
When you select an example from one of the sub-menus, its name and title will be displayed to the right of the Examples button. Little left and right arrow buttons allow you to cycle through the examples in the current submenu so you can browse what's available.
Some examples come with additional explanation on the web.
If the example you're currently looking at has such additional
documentation then the Info button
to the right will be enabled, and clicking on that should open
the relevant page in a browser on your desktop.
Some TAP services permit Table Uploads.
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 an 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
" - see the Upload
sub-menu of the Examples menu described above for
some examples.
Note the table uploaded in this way is the
Apparent Table corresponding to the
given ID number, i.e. current subset and column selections apply.
It's a good idea to ensure that any table you are uploading has
columns with sensible names, otherwise the service may rename the
columns or otherwise have trouble handling it.
Having entered suitable query text, click the Run Query button at the bottom of the window to submit the job. What happens then depends on the Query Mode described above: in Synchronous mode, the Load Window will appear with a load progress indicator, and when it's done the table will be loaded into TOPCAT in the usual way. In Asynchronous mode, you will be taken to the Running Jobs tab where you can see the progress of your submitted job; when it's ready it will be loaded into TOPCAT. In Quick Look mode, a window will pop up to display the results when they are ready.