diff --git a/CHANGES.rst b/CHANGES.rst index 9be6958c7a..0d41814cb3 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -54,6 +54,7 @@ heasarc - Add ``query_constraints`` to allow querying of different catalog columns. [#3403] - Add support for uploading tables when using TAP directly through ``query_tap``. [#3403] - Add automatic guessing for the data host in ``download_data``. [#3403] +- Include method to count the number of rows in a specified table. [#3549] gaia ^^^^ diff --git a/astroquery/heasarc/core.py b/astroquery/heasarc/core.py index f92121ff70..b073e5788f 100644 --- a/astroquery/heasarc/core.py +++ b/astroquery/heasarc/core.py @@ -958,5 +958,30 @@ def _s3_tree_download(client, bucket_name, path, local): path = key.replace(f's3://{self.S3_BUCKET}/', '') _s3_tree_download(self.s3_client, self.S3_BUCKET, path, location) + def count_rows(self, catalog: str) -> np.int64: + """ + Returns the number of rows in the HEASARC-hosted catalog specified by + the `catalog` argument. + + Parameters + ---------- + catalog : `str` + The name of the catalog to query for a total number of rows. To list + the available catalogs, use + :meth:`~astroquery.heasarc.HeasarcClass.list_catalogs`. + + Returns + ------- + num_rows : `np.int64` + The total number of rows in the specified catalog. + """ + # Send a query requesting a count of the number of rows in the + # specified catalog. + count_return = self.query_tap(f"SELECT COUNT(*) FROM {catalog}") + + # Extract an integer number of rows from the returned table. + num_rows = count_return["count"][0] + return num_rows + Heasarc = HeasarcClass() diff --git a/astroquery/heasarc/tests/test_heasarc_remote.py b/astroquery/heasarc/tests/test_heasarc_remote.py index 4d765c7583..04d4dc35d7 100644 --- a/astroquery/heasarc/tests/test_heasarc_remote.py +++ b/astroquery/heasarc/tests/test_heasarc_remote.py @@ -273,6 +273,13 @@ def test_deprecated_pars(self, pars): Heasarc.query_region(pos, mission="xmmmaster", **{keyword: value}) + def test_row_count(self): + """Test the convenience method that uses ADQL's COUNT function to + return the number of rows in a catalog. + """ + cat = "suzamaster" + assert Heasarc.count_rows(cat) == 3055 + @pytest.mark.remote_data class TestHeasarcBrowse: diff --git a/docs/heasarc/heasarc.rst b/docs/heasarc/heasarc.rst index 5aa7a28b36..8216d23576 100644 --- a/docs/heasarc/heasarc.rst +++ b/docs/heasarc/heasarc.rst @@ -422,6 +422,17 @@ in the XMM master catalog ``xmmmaster``: public_date Public Date mjd ra Right Ascension (Pointing Position) degree +Get Length Of Catalog +--------------------- +To easily find out the number of rows in a catalog, use the `~astroquery.heasarc.HeasarcClass.count_rows` +method. Here, for instance, we fetch the number of rows in the Suzaku 'master' observation table (``suzamaster``): + +.. doctest-remote-data:: + + >>> from astroquery.heasarc import Heasarc + >>> Heasarc.count_rows('suzamaster') + np.int64(3055) + Reference/API =============