chore: document Expr.__getitem__ (get a field of a struct array) (#5344)

danking · web-flow · commit 68873b30a6f9 · 2025-11-14T20:28:39.000Z
<img width="827" height="796" alt="Screenshot 2025-11-14 at 10 55 55 AM" src="https://github.com/user-attachments/assets/6985750f-6b2b-4351-9c92-1be6ff84f140" /> Signed-off-by: Daniel King <dan@spiraldb.com>
diff --git a/docs/api/python/expr.rst b/docs/api/python/expr.rst
@@ -32,3 +32,36 @@ the following expression represents the set of rows for which the `age` column l
 .. autofunction:: vortex.expr.literal
 
 .. autoclass:: vortex.expr.Expr
+   :members:
+
+   .. py:method:: __getitem__ (name, /)
+
+      Extract a field of a struct array.
+
+      :parameters:
+
+          - **name** (:class:`.str`) -- The name of the field.
+
+      :return type:
+
+          :class:`.vortex.Expr`
+
+      .. rubric:: Examples
+
+      >>> import vortex as vx
+      >>> import vortex.expr as ve
+      >>> import pyarrow as pa
+      >>>
+      >>> array = pa.array([
+      ...     {"x": 1, "y": {"yy": "a"}},
+      ...     {"x": 2, "y": {"yy": "b"}},
+      ... ])
+      >>>
+      >>> vx.io.write(vx.array(array), '/tmp/foo.vortex')
+      >>> (vx.file.open('/tmp/foo.vortex')
+      ...    .scan(expr=vx.expr.column("y")["yy"] == "a")
+      ...    .read_all()
+      ...    .to_pylist()
+      ... )
+      [{'x': 1, 'y': {'yy': 'a'}}]
+
diff --git a/vortex-python/src/expr/mod.rs b/vortex-python/src/expr/mod.rs
@@ -159,6 +159,8 @@ impl PyExpr {
         py_binary_operator(self_, Operator::Or, coerce_expr(right)?)
     }
 
+    // Special methods docstrings cannot be defined in Rust. Write a docstring in the corresponding
+    // rST file. https://github.com/PyO3/pyo3/issues/4326
     fn __getitem__(self_: PyRef<'_, Self>, field: String) -> PyResult<PyExpr> {
         get_item(field, self_.clone())
     }
@@ -236,6 +238,10 @@ pub fn root() -> PyExpr {
 /// >>> ve.column("age")
 /// <vortex.Expr object at ...>
 /// ```
+///
+/// .. seealso::
+///
+///    Use :meth:`.vortex.expr.Expr.__getitem__` to retrieve a field of a struct array.
 #[pyfunction]
 pub fn column<'py>(name: &Bound<'py, PyString>) -> PyResult<Bound<'py, PyExpr>> {
     let py = name.py();
