From 55378c10baee91cee679241932a26c4320e83b6c Mon Sep 17 00:00:00 2001
From: thiagobomfin-galileo <thiago.bomfin@galileo.ai>
Date: Fri, 6 Mar 2026 12:57:24 -0300
Subject: [PATCH] docs(datasets): document asymmetric NotFoundError vs None
 behavior for get_dataset

---
 src/galileo/__future__/dataset.py | 15 ++++++++++++---
 src/galileo/datasets.py           | 32 +++++++++++++++++++++++--------
 2 files changed, 36 insertions(+), 11 deletions(-)

diff --git a/src/galileo/__future__/dataset.py b/src/galileo/__future__/dataset.py
index 8398f398..bba4b4a0 100644
--- a/src/galileo/__future__/dataset.py
+++ b/src/galileo/__future__/dataset.py
@@ -195,24 +195,33 @@ def get(cls, *, id: str | None = None, name: str | None = None) -> Dataset | Non
         """
         Get an existing dataset by ID or name.
 
+        .. note::
+            Lookup behavior differs depending on which parameter is used:
+
+            - **By ID**: the API performs a direct lookup. If no dataset with that ID exists,
+              a ``NotFoundError`` is raised.
+            - **By name**: the API performs a filtered list query. If no dataset with that name
+              exists, ``None`` is returned (no exception is raised).
+
         Args:
             id (Optional[str]): The dataset ID.
             name (Optional[str]): The dataset name.
 
         Returns
         -------
-            Optional[Dataset]: The dataset if found, None otherwise.
+            Optional[Dataset]: The dataset if found, or ``None`` if looked up by name and no match exists.
 
         Raises
         ------
+            NotFoundError: If looked up by ID and no dataset with that ID exists.
             ValueError: If neither or both id and name are provided.
 
         Examples
         --------
-            # Get by name
+            # Get by name — returns None if not found
             dataset = Dataset.get(name="geography-questions")
 
-            # Get by ID
+            # Get by ID — raises NotFoundError if not found
             dataset = Dataset.get(id="dataset-123")
         """
         datasets_service = Datasets()
diff --git a/src/galileo/datasets.py b/src/galileo/datasets.py
index f058e7e1..eb35b7ba 100644
--- a/src/galileo/datasets.py
+++ b/src/galileo/datasets.py
@@ -285,6 +285,14 @@ def get(
 
         Optionally validates that the dataset is used in a specific project.
 
+        .. note::
+            Lookup behavior differs depending on which parameter is used:
+
+            - **By ID**: the API performs a direct lookup. If no dataset with that ID exists,
+              a ``NotFoundError`` is raised.
+            - **By name**: the API performs a filtered list query. If no dataset with that name
+              exists, ``None`` is returned (no exception is raised).
+
         Parameters
         ----------
         id : str
@@ -300,17 +308,17 @@ def get(
 
         Returns
         -------
-        Dataset
-            The dataset.
+        Optional[Dataset]
+            The dataset if found, or ``None`` if looked up by name and no match exists.
 
         Raises
         ------
+        NotFoundError
+            If looked up by ID and no dataset with that ID exists.
         ValueError
             If neither or both `id` and `name` are provided, if both project_id and project_name
             are provided, or if the specified project does not exist, or if the dataset is not
             used in the specified project.
-        errors.UnexpectedStatus
-            If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
         httpx.TimeoutException
             If the request takes longer than Client.timeout.
 
@@ -666,6 +674,14 @@ def get_dataset(
 
     Optionally validates that the dataset is used in a specific project.
 
+    .. note::
+        Lookup behavior differs depending on which parameter is used:
+
+        - **By ID**: the API performs a direct lookup. If no dataset with that ID exists,
+          a ``NotFoundError`` is raised.
+        - **By name**: the API performs a filtered list query. If no dataset with that name
+          exists, ``None`` is returned (no exception is raised).
+
     Parameters
     ----------
     id : str
@@ -679,17 +695,17 @@ def get_dataset(
 
     Returns
     -------
-    Dataset
-        The dataset.
+    Optional[Dataset]
+        The dataset if found, or ``None`` if looked up by name and no match exists.
 
     Raises
     ------
+    NotFoundError
+        If looked up by ID and no dataset with that ID exists.
     ValueError
         If neither or both `id` and `name` are provided, if both project_id and project_name
         are provided, or if the specified project does not exist, or if the dataset is not
         used in the specified project.
-    errors.UnexpectedStatus
-        If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
     httpx.TimeoutException
         If the request takes longer than Client.timeout.