feat: Add Source.fetch_record() andStream.fetch_record() backed by SimpleRetriever._fetch_one()

airbyte_cdk/sources/declarative/concurrent_declarative_source.py

@@ -77,6 +77,7 @@
     ModelToComponentFactory,
 )
 from airbyte_cdk.sources.declarative.resolvers import COMPONENTS_RESOLVER_TYPE_MAPPING
+from airbyte_cdk.sources.declarative.retrievers import SimpleRetriever
 from airbyte_cdk.sources.declarative.spec.spec import Spec
 from airbyte_cdk.sources.declarative.types import Config, ConnectionDefinition
 from airbyte_cdk.sources.message.concurrent_repository import ConcurrentMessageRepository
@@ -507,6 +508,64 @@ def check(self, logger: logging.Logger, config: Mapping[str, Any]) -> AirbyteCon
             return AirbyteConnectionStatus(status=Status.FAILED, message=repr(error))
         return AirbyteConnectionStatus(status=Status.SUCCEEDED)
 
+    def fetch_record(
+        self,
+        stream_name: str,
+        pk_value: Any,
+        config: Optional[Mapping[str, Any]] = None,
+    ) -> Mapping[str, Any]:
+        """
+        Fetch a single record from a stream by primary key.
+
+        Args:
+            stream_name: Name of the stream to fetch from
+            pk_value: Primary key value to fetch. Can be:
+                     - str: For simple single-field primary keys (e.g., "123")
+                     - Mapping[str, Any]: For composite primary keys (e.g., {"company_id": "123", "property": "status"})
+            config: Source configuration (optional, uses instance config if not provided)
+
+        Returns:
+            The fetched record as a dict
+
+        Raises:
+            ValueError: If the stream name is not found in the source
+            NotImplementedError: If the stream doesn't support fetching individual records
+            RecordNotFoundException: If the record is not found (404 response)
+        """
+        config = config or self._config
+
+        stream_configs = self._stream_configs(self._source_config) + self.dynamic_streams
+
+        stream_config = None
+        for config_item in stream_configs:
+            if config_item.get("name") == stream_name:
+                stream_config = config_item
+                break
+
+        if not stream_config:
+            available_streams = [c.get("name") for c in stream_configs]
+            raise ValueError(
+                f"Stream '{stream_name}' not found in source. "
+                f"Available streams: {', '.join(available_streams)}"
+            )
+
+        declarative_stream = self._constructor.create_component(
+            DeclarativeStreamModel,
+            stream_config,
+            config,
+            emit_connector_builder_messages=self._emit_connector_builder_messages,
+        )
+
+        if not isinstance(declarative_stream.retriever, SimpleRetriever):
+            raise NotImplementedError(
+                f"Stream '{stream_name}' does not support fetching individual records. "
+                "Only streams with SimpleRetriever currently support this operation."
+            )
+
+        return declarative_stream.retriever.fetch_one(
+            pk_value=pk_value, records_schema=declarative_stream.get_json_schema()
+        )
+
     @property
     def dynamic_streams(self) -> List[Dict[str, Any]]:
         return self._dynamic_stream_configs(

airbyte_cdk/sources/declarative/exceptions.py

@@ -7,3 +7,7 @@ class ReadException(Exception):
     """
     Raise when there is an error reading data from an API Source
     """
+
+
+class RecordNotFoundException(ReadException):
+    """Raised when a requested record is not found (e.g., 404 response)."""

airbyte_cdk/sources/declarative/retrievers/simple_retriever.py

@@ -26,6 +26,7 @@
 from airbyte_cdk.legacy.sources.declarative.incremental import ResumableFullRefreshCursor
 from airbyte_cdk.legacy.sources.declarative.incremental.declarative_cursor import DeclarativeCursor
 from airbyte_cdk.models import AirbyteMessage
+from airbyte_cdk.sources.declarative.exceptions import RecordNotFoundException
 from airbyte_cdk.sources.declarative.extractors.http_selector import HttpSelector
 from airbyte_cdk.sources.declarative.interpolation import InterpolatedString
 from airbyte_cdk.sources.declarative.partition_routers.single_partition_router import (
@@ -626,6 +627,116 @@ def _to_partition_key(to_serialize: Any) -> str:
         # separators have changed in Python 3.4. To avoid being impacted by further change, we explicitly specify our own value
         return json.dumps(to_serialize, indent=None, separators=(",", ":"), sort_keys=True)
 
+    def fetch_one(
+        self,
+        pk_value: Union[str, Mapping[str, Any]],
+        records_schema: Mapping[str, Any],
+    ) -> Mapping[str, Any]:
+        """Fetch a single record by primary key value.
+
+        This method constructs a path by appending the primary key value to the base path
+        and sends a GET request to fetch a single record. It's designed for REST APIs that
+        follow the convention: GET /resource/{id}
+
+        Args:
+            pk_value: The primary key value to fetch. Can be:
+                     - str: For simple single-field primary keys (e.g., "123")
+                     - Mapping[str, Any]: For composite primary keys (e.g., {"company_id": "123", "property": "status"})
+            records_schema: JSON schema describing the record structure
+
+        Returns:
+            The fetched record as a dict.
+
+        Raises:
+            RecordNotFoundException: If the response is empty/ignored or parsing yields no records.
+            ValueError: If pk_value is not a string or dict.
+            Exception: HTTP errors (including 404) are propagated from requester's error handling.
+
+        Example:
+            record = retriever.fetch_one("123", schema)
+
+            record = retriever.fetch_one({"company_id": "123", "property": "status"}, schema)
+
+        Note:
+            This implementation uses convention-based path construction (Option B from design). (important-comment)
+            For simple PKs: appends /{pk_value} to base path (important-comment)
+            For composite PKs: appends /{value1}/{value2}/... in key order (important-comment)
+
+            Alternative approaches that could be implemented in the future: (important-comment)
+            - Path template interpolation: Use a configurable template like "{base_path}/{id}" (important-comment)
+              See: https://github.com/airbytehq/airbyte-python-cdk/issues/833#phase-1a (important-comment)
+            - Field path configuration: Allow specifying which response field contains the record (important-comment)
+              for APIs that wrap single records in envelopes like {"data": {...}} (important-comment)
+        """
+        # Get the base path from the requester
+        base_path = self.requester.get_path(
+            stream_state={},
+            stream_slice=StreamSlice(partition={}, cursor_slice={}),
+            next_page_token=None,
+        )
+
+        if isinstance(pk_value, str):
+            fetch_path = f"{base_path.rstrip('/')}/{str(pk_value).lstrip('/')}"
+        elif isinstance(pk_value, Mapping):
+            sorted_values = [str(pk_value[key]).lstrip("/") for key in sorted(pk_value.keys())]
+            pk_path_segment = "/".join(sorted_values)
+            fetch_path = f"{base_path.rstrip('/')}/{pk_path_segment}"
+        else:
+            raise ValueError(f"pk_value must be a string or dict, got {type(pk_value).__name__}")
+
+        # Single-record fetch doesn't involve partitioning, so we pass an empty StreamSlice
+        stream_slice = StreamSlice(partition={}, cursor_slice={})
+
+        # send_request() may return None when the error handler chooses to IGNORE a response
+        response: requests.Response | None = self.requester.send_request(
+            path=fetch_path,
+            stream_state={},
+            stream_slice=stream_slice,
+            next_page_token=None,
+            request_headers=self._request_headers(
+                stream_state={},
+                stream_slice=stream_slice,
+                next_page_token=None,
+            ),
+            request_params=self._request_params(
+                stream_state={},
+                stream_slice=stream_slice,
+                next_page_token=None,
+            ),
+            request_body_data=self._request_body_data(
+                stream_state={},
+                stream_slice=stream_slice,
+                next_page_token=None,
+            ),
+            request_body_json=self._request_body_json(
+                stream_state={},
+                stream_slice=stream_slice,
+                next_page_token=None,
+            ),
+            log_formatter=self.log_formatter,
+        )
+
+        if not response:
+            raise RecordNotFoundException(
+                f"Record with primary key {pk_value} not found (no response)"
+            )
+
+        records_iter: Iterable[Record] = self._parse_response(
+            response=response,
+            stream_state={},
+            records_schema=records_schema,
+            stream_slice=stream_slice,
+            next_page_token=None,
+        )
+
+        first_record: Record | None = next(iter(records_iter), None)
+        if not first_record:
+            raise RecordNotFoundException(
+                f"Record with primary key {pk_value} not found (empty response)"
+            )
+
+        return dict(first_record.data)
+
 
 def _deep_merge(
     target: MutableMapping[str, Any], source: Union[Record, MutableMapping[str, Any]]

airbyte_cdk/sources/streams/concurrent/abstract_stream.py

@@ -90,3 +90,24 @@ def check_availability(self) -> StreamAvailability:
         """
         :return: If the stream is available and if not, why
         """
+
+    def fetch_record(self, pk_value: Any) -> Mapping[str, Any]:
+        """
+        Fetch a single record by primary key value.
+
+        Args:
+            pk_value: The primary key value. Can be:
+                     - str: For simple single-field primary keys (e.g., "123")
+                     - Mapping[str, Any]: For composite primary keys (e.g., {"company_id": "123", "property": "status"})
+
+        Returns:
+            The fetched record as a dict
+
+        Raises:
+            NotImplementedError: If the stream doesn't support fetching individual records
+            RecordNotFoundException: If the record is not found (404 response)
+        """
+        raise NotImplementedError(
+            f"Stream {self.name} does not support fetching individual records. "
+            "Only declarative streams with SimpleRetriever currently support this operation."
+        )