Next Previous Up Contents
Next: Select Service tab
Up: VO Data Access Windows
Previous: Multiple SSA Query
Table Access Protocol Window
The Table Access Protocol (TAP) load window can be opened using the
TAP Query button ()
in the Control Window's toolbar
or VO menu,
or the Load Window's toolbar.
It allows you to use the TAP protocol to
make freeform queries of remote database services
using an SQL-like language.
This is a powerful capability, giving you full access to
remote data holdings, and use of the
IVOA-endorsed TAP standard means that you can use
the same interface for many different remote datasets.
Using TAP is one of the more complicated things you can do in TOPCAT,
but it's well worth getting to grips with because of the
capabilities it gives you for customised access to all kinds of remote data.
In order to interrogate the remote database you will have to
write queries in Astronomical Data Query Language (ADQL).
ADQL is essentially a particular dialect of SQL,
so if you have used SQL before, you should be able to write ADQL queries.
A tutorial on writing ADQL/SQL is beyond the scope of this manual,
but the Use Service tab
provides a quick cheat sheet in the Hints tab
of the metadata panel,
and an Examples menu which
will give you a good start in using it.
There are introductions and tutorials elsewhere,
for instance at
http://docs.g-vo.org/adql (Markus Demleitner)
and in the documentation of some TAP service web pages.
Once your query is written, you can submit it in either
synchronous or asynchronous mode.
Synchronous queries begin to execute right away and should have a
relatively short runtime;
asynchronous queries are submitted to a server, run for a potentially
long time, and retrieve the result later.
The window is composed of four tabs, of which you can see one at a time
(some of these tabs themselves contain tabbed parts).
You will use two or three of them when submitting a TAP query.
Each tab is described in more detail in the following subsections,
but an overview of their operation is like this:
-
Select Service tab
- Chooses the TAP service you wish to query, either using a registry
search or by entering the service URL directly.
Once you have chosen a service you can move to the
Use Service tab.
-
Use Service tab
- Displays information about the service and the tables it holds,
and allows you to enter the text of the query and submit the job.
If the job is submitted synchronously, loading will begin directly,
but in the asynchronous case, you will move to the
Running Jobs tab.
-
Running Jobs tab
- Shows a list of the asynchronous query jobs you have submitted,
with details on their progress.
-
Resume Job tab
- Optionally allows you to resume an asynchronous query
started in some earlier session.
When you first visit this window, the Select Service
tab will be visible, and when an asynchronous query has been submitted the
Running Jobs tab will be visible.
If you want to submit another query to the same service,
or use a different service,
just select Use Service or
Select Service respectively,
by clicking on the appropriate tab at the top.
This window offers some menus additional to the standard
VO window menus:
-
TAP menu
- This contains some configuration options specific to Table Access
Protocol service interaction. It has the following sub-items:
-
Reload ()
- Reloads information displayed in the window from the server.
This may be updating job status information or reloading table
or service metadata; the exact behaviour depends on which tab
is currently visible.
-
Job Deletion submenu
- Allows you to choose when asynchronously submitted jobs will
by default be
deleted from the server. Once they are deleted they will no longer
be visible in the Running Jobs tab. If they are not
deleted in this way, they will stay on the server until they are
deleted according to the server's deletion policy. Choose one of
the available options:
-
On Completion:
deleted when it has completed with either success or error status
-
On Exit:
deleted when TOPCAT shuts down
-
Never:
not deleted (except according to server policy)
You can override these settings once a job has started
by using the controls at the bottom of the
Running Jobs tab.
The settings in this menu affect the default value of the
Delete On Exit checkbox.
If you want to resume
the job in a later session, you'll have to make sure that the
job is not deleted on completion or exit.
-
Metadata Acquisition submenu
- Controls how the application loads service metadata - information
about the tables and columns provided by the service.
The following options are available:
-
Auto:
make a sensible decision; this generally means
TAP_SCHEMA-C for services with very many tables,
and TableSet-VOSI1.1 otherwise.
-
TAP_SCHEMA-C:
reads metadata from TAP_SCHEMA tables;
all schemas, tables and foreign keys are read at once,
columns are read only when required.
-
TAP_SCHEMA-CF:
reads metadata from TAP_SCHEMA tables;
all schemas and tables are read at once,
columns and foreign keys are read only when required.
-
TAP_SCHEMA:
reads all metadata at once from the TAP_SCHEMA tables.
-
TableSet-VOSI1.1
Uses VOSI 1.1-style
detail
-sensitive requests
to the /tables
endpoint.
No detail
specification is made initially,
so the service decides whether up-front loading is done.
Still compatible with VOSI 1.0 services.
-
TableSet-VOSI1.1-1step
Uses VOSI 1.1-style
detail
-sensitive requests
to the /tables
endpoint.
detail=max
is specified initially to indicate that
full metadata up-front metadata load is preferred.
Still compatible with VOSI 1.0 services.
-
TableSet-VOSI1.1-2step
Uses VOSI 1.1-style
detail
-sensitive requests
to the /tables
endpoint.
detail=min
is specified initially to indicate that
on-demand column load is preferred.
Still compatible with VOSI 1.0 services.
-
TableSet-VOSI1.0:
reads the document at the
/tables
endpoint of
the TAP service as defined by VOSI 1.0;
all table metadata is loaded up front.
-
VizieR:
uses the 2-stage TableSet from
/tables
as implemented (at time of writing) by the TAPVizieR service;
columns are read only when required
(experimental, may be withdrawn).
You will usually want to stick with the default
value of Auto.
The main purpose of this menu is for TAP service implementers
or testers who want to experiment with different options.
However, if you're on a slow link, and it's taking a long time
to display any metadata for medium-sized services, you might want
to switch to TAP_SCHEMA-C/CF, or VizieR for talking to TAPVizier.
-
Response Format submenu
- Configures how the application requests that VOTable results
are to be returned. The options
(TABLEDATA,
BINARY,
BINARY2)
correspond to the different defined VOTable serialization formats.
The selected format is only actually requested if the service
has indicated support for it, otherwise the service default is used.
-
Upload Format submenu
- Configures how tables are transmitted to the service for upload
if an upload query
(one involving a
TAP_UPLOAD.*
table) is performed.
The options
(TABLEDATA,
BINARY,
BINARY2)
correspond to the different defined VOTable serialization formats.
The choice shouldn't affect any results, but it may affect
required bandwidth and some services may (though shouldn't)
have non-standard requirements for serialization format.
-
Service Discovery
- Configures how TOPCAT searches for available TAP services.
There are currently two options,
GloTS, which uses the Global TAP Schema
service list maintained by GAVO, and
Reg Prototype which uses a proposed convention
based on the IVOA Registry. You are advised to use the default
value (currently GloTS) unless you understand what you're doing here.
-
HTTP gzip
- If checked, this option sends
Accept-Encoding: gzip
headers with most of the HTTP requests when communicating with the
TAP service. That ought to reduce required bandwidth considerably,
but only if the service chooses to honour this request.
The setting should have no effect on the actual results,
but may affect performance.
-
Authentication menu
- Provides options concerned with logging in and out of TAP services.
-
Log In/Out ()
- Logs you in to the currently selected TAP service,
or logs you out if you are already logged in.
Only applies to services that have optional or mandatory
authentication.
This action is the same as the corresponding button in the
Use Service tab,
and it is documented in more detail there.
-
Reset Authentication ()
- Logs out of any external services that you have logged in to.
If you try to access these services again, you will either access
them anonymously or (in cases where authentication is mandatory)
be prompted to log in again.
-
Edit menu
- Provides options concerned with editing ADQL text.
This is only active when the
Use Service tab is visible, and it is described
in that section.
Note: TAP is a complex protocol, and at time of
writing, many TAP services still do not provide full and error-free
implementations. Unexpected behaviour may be a result of service
implementation deficiencies. Hopefully that will improve over time.
Next Previous Up Contents
Next: Select Service tab
Up: VO Data Access Windows
Previous: Multiple SSA Query
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@jiscmail.ac.uk