From d99fbf5478c9b7376919d9fb9bbaa21901b0e7e0 Mon Sep 17 00:00:00 2001
From: Jennifer Medina <jmedina@stsci.edu>
Date: Fri, 20 Oct 2023 01:35:49 -0400
Subject: [PATCH 1/2] Updated documentation with error-handling example for
 get_product_list

---
 docs/mast/mast_obsquery.rst | 14 +++++++++++++-
 1 file changed, 13 insertions(+), 1 deletion(-)

diff --git a/docs/mast/mast_obsquery.rst b/docs/mast/mast_obsquery.rst
index f11f57bd92..b6495c973b 100644
--- a/docs/mast/mast_obsquery.rst
+++ b/docs/mast/mast_obsquery.rst
@@ -208,7 +208,7 @@ Getting Product Lists
 ---------------------
 
 Each observation returned from a MAST query can have one or more associated data products.
-Given one or more observations or observation ids ("obsid")
+Given one or more observations or MAST Product Group IDs ("obsid")
 `~astroquery.mast.ObservationsClass.get_product_list` will return
 a `~astropy.table.Table` containing the associated data products.
 The product fields are documented `here <https://mast.stsci.edu/api/v0/_productsfields.html>`__.
@@ -278,6 +278,18 @@ The product fields are documented `here <https://mast.stsci.edu/api/v0/_products
    >>> print((data_products_by_obs == data_products_by_id).all())
    True
 
+Note that the input to `~astroquery.mast.ObservationsClass.get_product_list` should be "obsid" and NOT "obs_id",
+which is a mission-specific identifier for a given observation, and cannot be used for querying the MAST database
+with `~astroquery.mast.ObservationsClass.get_product_list`
+(see `here <https://mast.stsci.edu/api/v0/_c_a_o_mfields.html>`__ for more details).
+Using "obs_id" instead of "obsid" from the previous example will result in the following error:
+
+.. doctest-remote-data::
+   >>> obs_ids = obs_table[0:2]['obs_id']
+   >>> data_products_by_id = Observations.get_product_list(obs_ids)
+   Traceback (most recent call last):
+   ...
+   RemoteServiceError: Error converting data type varchar to bigint.
 
 Filtering
 ---------

From 86d7e011bc4665c3828f415e3638e56ab5021caf Mon Sep 17 00:00:00 2001
From: Jennifer Medina <jmedina@stsci.edu>
Date: Fri, 20 Oct 2023 01:44:02 -0400
Subject: [PATCH 2/2] Updated docstring to make explicit obsid and obs_id
 difference. Changelog.

---
 CHANGES.rst                     | 2 ++
 astroquery/mast/observations.py | 3 ++-
 2 files changed, 4 insertions(+), 1 deletion(-)

diff --git a/CHANGES.rst b/CHANGES.rst
index 2320049201..26042c0e6a 100644
--- a/CHANGES.rst
+++ b/CHANGES.rst
@@ -205,6 +205,8 @@ mast
 
 - Resolved issue making PANSTARRS catalog queries when columns and sorting is specified. [#2727]
 
+- Updating documentation to address the difference between ``obsid`` and ``obs_id`` database fields. [#2857]
+
 nist
 ^^^^
 
diff --git a/astroquery/mast/observations.py b/astroquery/mast/observations.py
index a082ea4a35..bd276ca861 100644
--- a/astroquery/mast/observations.py
+++ b/astroquery/mast/observations.py
@@ -410,7 +410,8 @@ def query_criteria_count(self, *, pagesize=None, page=None, **criteria):
     def get_product_list_async(self, observations):
         """
         Given a "Product Group Id" (column name obsid) returns a list of associated data products.
-        See column documentation `here <https://masttest.stsci.edu/api/v0/_productsfields.html>`__.
+        Note that obsid is NOT the same as obs_id, and inputting obs_id values will result in
+        an error. See column documentation `here <https://masttest.stsci.edu/api/v0/_productsfields.html>`__.
 
         Parameters
         ----------