review fixes

python/python/lancedb/remote/table.py

@@ -63,7 +63,16 @@ from ..query import (
     LanceTakeQueryBuilder,
     LanceVectorQueryBuilder,
 )
-from ..table import AsyncTable, BlobMode, Branches, IndexStatistics, Query, Table, Tags
+from ..table import (
+    AsyncTable,
+    BlobMode,
+    Branches,
+    IndexStatistics,
+    Query,
+    Table,
+    TableStatistics,
+    Tags,
+)
 from ..types import BaseTokenizerType
 
 
@@ -1010,7 +1019,7 @@ class RemoteTable(Table):
     ):
         return LOOP.run(self._table.wait_for_index(index_names, timeout))
 
-    def stats(self):
+    def stats(self) -> TableStatistics:
         return LOOP.run(self._table.stats())
 
     @property

python/python/lancedb/table.py

@@ -1018,6 +1018,13 @@ class Table(ABC):
     def stats(self) -> TableStatistics:
         """
         Retrieve table and fragment statistics.
+
+        Returns
+        -------
+        TableStatistics
+            Subscript access (``stats["total_bytes"]``) is still supported for
+            backwards compatibility with the older API, which returned a
+            dictionary.
         """
         raise NotImplementedError
 
@@ -4948,8 +4955,15 @@ class AsyncTable:
     async def stats(self) -> TableStatistics:
         """
         Retrieve table and fragment statistics.
+
+        Returns
+        -------
+        TableStatistics
+            Subscript access (``stats["total_bytes"]``) is still supported for
+            backwards compatibility with the older API, which returned a
+            dictionary.
         """
-        return await self._inner.stats()
+        return TableStatistics._from_dict(await self._inner.stats())
 
     async def uri(self) -> str:
         """
@@ -6146,13 +6160,19 @@ class TableStatistics:
         Statistics about fragments in the table.
     column_bytes: dict[str, int] | None
         The compressed on-disk bytes of each column, keyed by dotted field path
-        ("meta", "meta.geo", "meta.geo.lat"). Every nesting level gets an entry
-        covering the field's own bytes plus its whole subtree, so a struct
-        reports its total while its children report the breakdown (the
-        top-level entries alone sum to ``total_bytes``). Counts data-file bytes
-        only: blob sidecar payloads and index files are not included, and blob
-        columns therefore report just their descriptor bytes. ``None`` when the
-        backend provides no per-column breakdown (e.g. older remote servers).
+        ("meta", "meta.geo", "meta.geo.lat"). A struct's subfields each get their
+        own entry, and every entry covers the field's own bytes plus its whole
+        subtree, so a struct reports its total while its children report the
+        breakdown (the top-level entries alone sum to ``total_bytes``). List
+        elements are not broken out: a list column reports a single total with
+        its element bytes rolled in. Path segments containing anything other
+        than letters, digits, or ``_`` are backtick-quoted, so a subfield named
+        ``a.b`` under ``meta`` is keyed as ``meta.`a.b```.
+
+        Counts data-file bytes only: blob sidecar payloads and index files are
+        not included, and blob columns therefore report just their descriptor
+        bytes. ``None`` when the backend provides no per-column breakdown (e.g.
+        older remote servers).
     """
 
     total_bytes: int
@@ -6161,6 +6181,26 @@ class TableStatistics:
     fragment_stats: FragmentStatistics
     column_bytes: Optional[Dict[str, int]] = None
 
+    @classmethod
+    def _from_dict(cls, stats: Dict[str, Any]) -> TableStatistics:
+        fragment_stats = stats["fragment_stats"]
+        return cls(
+            total_bytes=stats["total_bytes"],
+            num_rows=stats["num_rows"],
+            num_indices=stats["num_indices"],
+            fragment_stats=FragmentStatistics(
+                num_fragments=fragment_stats["num_fragments"],
+                num_small_fragments=fragment_stats["num_small_fragments"],
+                lengths=FragmentSummaryStats(**fragment_stats["lengths"]),
+            ),
+            column_bytes=stats.get("column_bytes"),
+        )
+
+    # This exists for backwards compatibility with an older API, which returned
+    # a dictionary instead of a class.
+    def __getitem__(self, key):
+        return getattr(self, key)
+
 
 @dataclass
 class FragmentStatistics:
@@ -6182,6 +6222,11 @@ class FragmentStatistics:
     num_small_fragments: int
     lengths: FragmentSummaryStats
 
+    # This exists for backwards compatibility with an older API, which returned
+    # a dictionary instead of a class.
+    def __getitem__(self, key):
+        return getattr(self, key)
+
 
 @dataclass
 class FragmentSummaryStats:
@@ -6214,6 +6259,11 @@ class FragmentSummaryStats:
     p75: int
     p99: int
 
+    # This exists for backwards compatibility with an older API, which returned
+    # a dictionary instead of a class.
+    def __getitem__(self, key):
+        return getattr(self, key)
+
 
 class Tags:
     """

python/python/tests/test_remote_db.py

@@ -20,6 +20,7 @@ from lancedb.conftest import MockTextEmbeddingFunction
 from lancedb.query import ColumnOrdering
 from lancedb.remote import ClientConfig
 from lancedb.remote.errors import HttpError, RetryError
+from lancedb.table import TableStatistics
 import pytest
 import pyarrow as pa
 
@@ -1009,9 +1010,9 @@ def test_stats():
         table = db.create_table("test", [{"id": 1}])
         res = table.stats()
         print(f"{res=}")
-        # A server that omits the per-column breakdown reports it as None
-        # rather than leaving the key out.
-        assert res == {**stats, "column_bytes": None}
+        # A server that omits the per-column breakdown reports it as None.
+        assert res == TableStatistics._from_dict({**stats, "column_bytes": None})
+        assert res.column_bytes is None
 
 
 def test_stats_column_bytes():
@@ -1053,7 +1054,11 @@ def test_stats_column_bytes():
 
     with mock_lancedb_connection(handler) as db:
         table = db.create_table("test", [{"id": 1}])
-        assert table.stats() == stats
+        res = table.stats()
+        # The dotted paths are opaque to the client: whatever breakdown the
+        # server sends is passed through verbatim.
+        assert res == TableStatistics._from_dict(stats)
+        assert res.column_bytes == stats["column_bytes"]
 
 
 @contextlib.contextmanager

python/python/tests/test_table.py

@@ -24,7 +24,12 @@ from lancedb.db import AsyncConnection, DBConnection
 from lancedb.embeddings import EmbeddingFunctionConfig, EmbeddingFunctionRegistry
 from lancedb.expr import col, lit
 from lancedb.pydantic import LanceModel, Vector
-from lancedb.table import LanceTable
+from lancedb.table import (
+    FragmentStatistics,
+    FragmentSummaryStats,
+    LanceTable,
+    TableStatistics,
+)
 from pydantic import BaseModel
 
 
@@ -3393,26 +3398,25 @@ def test_stats(mem_db: DBConnection):
     assert len(table) == 2
     stats = table.stats()
     print(f"{stats=}")
-    assert stats == {
-        "total_bytes": 60,
-        "num_rows": 2,
-        "num_indices": 0,
-        "fragment_stats": {
-            "num_fragments": 1,
-            "num_small_fragments": 1,
-            "lengths": {
-                "min": 2,
-                "max": 2,
-                "mean": 2,
-                "p25": 2,
-                "p50": 2,
-                "p75": 2,
-                "p99": 2,
-            },
-        },
+    assert stats == TableStatistics(
+        total_bytes=60,
+        num_rows=2,
+        num_indices=0,
+        fragment_stats=FragmentStatistics(
+            num_fragments=1,
+            num_small_fragments=1,
+            lengths=FragmentSummaryStats(
+                min=2, max=2, mean=2, p25=2, p50=2, p75=2, p99=2
+            ),
+        ),
         # Both columns are counted, and the two together make up total_bytes.
-        "column_bytes": {"text": 34, "id": 26},
-    }
+        column_bytes={"text": 34, "id": 26},
+    )
+    # Subscript access still works, for callers written against the older API
+    # that returned a plain dictionary.
+    assert stats["total_bytes"] == stats.total_bytes == 60
+    assert stats["fragment_stats"]["lengths"]["p99"] == 2
+    assert stats["column_bytes"] == stats.column_bytes
 
 
 def test_stats_column_bytes_nested(mem_db: DBConnection):
@@ -3430,7 +3434,8 @@ def test_stats_column_bytes_nested(mem_db: DBConnection):
         data=[{"id": i, "meta": {"a": i, "b": f"value-{i}"}} for i in range(100)],
         schema=schema,
     )
-    column_bytes = table.stats()["column_bytes"]
+    stats = table.stats()
+    column_bytes = stats.column_bytes
 
     # Nested fields get their own dotted-path entries.
     assert set(column_bytes) == {"id", "meta", "meta.a", "meta.b"}
@@ -3439,7 +3444,63 @@ def test_stats_column_bytes_nested(mem_db: DBConnection):
     # A struct's entry covers its whole subtree.
     assert column_bytes["meta"] >= column_bytes["meta.a"] + column_bytes["meta.b"]
     # Top-level entries alone sum to the table total.
-    assert column_bytes["id"] + column_bytes["meta"] == table.stats()["total_bytes"]
+    assert column_bytes["id"] + column_bytes["meta"] == stats.total_bytes
+
+
+def test_stats_column_bytes_list_elements_not_broken_out(mem_db: DBConnection):
+    """A list's element is an encoding detail, not a column, so it must not
+    appear as a redundant ``tags.item`` entry duplicating ``tags``."""
+    schema = pa.schema(
+        [
+            pa.field("id", pa.int32()),
+            pa.field("tags", pa.list_(pa.utf8())),
+            pa.field("vector", pa.list_(pa.float32(), 4)),
+        ]
+    )
+    table = mem_db.create_table(
+        "list_stats",
+        data=[
+            {"id": i, "tags": [f"tag-{i}", "shared"], "vector": [0.1] * 4}
+            for i in range(100)
+        ],
+        schema=schema,
+    )
+    stats = table.stats()
+
+    assert set(stats.column_bytes) == {"id", "tags", "vector"}
+    # The element bytes are rolled into the list column, not dropped.
+    assert stats.column_bytes["tags"] > 0
+    assert sum(stats.column_bytes.values()) == stats.total_bytes
+
+
+def test_stats_column_bytes_dotted_field_name(mem_db: DBConnection):
+    """A subfield whose name contains a dot is backtick-quoted so it stays
+    distinguishable from the nested path that spells the same way."""
+    schema = pa.schema(
+        [
+            pa.field(
+                "meta",
+                pa.struct(
+                    [
+                        pa.field("a.b", pa.int32()),
+                        pa.field("a", pa.struct([pa.field("b", pa.int32())])),
+                    ]
+                ),
+            )
+        ]
+    )
+    table = mem_db.create_table(
+        "dotted_stats",
+        data=[{"meta": {"a.b": i, "a": {"b": i * 1000}}} for i in range(100)],
+        schema=schema,
+    )
+    stats = table.stats()
+
+    # All four fields are present; naive dotted keying would collide the leaf
+    # named "a.b" with the meta -> a -> b path and silently lose one.
+    assert set(stats.column_bytes) == {"meta", "meta.`a.b`", "meta.a", "meta.a.b"}
+    assert stats.column_bytes["meta.a"] == stats.column_bytes["meta.a.b"]
+    assert stats.column_bytes["meta"] == stats.total_bytes
 
 
 @pytest.mark.asyncio
@@ -3449,8 +3510,8 @@ async def test_stats_column_bytes_async(mem_db_async: AsyncConnection):
         data=[{"text": "foo", "id": 0}, {"text": "bar", "id": 1}],
     )
     stats = await table.stats()
-    assert set(stats["column_bytes"]) == {"text", "id"}
-    assert sum(stats["column_bytes"].values()) == stats["total_bytes"]
+    assert set(stats.column_bytes) == {"text", "id"}
+    assert sum(stats.column_bytes.values()) == stats.total_bytes
 
 
 def test_create_table_empty_list_with_schema(mem_db: DBConnection):