TAP Access via tap.data.lsdb.io

TAP Access via tap.data.lsdb.io#

tap.data.lsdb.io is an experimental implementation of the Table Access Protocol (TAP), an IVOA standard for querying astronomical catalogs using ADQL (Astronomical Data Query Language).

Warning

This service is experimental. Not all ADQL features are supported, and behavior may change. If you run into problems, please open an issue or contact the LINCC Frameworks team.

How It Works#

Queries submitted to tap.data.lsdb.io are handled by hats-tap, an open-source Python package that acts as a TAP-compatible server for HATS/LSDB catalogs.

When a query arrives, hats-tap:

  1. Parses the ADQL query using queryparser.

  2. Translates it into an equivalent sequence of LSDB Python calls (eg, mapping a cone search to lsdb.ConeSearch and column filters to catalog.query()).

  3. Executes the translated query against the HATS catalogs hosted at data.lsdb.io.

  4. Returns results in VOTable format, compatible with tools like TOPCAT and PyVO.

Endpoints#

The service exposes the following endpoints:

  • GET/POST /sync: submit a synchronous ADQL query

  • GET /tables: list available catalogs and their columns

  • GET /capabilities: service metadata following the TAP standard

Example Query#

Submit a query using curl:

curl -X POST https://tap.data.lsdb.io/sync \
  -d "REQUEST=doQuery" \
  -d "LANG=ADQL" \
  -d "QUERY=SELECT TOP 10 ra, dec, mean_mag_g, mean_mag_r, mean_mag_i \
               FROM ztf_dr14 \
               WHERE mean_mag_r < 20"

Or from Python using PyVO:

import pyvo
service = pyvo.dal.TAPService("https://tap.data.lsdb.io")
results = service.search("""
    SELECT TOP 15
        source_id, ra, dec, phot_g_mean_mag
    FROM gaia_dr3.gaia
    WHERE 1 = CONTAINS(
        POINT('ICRS', ra, dec),
        CIRCLE('ICRS', 270.0, 23.0, 0.25)
    )
    AND phot_g_mean_mag < 16
""")
results.to_table()

Supported ADQL Features#

The following ADQL constructs are currently translated and executed:

Column selection

Explicit column lists in the SELECT clause are supported.

SELECT ra, dec, phot_g_mean_mag FROM gaia_dr3.gaia
Result limiting

The TOP keyword limits the number of returned rows.

SELECT TOP 100 ra, dec FROM ztf_dr14
Row filtering

WHERE clauses with comparison operators (<, >, <=, >=, =) and multiple conditions combined with AND are supported.

SELECT ra, dec FROM ztf_dr14 WHERE mean_mag_r < 20 AND nepochs > 5
Cone search

Spatial filtering using CONTAINS with POINT and CIRCLE is translated to lsdb.ConeSearch. Only one CONTAINS clause per query is supported.

SELECT ra, dec FROM gaia_dr3.gaia
WHERE 1 = CONTAINS(
    POINT('ICRS', ra, dec),
    CIRCLE('ICRS', 270.0, 23.0, 0.25)
)
Polygon search

CONTAINS with POINT and POLYGON is translated to lsdb.PolygonSearch.

SELECT ra, dec FROM ztf_dr22
WHERE CONTAINS(
    POINT('ICRS', ra, dec),
    POLYGON('ICRS', 280.0, 30.0, 281.0, 30.0, 281.0, 29.0, 279.0, 27.0)
) = 1
Ordering

ORDER BY is supported for sorting results.

SELECT ra, dec FROM ztf_dr22
WHERE CONTAINS(POINT('ICRS', ra, dec), CIRCLE('ICRS', 280.0, 0.0, 0.1)) = 1
ORDER BY ra, dec DESC

Not Yet Supported#

The following ADQL features are recognized by the standard but are not yet implemented. Queries using them will return an error.

  • SELECT * - wildcard column selection is not supported; column names must be listed explicitly (issue #22).

  • BETWEEN - range predicates (col BETWEEN a AND b) are not yet translated (issue #17).

  • Arithmetic expressions - computed columns or filter values involving arithmetic (e.g. ra + 10) are not supported (issue #10).

  • Aggregation functions - COUNT, MIN, MAX, SUM, AVG, and similar aggregate functions are not yet implemented (issue #20).

  • COUNT(DISTINCT …) - unique-value counting is not supported (issue #19).

  • Multiple CONTAINS clauses - only a single spatial constraint per query is allowed.

  • DISTANCE function - computing the angular distance between two points (e.g. DISTANCE(POINT(...), POINT(...))) is not yet supported. Use CONTAINS/CIRCLE for proximity searches instead.

  • OR conditions - only AND-connected predicates in the WHERE clause are supported.

  • JOIN - multi-table joins are not yet translated (issue #16).

  • Subqueries - nested SELECT statements are not supported.

  • ID lookups (id_search) - queries that filter on a catalog’s primary ID column are not yet optimized via lsdb.id_search (issue #14).

  • Nearest-neighbor / self-join - crossmatch-style queries are not yet supported (issue #15).

Getting Help#

If a query fails or you encounter unexpected behavior, please open an issue on GitHub with the query you submitted and any error message you received.