Documentation

Documentation Table Access Protocol (TAP)

Table Access Protocol (TAP)

The CADC provides QUERY access to our databases via TAP-1.0. This services enables users to POST database queries over HTTP and retrieve responses in CSV, TSV or VOTable formats. The TOPCAT client is an excellent tool for TAP service interaction.

Example

To query for all observations that intersect a circle and are calibrated or advanced products a Query is submitted via the following URL:

http://www.cadc-ccda.hia-iha.nrc-cnrc.gc.ca/tap/sync?REQUEST=doQuery&LANG=ADQL&QUERY=SELECT * FROM caom2.Observation AS o JOIN caom2.Plane AS p ON o.obsID=p.obsID WHERE INTERSECTS(p.position_bounds, CIRCLE('ICRS', 180, 5, 2)) = 1 AND p.calibrationLevel >= 1

Here is a clickable link that will execute the query and download the result to your browser.

The ADQL tab of the CADC Advanced Search page provides the exact ADQL that was used for your search query. Examining in the 'ADQL' tab is a good way to become familar with the CADC CAOM2 database tables.

Downloading Data

One of the columns in our caom2.Plane table is the planeURI. This URI can be used to download the the files associated wiht the plane using a URL constrcuted following this pattern: http://www.cadc-ccda.hia-iha.nrc-cnrc.gc.ca/caom2obs/auth-pkg?ID=${planeURI} where ${planeURI} is the value from the planeURI column returned by your query. Note that this URL will require authentication to access as some data is proprietary.

Example

Below is a BASH script that will download all the observations associated with a given proposal_id 13BF10

#!/bin/bash
export proposal_id=13BF10
export tap_url=http://www.cadc-ccda.hia-iha.nrc-cnrc.gc.ca/tap/auth-sync
export download_url=http://www.cadc-ccda.hia-iha.nrc-cnrc.gc.ca/caom2ops/auth-pkg
export USERNAME=john_doe
export PASSWORD=secret
export REQUEST=doQuery
export LANG=ADQL
export FORMAT=CSV
export QUERY=select+planeURI+from+caom2.Observation+as+o+JOIN+caom2.Plane+as+p+on+o.obsID%3Dp.obsID+where+o.proposal_id=\'${proposal_id}\'
for planeURI in `curl -u ${USERNAME}:${PASSWORD} "${tap_url}?REQUEST=${REQUEST}&LANG=${LANG}&FORMAT=${FORMAT}&QUERY=${QUERY}"`
do
curl -u ${USERNAME}:${PASSWORD} -J -O -L "${download_url}?ID=${planeURI}"
done

Proprietary Metadata

Some of metadata content in the caom2.Plane table is proprietary. To see prioprietary records, use auth-sync instead of sync in the above URLs and provid a username+password.

Unsupported ADQL Constructs

The following ADQL Functions are not currently supported: ALL and DISTINCT within an aggragate function (AVG, COuNT, MIN, MAX, COUNT) PI RAND TRUNCATE

Details

The main use of our TAP serivce is to explore our observational catalogue. Metadata for all the observations stored within the CADC are provided via the Common Archive Observation Model (CAOM-2.0) database. The tables in the CAOM2 database can be queried via the TAP service. The main tables are:

  • caom2.Observation: this table lists observations (individual exposures or stacks of exposures).
  • caom2.Plane: this table lists individual data products constructed from a particular observation, such as a RAW image, a PROCessed image or a catalog of sources.

To use the TAP service one constructs an ADQL query and posts that query to a TAP URL. This is most easily done using tools like TOPCAT but can also be done directly using tools like cURL. The TAP URLs are:

resourcedescription
http://www.cadc-ccda.hia-iha.nrc-cnrc.gc.ca/tap/async asychronous queries, the VOSpace destination where the result will be written is returned.
http://www.cadc-ccda.hia-iha.nrc-cnrc.gc.ca/tap/sync sychronous queries, result of query is returned.

Other views on our collection

In addition to the CAOM2 database, this service also provides views of our meta-data collection that follow various IVOA table standards:

  • caom.SIAv1: a view on CAOM2 that provides access to calibrated images; VOTable output is compatible with the Simple Image Access (SIA) version 1.0 specification
  • ivoa.ObsCore: a prototype implementation of the ObsCore physical model from the ObsTap project

More Examples (w/ Queries)

Here are some examples of queries (with the minimal requied parameters) that should work and return a modest number of results. Note that the QUERY itself must be properly encoded since it has spaces and other special characters. These queries can be executed via the /caom/async or the /caom/sync endpoints; details on how to do that are given in the UWS and TAP specifications. We include some live URLs below that use the /caom/sync endpoint.

Query SIA view for observations that contain a location:

REQUEST=doQuery
LANG=ADQL
QUERY=select * from caom2.SIAv1
      where CONTAINS(POINT('ICRS', 180, 5), position_bounds) = 1

Try It!

Query ObsCore view for observations that intersect a circle:

REQUEST=doQuery
LANG=ADQL
QUERY=select * from ivoa.ObsCore
      where INTERSECTS(s_region, CIRCLE('ICRS', 180, 5, 2)) = 1

Try It!

Query that refers to a non-existent column and table and should fail:

REQUEST=doQuery
LANG=ADQL
QUERY=select noSuchColumn from noSuchTable

Try It!