Reminder

Definition TAP is a Web-Service to read data

The table access protocol (TAP) defines a service protocol for accessing general table data, including astronomical catalogs as well as general database tables. Access is provided for both database and table metadata as well as for actual table data.
IVOA Recommendation 2012 March 27 - v1.0

Here are the main key-ideas to keep in mind about TAP:

Resources TAP is a set of 5 resources

The IVOA defines 3 mandatory plus 2 optional resources for TAP. Among the mandatory ones, 2 let execute an interrogation query whereas the 3rd describes the capabilities of the service. Then the optional resources provide an indication of whether the service is available and of what are the queriable tables and columns.

Since TAP is defined as a Web-Service, these resources, if available, must be accessed thanks to a URI. Here are these URIs and a short description of each resource ( * = mandatory):

/
Root of a TAP service

No usage is defined by the IVOA for this URI. This resource is totaly free of implementation.

Not implemented?
If not implemented, a request to this URI should return an HTTP-404 error (not found).

/sync *
To execute a synchronous query

The result of a synchronous query is returned immediately when the query execution ends.

For fast-queries
It is recommended to use this resource only for fast queries.
If you have any doubt about the execution time of your query, you should think of using the asynchronous execution mode.

/async *
To execute an asynchronous query

The query is submitted in the same way as the synchronous mode, but the result is not returned in the HTTP response. Actually, this response is a redirection to a description of the query execution task. In this description, the main information are the status of the execution (EXECUTING, ERROR, COMPLETED, ...) and the link toward the result. Once the execution finished (status=COMPLETED), the result can be fetched using the provided result link.

For long-queries
On the contrary to the synchronous mode, this one should be used to execute long queries.
Stored results
In this execution mode, queries and their results are kept for a while (this time depends of the implementation). Thus, you can access your result(s) whenever you want and more than once.
User identification

A TAP service may allow authentication. It is particularly useful if you want to prevent anybody else to access your queries (and their result(s)). Of course, that means you must login before creating an asynchronous query ; otherwise, your query will not be associated with your account.

/capabilities *
To get a description of the service

This is a VOSI resource which lets declare the capabilities of a VO service. With it, it is particularly possible to register a TAP service in a VO Registry.

Examples:
Here are some possible capabilities for a TAP service:
  • language (at least ADQL)
  • output format (at least: VOTable)
  • retention period (how long an asynchronous query/job leaves on the server)
  • execution duration (default and maximum execution period for any query)
  • ...

/tables
To list all queriable tables and columns

Another VOSI resource which, this time, lets list schemas, tables and columns that can be used in any ADQL query. This is particularly useful for TAP clients (like TOPCAT) which are then able to discover a TAP service and to provide an helpful interface to write ADQL queries.

Other metadata
In addition of the table and column names, other information are also available: UCD, UType, unit, primary and foreign keys, indexed columns, ...

/availability
To know whether the service is available

This VOSI resource contains only one information: a boolean value indicating whether the TAP service is working or not. A note may give more information about the un- or availability of the service.

Requests How to query a TAP service ?

Query execution

As said just above, TAP provides two resources able to execute a query over the data. For both of these resources, queries must be submitted using an HTTP-POST request with some parameters (described below). These parameters are the same whatever is the resource. However, the way to get the result differs:

UWS
/async is actually another IVOA Web-Service: UWS. The TAP library published on this website includes another library, of the same author, for UWS. So you can get more information about UWS on the website dedicated to this other library (http://cdsportal.u-strasbg.fr/uwstuto) and particularly on its reminder part. Besides, there is a didactic demo that lets you understand the URIs building in function of the information you want to get.

Query parameters

Name Required? Possible values Requirements Description
VERSION No "1.0" Version of the TAP protocol to use.
REQUEST Yes "doQuery" or "getCapabilities" If "doQuery": LANG, QUERY, OUTPUT Specify the request to execute and so, how the other parameters must be interpreted.
LANG Yes, if REQUEST="doQuery" "ADQL", "PQL", ... REQUEST="doQuery", QUERY Specify the language of the submitted query. At least ADQL must exist in all TAP implementations.
QUERY Yes, if REQUEST="doQuery" "doQuery" or "getCapabilities" REQUEST="doQuery", LANG The interrogation query to execute. It must be written in the language specified by LANG.
RUNID No Tag a set of queries. In other words it is a tag which lets gather several queries in a same group. It may be particularly useful when a portal is sending several queries to complete a big request ; all the queries would then have the same RUNID (but different JobIDs). But of course, it may also be used merely to set a more human-readable "ID"/alias/name to jobs.
FORMAT No "votable" or "text/xml", "csv", "tsv", "fits", "text", "html", ... It must be one of the MIME types or of the short forms declared in capabilities. By default, only VOTable must be declared. Specify the format of the query result. By default all TAP implementations must provide at least a VOTable output.
MAXREC No "0", "5", "100", "1000", ... integer ≥ 0 Specify the maximum number of rows in the query result. If more rows are available, the result is truncated (with a commented flag OVERFLOW in the result document). The special value 0, means that only metadata must be returned. In this case the query may not be executed.
UPLOAD No "table_a,http://...;table_b,param:table2", ... The service must allow uploads ; this information is provided by the resource /capabilities. Specify a set of tables to upload and required to execute the given ADQL query. A table of this list may be accessed from a URL or from a parameter (only if given in an HTTP multipart request).

Informative requests

The 3 other resources (/capabilities, /tables and /availability) are supposed to provide a document in answer to a simple HTTP-GET request. No parameter is expected there, however it is up to TAP implementors to allow other HTTP method or to add extra parameters. The HTTP-GET request is the only requirement of TAP for the 3 non-queriable resources.