Warn the user if the Gaia result has limited rows

The `query_object` and `cone_search` families of functions in the Gaia
module now emit a `UserWarning` if the number of rows in the query
result matches the row limit.

astroquery/gaia/core.py

@@ -14,6 +14,8 @@
 
 
 """
+from warnings import warn
+
 from requests import HTTPError
 
 from astroquery.utils.tap import TapPlus
@@ -437,7 +439,12 @@ def __query_object(self, coordinate, radius=None, width=None, height=None,
                 job = self.launch_job_async(query, verbose=verbose)
             else:
                 job = self.launch_job(query, verbose=verbose)
-        return job.get_results()
+        table = job.get_results()
+        if len(table) == row_limit:
+            warn('The number of rows in the result matches the current row '
+                 f'limit of {row_limit}. You might wish to specify a '
+                 f'different "row_limit" value.', UserWarning)
+        return table
 
     def query_object(self, coordinate, radius=None, width=None, height=None,
                      verbose=False, columns=[], row_limit=None):
@@ -589,18 +596,22 @@ def __cone_search(self, coordinate, radius, table_name=None,
                               'radius': radiusDeg, 'table_name': table_name or self.MAIN_GAIA_TABLE or conf.MAIN_GAIA_TABLE})
 
         if async_job:
-            return self.launch_job_async(query=query,
-                                         output_file=output_file,
-                                         output_format=output_format,
-                                         verbose=verbose,
-                                         dump_to_file=dump_to_file,
-                                         background=background)
+            result = self.launch_job_async(query=query,
+                                        output_file=output_file,
+                                        output_format=output_format,
+                                        verbose=verbose,
+                                        dump_to_file=dump_to_file,
+                                        background=background)
         else:
-            return self.launch_job(query=query,
-                                   output_file=output_file,
-                                   output_format=output_format,
-                                   verbose=verbose,
-                                   dump_to_file=dump_to_file)
+            result = self.launch_job(query=query, output_file=output_file,
+                                     output_format=output_format,
+                                     verbose=verbose,
+                                     dump_to_file=dump_to_file)
+        if len(result.get_data()) == row_limit:
+            warn('The number of rows in the result matches the current row '
+                 f'limit of {row_limit}. You might wish to specify a '
+                 f'different "row_limit" value.', UserWarning)
+        return result
 
     def cone_search(self, coordinate, radius=None,
                     table_name=None,

astroquery/gaia/tests/test_gaia_remote.py

@@ -12,12 +12,20 @@ def test_query_object_row_limit():
     coord = SkyCoord(ra=280, dec=-60, unit=(u.degree, u.degree), frame='icrs')
     width = u.Quantity(0.1, u.deg)
     height = u.Quantity(0.1, u.deg)
-    r = Gaia.query_object_async(coordinate=coord, width=width, height=height)
+    msg = ('The number of rows in the result matches the current row limit of '
+           '50. You might wish to specify a different "row_limit" value.')
+    with pytest.warns(UserWarning, match=msg):
+        r = Gaia.query_object_async(coordinate=coord, width=width,
+                                    height=height)
 
     assert len(r) == conf.ROW_LIMIT
 
     Gaia.ROW_LIMIT = 10
-    r = Gaia.query_object_async(coordinate=coord, width=width, height=height)
+    msg = ('The number of rows in the result matches the current row limit of '
+           '10. You might wish to specify a different "row_limit" value.')
+    with pytest.warns(UserWarning, match=msg):
+        r = Gaia.query_object_async(coordinate=coord, width=width,
+                                    height=height)
 
     assert len(r) == 10 == Gaia.ROW_LIMIT
 
@@ -32,13 +40,19 @@ def test_cone_search_row_limit():
     Gaia = GaiaClass()
     coord = SkyCoord(ra=280, dec=-60, unit=(u.degree, u.degree), frame='icrs')
     radius = u.Quantity(0.1, u.deg)
-    j = Gaia.cone_search_async(coord, radius)
+    msg = ('The number of rows in the result matches the current row limit of '
+           '50. You might wish to specify a different "row_limit" value.')
+    with pytest.warns(UserWarning, match=msg):
+        j = Gaia.cone_search_async(coord, radius)
     r = j.get_results()
 
     assert len(r) == conf.ROW_LIMIT
 
     Gaia.ROW_LIMIT = 10
-    j = Gaia.cone_search_async(coord, radius)
+    msg = ('The number of rows in the result matches the current row limit of '
+           '10. You might wish to specify a different "row_limit" value.')
+    with pytest.warns(UserWarning, match=msg):
+        j = Gaia.cone_search_async(coord, radius)
     r = j.get_results()
 
     assert len(r) == 10 == Gaia.ROW_LIMIT

astroquery/gaia/tests/test_gaiatap.py

@@ -214,6 +214,11 @@ def test_query_object_async(self):
                                     'table1_oid',
                                     None,
                                     np.int32)
+        msg = ('The number of rows in the result matches the current row '
+               'limit of 3. You might wish to specify a different "row_limit" '
+               'value.')
+        with pytest.warns(UserWarning, match=msg):
+            job = tap.query_object_async(sc, radius, row_limit=3)
 
     def test_cone_search_sync(self):
         connHandler = DummyConnHandler()
@@ -376,7 +381,11 @@ def test_cone_search_async(self):
         # No row limit
         job = tap.cone_search_async(sc, radius, row_limit=-1)
         assert 'TOP' not in job.parameters['query']
-
+        msg = ('The number of rows in the result matches the current row '
+               'limit of 3. You might wish to specify a different "row_limit" '
+               'value.')
+        with pytest.warns(UserWarning, match=msg):
+            job = tap.cone_search_async(sc, radius, row_limit=3)
 
     def __check_results_column(self, results, columnName, description, unit,
                                dataType):

docs/gaia/gaia.rst

@@ -124,6 +124,8 @@ degrees around an specific point in RA/Dec coordinates.
    0.020802655215768254 1635721458409799680 ...
    0.021615117161838747 1635721458409799680 ...
   Length = 50 rows
+  UserWarning: The number of rows in the result matches the current row limit
+  of 50. You might wish to specify a different "row_limit" value.
 
 By default the number of rows returned by a query is limited by the
 ``astroquery.gaia.conf.ROW_LIMIT`` value. This value can be overruled in a
@@ -149,6 +151,8 @@ class attribute ``Gaia.ROW_LIMIT`` is set then it will take precedence over
    0.006209042666371929 1635721458409799680 ...
    0.007469463683838576 1635721458409799680 ...
    0.008202004514524316 1635721458409799680 ...
+  UserWarning: The number of rows in the result matches the current row limit
+  of 8. You might wish to specify a different "row_limit" value.
 
 To return an unlimited number of rows set the row limit to ``-1``.
 
@@ -213,6 +217,8 @@ radius argument. The number of rows is limited just like in object queries.
   1635721458409799680 Gaia DR2 6636090334814218752 ...  0.005846434715822121
                   ...                          ... ...                   ...
   Length = 50 rows
+  UserWarning: The number of rows in the result matches the current row limit
+  of 50. You might wish to specify a different "row_limit" value.
 
 
 1.3. Getting public tables metadata