MAST: count_only parameter for MastMissions queries

CHANGES.rst

@@ -201,6 +201,8 @@ mast
 - Added ``pass_id`` as an alias for the ``pass`` column in query functions for the Roman mission to avoid conflicts with
   the reserved Python keyword. [#3588]
 - Update the cutout format request parameter in ``Zcut.download_cutouts`` to reflect a recent service change. [#3608]
+- Add a ``count_only`` parameter to ``MastMissions`` query methods to return only the number of matching results,
+  rather than the full result table. [#3645]
 
 
 jplspec

astroquery/mast/missions.py

@@ -138,6 +138,10 @@ def _parse_result(self, response, *, verbose=False):  # Used by the async_to_syn
         if self.service == self._search:
             results = self._service_api_connection._parse_result(response, verbose, data_key='results')
 
+            # If returning a count_only response, return the count as an integer
+            if isinstance(results, int):
+                return results
+
             # Add column descriptions to column metadata
             column_list = self.get_column_list()
             for col in results.columns:
@@ -378,7 +382,7 @@ def _is_legacy_ra_dec_pair(items):
     @class_or_instance
     @deprecated_renamed_argument('objectname', 'object_names', since='0.4.12')
     def query_criteria_async(self, *, coordinates=None, object_names=None, radius=3*u.arcmin,
-                             limit=5000, offset=0, select_cols=None, resolver=None, **criteria):
+                             limit=5000, offset=0, select_cols=None, resolver=None, count_only=False, **criteria):
         """
         Given a set of search criteria, returns a list of mission metadata.
 
@@ -414,6 +418,8 @@ def query_criteria_async(self, *, coordinates=None, object_names=None, radius=3*
             "SIMBAD" and "NED". If not specified, the default resolver order will be used. Please see the
             `STScI Archive Name Translation Application (SANTA) <https://mastresolver.stsci.edu/Santa-war/>`__
             for more information. Default is None.
+        count_only : bool, optional
+            Default is False. If True, only the count of matching datasets will be returned.
         **criteria
             Criteria to apply. Valid criteria include coordinates, object_names, radius (as in
             `~astroquery.mast.missions.MastMissionsClass.query_region` and
@@ -462,13 +468,16 @@ def query_criteria_async(self, *, coordinates=None, object_names=None, radius=3*
             params["radius"] = radius.arcsec
             params["radius_units"] = 'arcseconds'
 
+        if count_only:
+            params["count_only"] = True
+
         self._build_params_from_criteria(params, **criteria)
 
         return self._service_api_connection.missions_request_async(self.service, params)
 
     @class_or_instance
     def query_region_async(self, coordinates, *, radius=3*u.arcmin, limit=5000, offset=0,
-                           select_cols=None, **criteria):
+                           select_cols=None, count_only=False, **criteria):
         """
         Given a sky position (or positions) and radius, returns a list of matching dataset IDs.
 
@@ -493,6 +502,8 @@ def query_region_async(self, coordinates, *, radius=3*u.arcmin, limit=5000, offs
             If None, a default set of columns will be returned.
             Can either be an iterable of column names, a comma-separated string of column names,
             or 'all'/'*' to return all available columns.
+        count_only : bool, optional
+            Default is False. If True, only the count of matching datasets will be returned.
         **criteria
             Other mission-specific criteria arguments.
             All valid filters can be found using `~astroquery.mast.missions.MastMissionsClass.get_column_list`
@@ -516,12 +527,13 @@ def query_region_async(self, coordinates, *, radius=3*u.arcmin, limit=5000, offs
                                          limit=limit,
                                          offset=offset,
                                          select_cols=select_cols,
+                                         count_only=count_only,
                                          **criteria)
 
     @class_or_instance
     @deprecated_renamed_argument('objectname', 'object_names', since='0.4.12')
     def query_object_async(self, object_names, *, radius=3*u.arcmin, limit=5000, offset=0,
-                           select_cols=None, resolver=None, **criteria):
+                           select_cols=None, resolver=None, count_only=False, **criteria):
         """
         Given an object name (or names), returns a list of matching rows.
 
@@ -551,6 +563,8 @@ def query_object_async(self, object_names, *, radius=3*u.arcmin, limit=5000, off
             "SIMBAD" and "NED". If not specified, the default resolver order will be used. Please see the
             `STScI Archive Name Translation Application (SANTA) <https://mastresolver.stsci.edu/Santa-war/>`__
             for more information. Default is None.
+        count_only : bool, optional
+            Default is False. If True, only the count of matching datasets will be returned.
         **criteria
             Other mission-specific criteria arguments.
             All valid filters can be found using `~astroquery.mast.missions.MastMissionsClass.get_column_list`
@@ -570,6 +584,7 @@ def query_object_async(self, object_names, *, radius=3*u.arcmin, limit=5000, off
                                          offset=offset,
                                          select_cols=select_cols,
                                          resolver=resolver,
+                                         count_only=count_only,
                                          **criteria)
 
     @class_or_instance

astroquery/mast/services.py

@@ -262,8 +262,12 @@ def _parse_result(self, response, verbose=False, data_key='data'):
         -------
         response : `~astropy.table.Table`
         """
-
         result = response.json()
+
+        # Check for a count_only response and return the count if present
+        if "search_params" in result and result["search_params"]["count_only"]:
+            return result["totalResults"]
+
         result_table = _json_to_table(result, data_key=data_key)
 
         # Check for no results

astroquery/mast/tests/data/mission_count_only.json

@@ -0,0 +1,49 @@
+{
+    "messages": [],
+    "search_params": {
+        "target": [],
+        "radius": 3.0,
+        "radius_units": "arcminutes",
+        "offset": 0,
+        "limit": 5000,
+        "sort_by": [
+            "sci_targname",
+            "sci_data_set_name"
+        ],
+        "sort_desc": [
+            false,
+            false
+        ],
+        "skip_count": false,
+        "count_only": true,
+        "select_cols": [
+            "sci_data_set_name",
+            "sci_targname",
+            "sci_hapnum",
+            "sci_haspnum",
+            "sci_hslanum",
+            "sci_instrume",
+            "sci_aper_1234",
+            "sci_spec_1234",
+            "sci_actual_duration",
+            "sci_start_time",
+            "sci_pep_id",
+            "sci_pi_last_name",
+            "sci_ra",
+            "sci_dec",
+            "sci_refnum",
+            "sci_central_wavelength",
+            "sci_release_date",
+            "sci_stop_time",
+            "sci_preview_name",
+            "scp_scan_type",
+            "sci_hlsp"
+        ],
+        "search_key": [],
+        "user_fields": [],
+        "conditions": []
+    },
+    "totalResults": 1066009,
+    "info": [],
+    "results": []
+}