Next Previous Up Contents
Next: Running Jobs tab
Up: Table Access Protocol (TAP) Query
Previous: Select Service tab

#### A.9.8.2 Enter Query 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