ESO logo

ESO Tabular Access Protocol Query Examples


This page is encoded according to the DALI specifications, hence using the RDFa lite framework.

Querying the ESO TAP Server

Any query sent to the ESO TAP servers requires/allows the following:

List of ESO Supported Examples

What follows is a set of query examples which can be used as templates to develop your own queries.
The language used is the Astronomical Data Query Language (ADQL) of the Virtual Observatory.

Each example starts with a number and a title, continues with a descritpion of the use case at hand, provides the ADQL query, adds some further detail, lists the tables involved in the query, and finally presents the URL query string that can be used to query the TAP server. To be used, the provided URL query string must be concatenated to the URL end point of the ESO TAP service, which is: http://archive.eso.org/tap_obs/sync? for simple queries. Had you the intention to send more complex queries that would timeout using the previous endpoint, you could then use instead: http://archive.eso.org/tap_obs/async which execute queries in asynchronous mode

In case you encounter a problem with any of the provided examples, please contact us at: usd-help(at)eso.org with subject: ESO TAP SERVER, specifying the number of the example(s) you are referring to, and describing the issue you are having. Many thanks in advance for doing so.

  1. Which tables can I query within the ESOTAP server?
    The use case is as follows: I want to know the name and the description of all the tables that can be queried via this service.
    QUERY

    SELECT schema_name, table_name, description
    FROM TAP_SCHEMA.tables
    ORDER BY schema_name, table_name
    
    -- Further details:
    -- All TAP services must support a set of (meta) tables, in a schema named TAP_SCHEMA.
    -- These meta-tables describe all tables and columns published through the TAP service.
    -- The meta-tables can be queried themselves via TAP.
    -- Users can discover ESO-published tables or columns by querying the tables in this schema.

    ivo://ivoa.net/std/TAP/v1.1

    List of tables involved in the query: TAP_SCHEMA.tables

    REQUEST doQuery
    LANG ADQL
    URL query string:

  2. What are the column names of the ObsCore table?
    I am interested in reduced products; from the query before I see that the ivoa.ObsCore table offers them. What are the column names of the ivoa.ObsCore table?
    QUERY

    SELECT column_name, datatype, unit, ucd, utype
    from TAP_SCHEMA.columns
    where table_name='ivoa.ObsCore'
    
    -- The TAP_SCHEMA.columns table provides the column names, units,
    -- UCDs, description, etc., of all the published ESO tables.
    -- Please note that string values must be embraced in single quotes (e.g.: 'ivoa.ObsCore').
    -- Please note that the part of a line starting from 2 minus signs (--) onward is considered a comment and is therefore not part of the query.

    ivo://ivoa.net/std/TAP/v1.1

    List of tables involved in the query: ivoa.ObsCore

    REQUEST doQuery
    LANG ADQL
    URL query string:

  3. Query products by wavelength, sorting by declination
    Find products containing the 2.18 micron wavelength, closer than 15.5 degrees to the south pole (FK5 J2000). Limit the results to the first 200 records. Expected results: . Any spectrum, cube, or visibility, whose wavelengths extend below and above the 2.18 micron . Any image, source table, catalog, whose filter covers the 2.18 micron wavelength (i.e. the Ks-filter of all instruments, the BrGamma narrow-band filter of HAWKY), (see Helper: Characteristics of ESO filters below) . Only products whose declination is southern than -74.5 degrees (FK5 J2000) are considered. . ORDER BY: the results will be sorted by the declination in the default ascending order. . TOP 200: only the first 200 records (at maximum) of the result set will be returned, even if more results are available. . The TOP operator is applied to the query result set, that is, after the sorting has taken place; effectively, this means that only the first 200 closest products to the south pole are returned.
    QUERY

    SELECT TOP 200 target_name, instrument_name, dataproduct_type,
       em_min, em_max, em_res_power, obs_collection, dataproduct_subtype 
    FROM ivoa.ObsCore 
    WHERE em_min <= 2.18E-6 
      AND em_max >= 2.18E-6 
      AND s_dec < -74.5
    -- and em_res_power < 10 -- to exclude narrow-band filters like the Hawki-BrGamma
    ORDER BY s_dec
    -- The first 200 closest products to the south pole containing the 2.18 micron wavelength will be returned, sorted by ascending declination.
    -- The spatial reference system used by the Virtual Observatory is ICRS.

    ivo://ivoa.net/std/TAP/v1.1

    List of tables involved in the query: ivoa.ObsCore

    REQUEST doQuery
    LANG ADQL
    URL query string:

  4. Products of high resolving power contained in a cone around SN1987A
    Find products whose footprint is entirely contained in a cone of radius 100 arcsec around SN1987A with a spectral resolving power of at least 27,000.
    QUERY

    SELECT target_name, s_dec, s_ra, t_exptime, em_res_power, em_min, dataproduct_type, instrument_name,   
           3600.*distance(point('',s_ra, s_dec),point('',83.86675,-69.269741666)) as arcsec_from_SN1987A   
    FROM   ivoa.Obscore    
    WHERE  CONTAINS(s_region,CIRCLE('ICRS',83.86675,-69.269741666, 100./3600.)) = 1
                               -- a circle centered onto SN1987A, of radius=100 arcsec,
                               -- must contain the s_region, i.e. the footprint of the product
    and em_res_power > 27000             -- R (resolving power) > 27 000 
    order by arcsec_from_SN1987A         -- sorted (ascending) on the computed field called arcsec_from_SN1987A 
    
    -- The constraint CONTAINS(arg1, arg2)==1 ensures that arg2 contains arg1.
    -- In this case, the CIRCLE must contain the footprint of the product (s_region).
    -- All coordinates are expressed in decimal degrees, as it is also the radius of the CIRCLE.
    -- The spatial reference system is forcefully ICRS. You can NOT modify it;
    -- you can omit it, as done e.g. in POINT('', s_ra, s_dec).
    --
    -- By choice, the footprint of an ESO 1d spectrum is always a point.

    -- The s_region is the ObsCore field that stores the footprint of the product. -- All geometrical functions applied to sky coordinates require as first parameter the spatial reference system. -- Though, the VO requires it to be always ICRS, which is also the default value; for that reason one can omit it -- as for example done in the POINT('',s_ra, s_dec), or can be spelt out, as in CIRCLE('ICRS', 83.86675, -69.2697). -- For all practical usages of these data, ICRS and FK5 J2000 are indistinguishable.
    ivo://ivoa.net/std/TAP/v1.1

    List of tables involved in the query: ivoa.ObsCore

    REQUEST doQuery
    LANG ADQL
    URL query string:

  5. Products whose footprint contains a given point (e.g., cepheid RS PUPPIS)
    Find products containing the position of the cepheid RS PUPPIS Please note that this query cannot return spectra, which, in the ESO case, have a point-like footprint (s_region has area=0)!
    QUERY

    SELECT TOP 100 * FROM ivoa.Obscore 
    WHERE CONTAINS(POINT('ICRS',123.2675,-34.5785),s_region) = 1  -- footprint(the s_region field) must contain a given point
    
    -- The constraint CONTAINS(arg1, arg2)==1 ensures that arg2 contains arg1.
    -- In this case, the footprint (s_region) of a product must contain the point (RA,DEC)=(123.2675deg,-34.5785deg).
    --
    -- Please notice that this query cannot return any product whose s_region as an area of 0, which means that this query will not return any of the ESO spectra.

    ivo://ivoa.net/std/TAP/v1.1

    List of tables involved in the query: ivoa.ObsCore

    REQUEST doQuery
    LANG ADQL
    URL query string:

  6. 100 best spatially-resolved J, H, or Ks images intersecting a 5 deg cone around the Galactic Centre
    Find the imaging products (dataproduct_type='image') intersecting a cone of 5 degrees around the Galactic Centre (266.42,-29.0) extending the spectral axis over the central wavelengths of either J, H, or Ks photometric bands Sort results by the spatial resolution (from best to worse), and return only the first such 100 results.
    QUERY

    SELECT TOP 100 instrument_name, em_min, em_max, s_resolution, distance(point('',s_ra,s_dec),point('',266.42,-29.0)) as dist_from_GC, dataproduct_type 
     FROM ivoa.Obscore 
    WHERE dataproduct_type='image' 
     AND INTERSECTS(CIRCLE('ICRS',266.42,-29.0,5),s_region) = 1  -- intersecting (aka overlapping) a 5 deg cone around the Galactic Centre
     AND ((em_min < 1.25E-6 AND em_max > 1.25E-6)   -- Contains lambda(J) or
         OR (em_min < 1.65E-6 AND em_max > 1.65E-6) -- Contains lambda(H) or
         OR (em_min < 2.2E-6 AND em_max > 2.2E-6))  -- Contains lambda(Ks) 
     ORDER BY 4               -- 4 is the position of the s_resolution within the SELECT list
    
    -- INTERSECTS( arg1, arg2 ) is a function that return 1 if the two geographies arg1 and arg2 intersect in at least one point.
    -- ORDER BY accepts either a column name (e.g. s_resolution), or the position of the column in the SELECT list.
    -- ORDER BY dist_from_GC could have been used instead to return the 100 products closer to the Galactic Centre.

    ivo://ivoa.net/std/TAP/v1.1

    List of tables involved in the query: ivoa.ObsCore

    REQUEST doQuery
    LANG ADQL
    URL query string: