Accessing ALeRCE data: moving from direct database access to TAP

Moving from direct database access to the TAP service

Last updated: 30/06/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, and this is not a data freeze — ALeRCE keeps ingesting and serving data as usual (including ZTF), and all our services stay live and up to date. The only thing being phased out is the ability to connect to the database directly. 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
Our websites (Explorer, SN Hunter)	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
The cross-match and catsHTM tools	None	Nothing to do
An older copy of our notebooks that connects to the database directly	Affected	Update it — pull the current version, or replace its direct-DB calls with TAP
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
Websites (Explorer, SN Hunter)	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. Everything you can reach through a direct connection is available through TAP, in two schemas:

alerce_tap → our main multi-survey catalog (e.g. alerce_tap.object, alerce_tap.detection, alerce_tap.probability, alerce_tap.feature).
ztf → ZTF data (e.g. ztf.object, ztf.detection, ztf.forced_photometry, ztf.magstat). For ZTF, use this schema.

Heads-up: the alerce_tap schema also contains ZTF tables, but they are not ready for use yet — please keep using the ztf schema for ZTF data for now. We'll announce when the ZTF tables under alerce_tap are ready.

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 multi-survey 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

Open TOPCAT → VO → Table Access Protocol (TAP) Query.
Enter the service URL: https://tap.alerce.online/tap.
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 our main multi-survey catalog (alerce_tap):

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 data 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:

Inventory your queries. List the tables and columns you rely on.
Find their equivalents in the TAP schema browser.
Rewrite LIMIT as TOP and switch any spatial predicates to ADQL CONTAINS/CIRCLE.
Validate against the read-only window (see timeline) so you can compare results before direct access goes away.
Update any old notebooks. If you saved an earlier copy of one of our notebooks that connects to the database directly, pull the current version (it now uses TAP) or swap its direct-DB calls for TAP.
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 have been updated to use TAP in place of direct database calls. They're 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
07/07/2026	The directly-connected database is frozen	It becomes a static snapshot — no new data arrives through the direct connection. Every ALeRCE service (TAP, API, websites) keeps updating as normal, so move to TAP to keep getting fresh data.
~3 months (through ~October 2026)	Read-only migration window	Your existing direct connection still works (read-only). Migrate your queries to TAP during this window.
Around October 2026	Direct database access is removed	Direct SQL connections stop working. Use TAP and our other interfaces from here on.

Frequently asked questions

Is this a data freeze? Is ZTF data stopping?
No. ALeRCE keeps ingesting and serving data as usual, including ZTF — TAP, the API, and our websites all stay live and up to date. The freeze on 07/07/2026 applies only to the direct connection, which is exactly why we ask direct users to move to TAP, where the data keeps flowing.

Is my data being deleted?
No. We're retiring the direct connection method, not the data. Everything stays fully queryable through TAP and our other services.

I use the websites / API / Python client / cross-match / catsHTM. Do I need to do anything?
No — those are unaffected. Notebooks are the one thing to check: if you kept an old copy of one of our notebooks that connects to the database directly, update it to use TAP.

Where is ZTF data?
Right where it is — fully available through all our services, and still updating. In TAP, query it via the ztf schema. (The alerce_tap schema also has ZTF tables, but they're not ready yet — use ztf for now; we'll announce when they're ready.)

When exactly will direct access stop working?
Around October 2026, roughly three months after the 07/07/2026 freeze. Dates are approximate; we'll confirm them here as they firm up.

Will I lose access to anything after October 2026?
Only the direct connection. Everything you reach today through TAP, the API, the Python client, our websites, and our other tools stays available.

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.
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.