Accessing ALeRCE data: moving from direct database access to TAP

Moving from direct database access to the TAP service

Last updated: June 2026

ALeRCE is updating how users access our data. We are retiring direct (raw SQL) connections to the ALeRCE database and standardizing on our supported interfaces — most importantly the TAP service, which is the recommended replacement for anyone who used to query the database directly.

Your data is not going away — only the way you connect to the database directly is being phased out. TAP is already live, so you can start migrating today rather than waiting for any of the dates below.

Who is affected?

If you use… Impact Action
The ALeRCE website / Explorer None Nothing to do
The ALeRCE API (api.alerce.online) None Nothing to do
The ALeRCE Python client (alerce) None Keep your code; just stay on a recent version
Our example notebooks / tutorials (official versions) None TAP versions land in the repo in the next couple of days — use the latest version once available
A direct database connection (psql, psycopg2, SQLAlchemy, JDBC, etc. — including from your own notebooks) Affected Migrate to TAP (or the API / Python client) before direct access is removed

If you have a database host, port, username, and password that you use to run SQL against ALeRCE — including from inside a Jupyter notebook — this change applies to you.

Why we’re making this change

Direct database connections expose our internal schema, are difficult to keep stable and secure, and aren’t part of the standard astronomical data-access ecosystem. By moving everyone onto TAP and our other interfaces, we give you:

  • A stable, documented contract that won’t break when we evolve our internal storage.
  • Standard tooling — TAP works with TOPCAT, pyvo, astroquery, and any IVOA-compliant client.
  • The same expressive power you had with SQL, via ADQL (the astronomy SQL dialect), including cone searches and cross-matches.

The interfaces at a glance

Interface Best for Endpoint
Website / Explorer Interactive exploration, single-object lookups, visual inspection alerce.science
ALeRCE API Programmatic access to objects, detections, features, classifications api.alerce.online
Python client The easiest way to use the API from Python / notebooks pip install alerce
TAP service SQL-style (ADQL) queries, bulk selection, cross-matching, VO tools tap.alerce.online

If you were writing SQL directly, TAP is your destination. If your queries are object/feature lookups, the API or Python client may be even simpler.

What is TAP?

TAP (Table Access Protocol) is the IVOA standard for querying astronomical tables over the web. You write queries in ADQL, a SQL dialect with extra astronomy functions (cone searches, region queries, etc.). Because it’s a community standard, you can use it from:

  • TOPCAT — point-and-click table access and visualization.
  • pyvo — the standard Python VO library.
  • astroquery.utils.tap — if you already use Astroquery.
  • Any other IVOA TAP-compliant client.

The TAP service is live today — you can connect and start migrating right now, before any of the dates below. Both the multisurvey database and ZTF-legacy are served through it, so everything you can reach through a direct connection you can reach through TAP:

  • alerce_tap schema → the multisurvey catalog (e.g. alerce_tap.object, alerce_tap.detection, alerce_tap.probability, alerce_tap.feature).
  • ztf schema → ZTF-legacy (e.g. ztf.object, ztf.detection, ztf.forced_photometry, ztf.magstat).

For connection instructions — including the exact TAP service URL and details for each client — see tap.alerce.online, which also lets you browse every available table and column.

Connecting with pyvo

import pyvo

# ALeRCE TAP service
tap = pyvo.dal.TAPService("https://tap.alerce.online/tap")

# Browse the available tables and columns
for t in tap.tables:
    print(t.name)

# Run an ADQL query against the multisurvey catalog
job = tap.search("SELECT TOP 10 oid, meanra, meandec, n_det FROM alerce_tap.object")
results = job.to_table()   # an astropy Table

Connecting with TOPCAT

  1. Open TOPCAT → VO → Table Access Protocol (TAP) Query.
  2. Enter the service URL: https://tap.alerce.online/tap.
  3. Browse the schema, write your ADQL in the query box, and run.

A cone search in ADQL

ADQL adds geometric functions for positional queries. A cone search around (RA, Dec) = (150.0, 2.0) with a 3 arcmin (0.05°) radius, against the multisurvey catalog:

SELECT TOP 100 oid, meanra, meandec, n_det, firstmjd, lastmjd
FROM alerce_tap.object
WHERE 1 = CONTAINS(
    POINT('ICRS', meanra, meandec),
    CIRCLE('ICRS', 150.0, 2.0, 0.05)
)

The same query against ZTF-legacy uses the ztf schema:

SELECT TOP 100 oid, meanra, meandec, ndet, firstmjd, lastmjd
FROM ztf.object
WHERE 1 = CONTAINS(
    POINT('ICRS', meanra, meandec),
    CIRCLE('ICRS', 150.0, 2.0, 0.05)
)

The full list of tables and columns is in the schema browser of the TAP service (at tap.alerce.online, in TOPCAT, or via tap.tables in pyvo).

Migrating from direct SQL

Most direct-SQL workflows map cleanly onto ADQL — it is SQL, with a few differences:

Direct SQL (today) TAP / ADQL (going forward)
Connect with host/port/user/password Connect to the TAP endpoint over HTTPS (no DB credentials)
LIMIT 100 TOP 100 (ADQL uses SELECT TOP n …)
Vendor-specific spatial operators / q3c functions Standard ADQL CONTAINS / POINT / CIRCLE
Full read access to internal tables The published, documented tables exposed by the service
Driver-specific result handling Standard VOTable results → astropy.table.Table

Tips for a smooth migration:

  1. Inventory your queries. List the tables and columns you rely on.
  2. Find their equivalents in the TAP schema browser.
  3. Rewrite LIMIT as TOP and switch any spatial predicates to ADQL CONTAINS/CIRCLE.
  4. Validate against the read-only window (see timeline) so you can compare results before direct access goes away.
  5. If your queries are really object/feature lookups, consider the Python client instead — it may be less code than ADQL.

Worked examples: our use-case notebooks at github.com/alercebroker/usecases are being updated to use TAP in place of direct database calls — the TAP versions will be available in the repo within the next couple of days. Once published, they’ll be the fastest way to see real, working ADQL queries against both the alerce_tap and ztf schemas and to adapt them to your own analysis.

Timeline

All dates are approximate; we will post updates here and announce major milestones.

When What happens What it means for you
Late June 2026 The database is frozen No new data is written into the ZTF-legacy dataset. Existing data stays available.
~3 months after the freeze Read-only migration window Direct connections still work (read-only). Migrate your code to TAP during this window.
Around September 2026 Direct database access is removed Direct SQL connections stop working. Use TAP and our other interfaces from here on.
Before the end of 2026 (planned) ZTF data migrated into the multisurvey database We’ll announce this separately. Until then, access ZTF data via ZTF-legacy.
2027 at the earliest Eventual retirement of ZTF-legacy No fixed date. ZTF-legacy remains available for a long time; we will give ample notice.

Frequently asked questions

Is my data being deleted?
No. We’re retiring the direct connection method, not the data. Both the multisurvey database and ZTF-legacy remain fully queryable through TAP and our other interfaces.

I only use the website / API / Python client. Do I need to do anything?
No. Those interfaces are unaffected.

Where is ZTF data?
For now, in ZTF-legacy — query it there. We plan to migrate all ZTF data into the multisurvey database before the end of 2026 and will notify you when it’s done.

When exactly will direct access stop working?
Around September 2026, roughly three months after the database is frozen in late June 2026. Dates are approximate; we’ll confirm them here as they firm up.

Will ZTF-legacy disappear after September 2026?
No. Only direct access is removed then. ZTF-legacy itself stays available through TAP and our other interfaces, with no retirement before 2027 and plenty of advance notice.

Can TAP do everything my SQL queries did?
For the data we publish, yes — ADQL is a full SQL dialect plus astronomy functions. The main differences are TOP n instead of LIMIT n and standard ADQL spatial functions instead of vendor-specific operators.

Getting help

  • Example notebooks: github.com/alercebroker/usecases — TAP-based notebooks you can copy and adapt (available in the next couple of days).
  • TAP service & connection details: tap.alerce.online — connection instructions, the exact service URL, and the table/column browser.
  • Community & questions: ask on the LSST Community forum using the tag alerce — a good place to share ADQL queries and get help migrating.

We’ll keep this page updated as the migration progresses.

Direct database access is being retired — we're moving to the TAP service. Read the migration guide →