Update SDK to version 0.36.0rc0

Author: Roboto-Bot-O

CHANGELOG.md

@@ -1,6 +1,23 @@
 # Changelog
 
+# 0.36.0rc0
+## Breaking Changes
+  - `MessagePath.parents()` now requires a `list[str]` (`path_in_schema`) instead of a dot-delimited `str`. This reflects the shift from ambiguous dot-separated paths to explicit schema path components for correct handling of nested and dot-containing field names. If you were calling `MessagePath.parents("pose.position.x")`, update to `MessagePath.parents(["pose", "position", "x"])`. Passing a string now raises a `TypeError` with guidance on how to migrate.
+  - `MessagePath.parts()` has been removed. Use `MessagePathRecord.path_in_schema` directly to obtain path components.
+
+## Features Added
+  - Introduced `QueryContentMode`, allowing search endpoints to return Roboto entities with or without custom metadata. Initial support is for dataset queries in particular, since datasets can store large amounts of `metadata`, which is known to affect search latency and response size. More entity types will be supported in the future.
+  - Improved `Topic.get_data` and `Topic.get_data_as_df` performance for Parquet-backed data.
+  - `Topic.create_from_df()` and `File.add_topic()` now support DataFrames containing nested column types (structs, lists, list<struct>). Previously, only top-level primitive columns were fully supported.
+  - `AddMessagePathRequest` now accepts a `path_in_schema` field to explicitly specify the field's location in the source data schema as an ordered list of path components. Relatedly, `Topic.add_message_path()` and `Topic.update_message_path()` now accept an optional `path_in_schema` parameter.
+
+## Bugs Fixed
+  - Updated behavior to not retry requests when server response exceeds the maximum safe payload size.
+
 # 0.35.2
+## Features Added
+- Added limit, sort_by and sort_direction parameters to `v1/datasets/<dataset_id>/files/query`
+
 # 0.35.1
 ### Simplified File Transfer API
 
@@ -21,7 +38,6 @@ File upload and download operations have been simplified. The high-level methods
 
 ## Features Added
   - Added generic file upload API endpoints (`/v1/files/upload/*`) that support uploading files to any association type (datasets, topics, etc.), replacing the dataset-specific upload endpoints.
-  - Added limit, sort_by and sort_direction parameters to `v1/datasets/<dataset_id>/files/query`
 
 ## Bugs Fixed
   - CLI version checker now queries GitHub Releases instead of PyPI, ensuring users are only prompted to upgrade to CLI versions that are actually published and available.

RELEASE_NOTES.md

@@ -1,3 +1,14 @@
-# 0.35.2
+# 0.36.0rc0
+## Breaking Changes
+  - `MessagePath.parents()` now requires a `list[str]` (`path_in_schema`) instead of a dot-delimited `str`. This reflects the shift from ambiguous dot-separated paths to explicit schema path components for correct handling of nested and dot-containing field names. If you were calling `MessagePath.parents("pose.position.x")`, update to `MessagePath.parents(["pose", "position", "x"])`. Passing a string now raises a `TypeError` with guidance on how to migrate.
+  - `MessagePath.parts()` has been removed. Use `MessagePathRecord.path_in_schema` directly to obtain path components.
+
 ## Features Added
-- Added limit, sort_by and sort_direction parameters to `v1/datasets/<dataset_id>/files/query`
+  - Introduced `QueryContentMode`, allowing search endpoints to return Roboto entities with or without custom metadata. Initial support is for dataset queries in particular, since datasets can store large amounts of `metadata`, which is known to affect search latency and response size. More entity types will be supported in the future.
+  - Improved `Topic.get_data` and `Topic.get_data_as_df` performance for Parquet-backed data.
+  - `Topic.create_from_df()` and `File.add_topic()` now support DataFrames containing nested column types (structs, lists, list<struct>). Previously, only top-level primitive columns were fully supported.
+  - `AddMessagePathRequest` now accepts a `path_in_schema` field to explicitly specify the field's location in the source data schema as an ordered list of path components. Relatedly, `Topic.add_message_path()` and `Topic.update_message_path()` now accept an optional `path_in_schema` parameter.
+
+## Bugs Fixed
+  - Updated behavior to not retry requests when server response exceeds the maximum safe payload size.
+

build-support/lockfiles/python-default.lock

@@ -27,14 +27,20 @@ class RobotoApiVersion(StrEnum):
     v2026_01_02 = "2026-01-02"
     """Release date for v0.35.0 of the Roboto Python SDK"""
 
+    v2026_02_02 = "2026-02-02"
+    """Content mode introduced for query APIs."""
+
+    v2026_02_11 = "2026-02-11"
+    """path_in_schema is now a required field on AddMessagePathRequest"""
+
     @staticmethod
     def latest() -> RobotoApiVersion:
         """Get the latest available API version.
 
         Returns:
             The most recent API version supported by the platform.
         """
-        return RobotoApiVersion.v2026_01_02
+        return RobotoApiVersion.v2026_02_11
 
     def is_latest(self) -> bool:
         """Check if this API version is the latest available version.

src/roboto/api_version.py

@@ -8,15 +8,16 @@
 import json
 import typing
 
-from ...domain.datasets import Dataset
 from ...query import (
     Comparator,
     Condition,
     ConditionGroup,
     ConditionOperator,
+    QueryContentMode,
     QuerySpecification,
     SortDirection,
 )
+from ...roboto_search import RobotoSearch
 from ..command import (
     KeyValuePairsAction,
     RobotoCommand,
@@ -27,6 +28,7 @@
 
 def search(args, context: CLIContext, parser: argparse.ArgumentParser):
     conditions: list[typing.Union[Condition, ConditionGroup]] = []
+
     if args.metadata:
         for key, value in args.metadata.items():
             conditions.append(
@@ -50,18 +52,19 @@ def search(args, context: CLIContext, parser: argparse.ArgumentParser):
     query_args: dict[str, typing.Any] = {
         "sort_direction": SortDirection.Descending,
     }
+
     if conditions:
         if len(conditions) == 1:
             query_args["condition"] = conditions[0]
         else:
             query_args["condition"] = ConditionGroup(conditions=conditions, operator=ConditionOperator.And)
 
     query = QuerySpecification(**query_args)
-    results = Dataset.query(
-        spec=query,
-        roboto_client=context.roboto_client,
-        owner_org_id=args.org,
-    )
+    searcher = RobotoSearch.for_roboto_client(context.roboto_client, args.org)
+
+    # Fetch dataset metadata, since we want to dump all dataset fields as JSON on the cmdline
+    results = searcher.find_datasets(query, content_mode=QueryContentMode.RecordWithMeta)
+
     print(json.dumps([result.to_dict() for result in results], indent=2))
 
 

src/roboto/cli/datasets/search.py

@@ -34,7 +34,7 @@
     NoopProgressMonitor,
     TqdmProgressMonitor,
 )
-from ...query import QuerySpecification
+from ...query import DEFAULT_PAGE_SIZE, QueryContentMode, QuerySpecification
 from ...sentinels import (
     NotSet,
     NotSetType,
@@ -98,6 +98,7 @@ class Dataset:
 
     __roboto_client: RobotoClient
     __record: DatasetRecord
+    __content_mode: QueryContentMode
     __file_service: FileService
 
     @classmethod
@@ -350,7 +351,7 @@ def query(
             Found dataset: Other Roboto Test
         """
         roboto_client = RobotoClient.defaulted(roboto_client)
-        spec = spec if spec is not None else QuerySpecification()
+        spec = spec if spec is not None else QuerySpecification(limit=DEFAULT_PAGE_SIZE)
 
         known = set(DatasetRecord.model_fields.keys())
         actual = set()
@@ -386,17 +387,22 @@ def query(
     def __eq__(self, other: object) -> bool:
         if not isinstance(other, Dataset):
             return False
-        return self.record == other.record
+
+        # Only compare core dataset entity fields
+        exclude_meta: dict[str, typing.Any] = {"metadata": dict()}
+        return self.record.model_copy(update=exclude_meta) == other.record.model_copy(update=exclude_meta)
 
     def __init__(
         self,
         record: DatasetRecord,
         roboto_client: typing.Optional[RobotoClient] = None,
         file_service: typing.Optional[FileService] = None,
+        content_mode: typing.Optional[QueryContentMode] = None,
     ) -> None:
         self.__roboto_client = RobotoClient.defaulted(roboto_client)
         self.__file_service = file_service or FileService(self.__roboto_client)
         self.__record = record
+        self.__content_mode = content_mode or QueryContentMode.RecordWithMeta
 
     def __repr__(self) -> str:
         return self.__record.model_dump_json()
@@ -454,7 +460,26 @@ def metadata(self) -> dict[str, typing.Any]:
         Returns a copy of the dataset's metadata dictionary containing arbitrary
         key-value pairs for storing custom information. Supports nested structures
         and dot notation for accessing nested fields.
+
+        Note: this attribute is kept for backward compatibility. Prefer :py:meth:`get_metadata()`,
+        since metadata may need to be loaded on-demand from the server.
         """
+
+        return self.get_metadata()
+
+    def get_metadata(self) -> dict[str, typing.Any]:
+        """Return custom metadata associated with this dataset.
+
+        Returns a copy of the dataset's metadata dictionary containing arbitrary
+        key-value pairs for storing custom information. Supports nested structures
+        and dot notation for accessing nested fields.
+        """
+
+        if self.__content_mode is not QueryContentMode.RecordWithMeta:
+            # Force metadata to be fetched from the DB.
+            self.refresh()
+            self.__content_mode = QueryContentMode.RecordWithMeta
+
         return self.__record.metadata.copy()
 
     @property
@@ -552,7 +577,9 @@ def create_directory(
             Create a directory with intermediate directories:
 
             >>> directory = dataset.create_directory(
-            ...     name="final", parent_path="path/to/deep", create_intermediate_dirs=True
+            ...     name="final",
+            ...     parent_path=pathlib.Path("path/to/deep"),
+            ...     create_intermediate_dirs=True,
             ... )
             >>> print(directory.relative_path)
             path/to/deep/final

src/roboto/domain/datasets/dataset.py

@@ -58,54 +58,45 @@ class MessagePath:
     __topic_data_service: TopicDataService
 
     @staticmethod
-    def parents(path: str) -> list[str]:
-        """Get parent paths for a message path in dot notation.
+    def parents(path_in_schema: list[str]) -> list[str]:
+        """Get parent paths for a message path.
 
-        Given a message path in dot notation, returns a list of its parent paths
-        ordered from most specific to least specific.
+        Given a path_in_schema (list of path components), returns a list of its
+        parent paths ordered from most specific to least specific.
 
         Args:
-            path: Message path in dot notation (e.g., "pose.pose.position.x").
+            path_in_schema: List of path components (e.g., ["pose", "pose", "position", "x"]).
 
         Returns:
             List of parent paths in dot notation, ordered from most to least specific.
 
+        Raises:
+            TypeError: If a string is passed instead of a list. This method previously
+                accepted a dot-delimited string; passing a string now would silently
+                iterate over its characters and produce wrong results.
+
         Examples:
-            >>> path = "pose.pose.position.x"
-            >>> MessagePath.parents(path)
+            >>> path_in_schema = ["pose", "pose", "position", "x"]
+            >>> MessagePath.parents(path_in_schema)
             ['pose.pose.position', 'pose.pose', 'pose']
 
             >>> # Single level path has no parents
-            >>> MessagePath.parents("velocity")
+            >>> MessagePath.parents(["velocity"])
             []
         """
-        parent_parts = MessagePath.parts(path)[:-1]
+        # Guard against callers using the old str-based signature.
+        # Strings are iterable in Python, so passing one wouldn't raise but would
+        # silently produce nonsense by iterating over individual characters.
+        if isinstance(path_in_schema, str):
+            raise TypeError(
+                "MessagePath.parents() now requires a list[str] (path_in_schema), "
+                "not a dot-delimited string. Use MessagePathRecord.path_in_schema "
+                "or split your path into components."
+            )
+
+        parent_parts = path_in_schema[:-1]
         return [MessagePath.DELIMITER.join(parent_parts[:i]) for i in range(len(parent_parts), 0, -1)]
 
-    @staticmethod
-    def parts(path: str) -> list[str]:
-        """Split message path in dot notation into its constituent parts.
-
-        Splits a message path string into individual components, useful for
-        programmatic manipulation of message path hierarchies.
-
-        Args:
-            path: Message path in dot notation (e.g., "pose.pose.position.x").
-
-        Returns:
-            List of path components in order from root to leaf.
-
-        Examples:
-            >>> path = "pose.pose.position.x"
-            >>> MessagePath.parts(path)
-            ['pose', 'pose', 'position', 'x']
-
-            >>> # Single component path
-            >>> MessagePath.parts("velocity")
-            ['velocity']
-        """
-        return path.split(MessagePath.DELIMITER)
-
     @classmethod
     def from_id(
         cls,

src/roboto/domain/topics/message_path.py

@@ -95,6 +95,10 @@ class AddMessagePathRequest(pydantic.BaseModel):
         canonical_data_type: Normalized Roboto data type that enables specialized
             platform features for maps, images, timestamps, and other data.
         metadata: Initial key-value pairs to associate with the message path.
+        path_in_schema: List of path components representing the field's location
+            in the original data schema. Unlike message_path, which assumes dots
+            separate path parts implying nested data, this preserves the exact path
+            from the source data for accurate attribute access.
     """
 
     message_path: str
@@ -105,6 +109,10 @@ class AddMessagePathRequest(pydantic.BaseModel):
         description="Initial key-value pairs to associate with this topic message path for discovery and search, e.g. "
         + "`{ 'min': 0.71, 'max': 1.77, 'classification': 'my-custom-classification-tag' }`",
     )
+    path_in_schema: list[str] = pydantic.Field(
+        description="List of path components representing the field's location in the source data schema. "
+        "For nested fields like 'position.x', this would be ['position', 'x'].",
+    )
 
     model_config = pydantic.ConfigDict(extra="ignore")
 
@@ -133,6 +141,12 @@ class UpdateMessagePathRequest(pydantic.BaseModel):
     ability to interpret and visualize the data.
     """
 
+    path_in_schema: typing.Union[list[str], NotSetType] = NotSet
+    """List of path components representing the field's location in the source data schema (optional).
+
+    For nested fields like 'position.x', this would be ['position', 'x'].
+    """
+
     model_config = pydantic.ConfigDict(extra="ignore", json_schema_extra=NotSetType.openapi_schema_modifier)
 
     def has_updates(self) -> bool:
@@ -145,6 +159,7 @@ def has_updates(self) -> bool:
         return (
             is_set(self.data_type)
             or is_set(self.canonical_data_type)
+            or is_set(self.path_in_schema)
             or (is_set(self.metadata_changeset) and self.metadata_changeset.has_changes())
         )
 

src/roboto/domain/topics/operations.py

@@ -5,7 +5,7 @@
 # file, You can obtain one at https://mozilla.org/MPL/2.0/.
 
 from .arrow_to_roboto import (
-    field_to_message_path_request,
+    generate_message_path_requests,
 )
 from .ingestion import (
     make_topic_filename_safe,
@@ -17,7 +17,7 @@
 )
 
 __all__ = (
-    "field_to_message_path_request",
+    "generate_message_path_requests",
     "make_topic_filename_safe",
     "ParquetParser",
     "ParquetTopicReader",