TAP and ADQL, just enough

Two acronyms run under everything in this package. You do not need to master them — but it helps to know what they are and the one place they peek through.

TAP is the plumbing

TAP (Table Access Protocol) is the IVOA standard for querying astronomical tables over HTTP. The archive exposes its holdings as TAP tables, and this package speaks TAP for you — so you call query_* methods instead of building HTTP requests by hand. You mainly meet the name in two places: the sync-vs-async distinction below, and TAP_SCHEMA, the server’s self-description that describe_table reads to list the real columns, units, and descriptions of a table.

ADQL is the query language

ADQL (Astronomical Data Query Language) is SQL for astronomy, with extra geometry functions for cone searches. The high-level methods build ADQL for you from your arguments, so most users never write a line of it.

You only meet ADQL directly in two ways:

  • a where (ADQL fragment) string ANDed onto a high-level query (e.g. where='extsnr > 200'), or

  • the query_adql escape hatch, where you write the whole query.

Warning

When you do write ADQL yourself, two server quirks bite:

  • Dates must use Oracle to_date('YYYY-MM-DD HH24:MI:SS', ...); a bare string comparison fails. (The high-level methods handle this for you.)

  • Table names are spelling- and case-sensitive; a misspelled table returns a “table or view does not exist” error. Each archive’s page lists its table names and any spelling traps (for example, EXPRES’s expressolarl1).

Sync versus async

A normal query_* call is synchronous: it sends the query and waits for the rows, returning them immediately. That is ideal for bounded queries — keep them small with maxrec while exploring.

For a query too large or slow to return in one shot, run it asynchronously: the server queues it and works in the background while you poll an async TAP job (AsyncJob). You submit with submit_async(), watch its job phase, then collect the full astropy Table with .result().

For mapping a question to a method, see Choosing a query.