The Common Archive Observation Model (CAOM) TAP Service

This service implements the IVOA TAP-1.0 recommendation and exposes the Common Archive Observation Model (CAOM) content at CADC. The CAOM tables are all part of a schema called caom. The main tables are:

• caom.Observation: these are simple observations (the exposures taken at the telescope) or composite observations (a group of simple observations where a new data product has been or can be made, e.g. a stack of images) collected together in a single table (type = S or C)
• caom.Plane: a plane is one of the data products of an observation, including the raw data, the calibrated data (standard data reduction applied), advanced data products (non-standard processing), and source catalogues derived from the data

Following the TAP specification, we have implemented the following resources:

IVOA Data Models

In addition to the CAOM, this TAP service also provides access to some standard data models via the following database tables:

• caom.SIAv1: a view on CAOM 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

Downloading Data

The accessURL column in the caom.Plane table can be used to download the data. Note that some data is proprietary (caom.Plane.dataRelease is null or in the future); if you try to use the accessURL for proprietary data you will be challenged to authenticate and an authorization check will be performed. The download will be permitted (or not) depending on those checks.

There is also an accessURL column in the caom.SIAv1 and ivoa.ObsCore tables.

There is a previewURL column in the caom.Observation table. By default, this URL will return a modest-sized graphical representation of the observation, but may return an error code (404: Not Found) if there is no preview available.

Proprietary Metadata

Some of the observations and planes in CAOM have proprietary metadata (caom.Plane.metaRelease is null or in the future). For anonymous queries, the service will automatically restrict access to public metadata only. Experimental: users may authenticate using https and client-side X.509 certficate, in which case they will see both public metadata and proprietary metadata they are authorised to view.

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

Sample TAP Requests (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.

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

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

REQUEST=doQuery
LANG=ADQL
QUERY=select * from caom.Observation as o JOIN caom.Plane as p on o.obsID=p.obsID
      where INTERSECTS(position_bounds, CIRCLE('ICRS', 180, 5, 2)) = 1
        and observable_ctype in ('CAL', 'PROD')

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

Experimental PQL Support

PQL (Parameterised Query Language) is now supported but experimental; it does not follow any existing standard. To use PQL instead of ADQL as the query language, you must include LANG=PQL as a job parameter, plus 1 or more additional parameters defined below.

Allowed PQL parameters:

• TABLE: the value is a single table name as given in the TAP_SCHEMA or VOSI-tables output
• <column name>: the parameter name is a column name as given in the TAP_SCHEMA or VOSI-tables output, the value is a simple number or string and only equality conditions are currently implemented
• <utype>: the parameter name is a utype from a supported data model as given in the TAP_SCHEMA, the value is a simple string or number (as above)

The most general way to query is by using utype parameters from a data model. The service can find the appropriate tables and columns automatically and can even infer joins between tables if the foreign key relationship is described in the TAP_SCHEMA. For example, if the PQL parameters include utypes from the caom.Observation and caom.Plane tables, the correct join will be used to generate the query. It should be noted that the TAP_SCHEMA tables themselves, while described in the TAP_SCHEMA with all the appropriate foreign keys, cannot feasibly be used with our experimental PQL implementation (except with a single TABLE parameter) : they do not have utypes (yet) and column names are generally ambiguous because the same column names are used in multiple tables. We intend to add utypes taken from the VODataService specification to resolve this.

REQUEST=doQuery
LANG=PQL
obscore:DataID.collection=JCMT
obscore:Obs.dataProductType=spectrum

Note: We are currently working on expanding the capabilities of PQL, specificially in specifying values and other kinds of conditions.

RSS Support

The caller can ask for RSS output format instead of the default VOTable. A URL with FORMAT=rss and LANG=PQL and one or more PQL parameters is a valid RSS feed that can be subscribed to using a variety of clients. By default, RSS queries a limited to 10 rows (items).

REQUEST=doQuery
FORMAT=rss
LANG=PQL
TABLE=ivoa.ObsCore

REQUEST=doQuery
FORMAT=rss
LANG=PQL
obscore:Obs.calibLevel=2
obscore:Obs.dataProductType=image

REQUEST=doQuery
FORMAT=rss
LANG=PQL
caom:Plane.calibrationLevel=2
caom:Plane.energy.emBand=Optical
caom:Plane.dataProductType=image