Choosing a query

You have picked an archive and a data level (see Data levels). Now pick a query method by what you already know about the data you want.

You know…	Use	What it does
A time window	query_datetime	Filters on the observation date. Always works.
A star by name	query_object	Resolves the name to coordinates, then cone-searches.
RA/Dec	query_position	Direct cone search around a astropy.coordinates.SkyCoord.
The exact catalog ID	query_qobject	Exact match on qobject (usually Gaia DR2); no resolver, no ambiguity.
The proposal ID	query_program	Every observation from one program.
The lead scientist	query_pi	Every observation led by that person.
Several of the above	query_criteria	Combines constraints in one server round-trip.
Nothing above fits	query_adql	Raw escape hatch; you own the ADQL.

Start with a time window

query_datetime is the safest first query: it always works and is the only sky-independent one. When in doubt — or when working with solar data — it is the right entry point.

Name versus catalog ID

Two methods find a specific target, and the difference matters:

• query_object takes a human-readable name ('HD 189733'), resolves it via name resolution (Simbad / NED), and cone-searches around the resulting coordinates. Use it when you have a name but not exact coordinates or an ID. Note the free-text object field is inconsistent across programs, so do not try to exact-match on it.

• query_qobject takes the archive’s normalized catalog ID (Gaia DR2) and does an exact, unambiguous match with no network name-resolution step. Use it when you want every observation of one specific target, reliably.

Combine, do not chain

When you know several things at once — say a date range and a target — reach for query_criteria with a dict (keys: datetime, position, object plus object_radius, qobject, program, pi_name, and where for a raw ADQL add-on). One combined query beats running several and merging the results.

When a method does not apply

Not every method makes sense for every archive or level. Solar observations have no celestial target — their query coordinates (qra / qdec / qrad / qdecd) are sentinel values — so position, object, and qobject searches on solar data raise NotApplicable rather than return meaningless rows. Likewise query_pi raises it on tables with no PI column. Each archive’s page lists exactly which methods apply. For solar data, reach for query_datetime, optionally narrowed with a where= cut (e.g. extsnr > 200).

Sync versus async

A normal query_* call is synchronous and returns immediately — fine for bounded queries (keep them small with maxrec while exploring). For very large or multi-year pulls that would time out, use an async TAP job (AsyncJob) instead. See TAP and ADQL, just enough and Querying vs downloading, and proprietary data.