Observations - Query for Raw Data (Instrument-Specific)#

Note

The astroquery.eso module provides several ways to search for raw data in the ESO Science Archive. This section focuses on the instrument-specific query interface for raw data query_instrument(), while in the generic raw-data query section we describe generic queries using query_main().

In many cases, you will want to query the ESO Archive for data from a specific instrument. This is exactly what the query_instrument() method is designed for. It allows you to search instrument-specific tables, which expose metadata fields and filters unique to each instrument. Internally, this method queries the corresponding instrument table (e.g., ist.muse) via ESO’s TAP service. This approach is ideal when you need precise control over your query, such as filtering by instrument configuration, mode, or observational setup.

Available Instruments#

To begin retrieving raw data from the ESO Science Archive, you first need to identify the relevant instrument(s) for your search. Each instrument has its own dedicated query table accessible through the archive’s programmatic TAP interface.

The list of all supported instruments can be retrieved using the list_instruments() method:

>>> from astroquery.eso import Eso
>>> eso = Eso()

>>> eso.list_instruments()
['alpaca', 'amber', 'apex', 'crires', 'efosc', 'eris',
'espresso', 'fiat', 'fors1', 'fors2', 'giraffe', 'gravity',
'harps', 'hawki', 'isaac', 'kmos', 'matisse', 'midi',
'muse', 'naco', 'nirps', 'omegacam', 'pionier', 'sinfoni',
'sofi', 'sphere', 'uves', 'vimos', 'vircam', 'visir',
'wlgsu', 'xshooter']

This list corresponds to the instruments currently available for programmatic raw data queries in the ESO archive.

The list is dynamically generated by querying the archive’s internal TAP service. It can also be reproduced directly by executing the following ADQL query on the ESO TAP interface or using the query_tap() function:

SELECT table_name
FROM TAP_SCHEMA.tables
WHERE schema_name = 'ist'
ORDER BY table_name

Once you have identified the instrument of interest, you can proceed with constructing your query and retrieving raw data products.

Available Query Constraints#

Once an instrument is selected — for example, midi — you can inspect the available queryable columns using the help=True keyword in the query_instrument() method. This is a useful first step to understand what metadata is available and how to structure your query.

The output includes column names, data types, units, and, where applicable, xtype information to indicate more specific column content. The xtype attribute defines how a string-valued column should be interpreted during querying. For example, a column with datatype char may represent a standard string (xtype = null), a timestamp (xtype = timestamp), or a sky region footprint usable in ADQL spatial queries (xtype = adql:REGION), with this interpretation reflected in the xtype field.

>>> eso.query_instrument("midi", help=True)
INFO:
Columns present in the table ist.midi:
    column_name     datatype    xtype         unit
------------------- -------- ------------ -----------
     access_estsize     long                 kbyte
         access_url     char
       datalink_url     char
           date_obs     char
                ...
          exp_start     char      timestamp
                ...
             object     char
                ...
       release_date     char      timestamp
           s_region     char   adql:REGION
                ...
                utc    float                    s
Number of records present in the table ist.midi:
437577
[astroquery.eso.core]

Query with Constraints#

Once the available query columns have been inspected, you can construct a constrained query to retrieve relevant datasets. For example, suppose you want to retrieve MIDI observations that were taken between 2008-01-01 and 2009-05-12.

The column_filters dictionary allows you to specify conditions for individual columns, using ADQL-compatible expressions under the hood. In this case, the filters apply to:

  • object: the target name, matched as a string (case-insensitive)

  • exp_start: the observation start time, stored as a char column with timestamp xtype

The columns argument controls which fields are returned in the results table.

Tip

  • Use only column names returned via help=True (in this case exp_start, object, prog_id, exptime, etc.).

  • String filters (like object) are matched case-insensitively.

  • Temporal filters on fields like exp_start or release_date can use SQL-style syntax (e.g. between 'YYYY-MM-DD' and 'YYYY-MM-DD').

  • Column names are case-sensitive in Python, so ensure they match exactly.

>>> table = eso.query_instrument(
...             instrument="midi",
...             column_filters={
...                 "exp_start": "between '2008-01-01' and '2009-05-12'"},
...             columns=["object", "date_obs"]
...                             )
>>> table
<Table length=1000>
            object                     date_obs
            object                      object
------------------------------ -----------------------
                WAVE,SPECTEMPL 2008-01-03T08:57:45.000
                        OTHER 2008-01-03T08:58:07.803
                WAVE,SPECTEMPL 2008-01-03T08:59:37.000
                WAVE,SPECTEMPL 2008-01-03T09:00:38.000
                        ...                     ...
    PHOTOMETRY,OBJECT,SCIPHOT 2008-01-12T02:23:16.606

Tip

Use query_main() when you want to search across all instruments. Use query_instrument() when you want a more refined, instrument-specific search (e.g. instrument modes, configurations, or ambient conditions).

>>> column_filters = {
...     "dp_cat": "SCIENCE",           # Science data only
...     "ins_opt1_name": "HIGH_SENS",  # High sensitivity mode
...     "night_flag": "night",         # Nighttime observations only
...     "moon_illu": "< 0",            # No moon (below horizon)
...     "lst": "between 0 and 6"       # Local sidereal time early in the night
... }
>>> table = eso.query_instrument("midi", column_filters=column_filters)

Download Data#

To download the data returned by the query, you can use the retrieve_data() method. This method takes a list of data product IDs (dp_id) and downloads the corresponding files from the ESO archive.

>>> eso.retrieve_data(table["dp_id"])

The data_files list points to the decompressed dataset filenames that have been locally downloaded. The default location of the decompressed datasets can be adjusted by providing a destination keyword in the call to retrieve_data().

>>> data_files = eso.retrieve_data(table["dp_id"], destination="./eso_data/")

For raw data, you can also retrieve associated calibration files by passing with_calib="raw" (or with_calib="processed"). See Observations - Download Data for examples and the related CalSelector terminology.