docs(examples): add example and see also ref for Table.execute

Author: IndexSeek

ibis/expr/types/core.py

@@ -414,6 +414,41 @@ def execute(
             Mapping of scalar parameter expressions to value
         kwargs
             Keyword arguments
+
+        Examples
+        --------
+        >>> import ibis
+        >>> t = ibis.examples.penguins.fetch()
+        >>> t.execute()
+               species     island  bill_length_mm  ...  body_mass_g     sex  year
+        0       Adelie  Torgersen            39.1  ...       3750.0    male  2007
+        1       Adelie  Torgersen            39.5  ...       3800.0  female  2007
+        2       Adelie  Torgersen            40.3  ...       3250.0  female  2007
+        3       Adelie  Torgersen             NaN  ...          NaN    None  2007
+        4       Adelie  Torgersen            36.7  ...       3450.0  female  2007
+        ..         ...        ...             ...  ...          ...     ...   ...
+        339  Chinstrap      Dream            55.8  ...       4000.0    male  2009
+        340  Chinstrap      Dream            43.5  ...       3400.0  female  2009
+        341  Chinstrap      Dream            49.6  ...       3775.0    male  2009
+        342  Chinstrap      Dream            50.8  ...       4100.0    male  2009
+        343  Chinstrap      Dream            50.2  ...       3775.0  female  2009
+        [344 rows x 8 columns]
+
+        Scalar parameters can be supplied dynamically during execution.
+        >>> species = ibis.param("string")
+        >>> expr = t.filter(t.species == species).order_by(t.bill_length_mm)
+        >>> expr.execute(limit=3, params={species: "Gentoo"})
+          species  island  bill_length_mm  ...  body_mass_g     sex  year
+        0  Gentoo  Biscoe            40.9  ...         4650  female  2007
+        1  Gentoo  Biscoe            41.7  ...         4700  female  2009
+        2  Gentoo  Biscoe            42.0  ...         4150  female  2007
+        <BLANKLINE>
+        [3 rows x 8 columns]
+
+        See Also
+        --------
+        [`Table.to_pandas()`](./expression-tables.qmd#ibis.expr.types.relations.Table.to_pandas)
+        [`Value.to_pandas()`](./expression-generic.qmd#ibis.expr.types.generic.Value.to_pandas)
         """
         return self._find_backend(use_default=True).execute(
             self, limit=limit, params=params, **kwargs