From c0ee370f83892aeeba4a63380eddd37c8105855c Mon Sep 17 00:00:00 2001
From: QianZhu <qian@lancedb.com>
Date: Thu, 12 Dec 2024 10:52:06 -0800
Subject: [PATCH] docs: improve schema evolution api examples (#1929)

---
 docs/src/guides/tables.md              | 10 +++++-----
 nodejs/examples/basic.test.ts          |  4 +++-
 python/python/tests/docs/test_basic.py | 16 ++++++++++++++++
 3 files changed, 24 insertions(+), 6 deletions(-)

diff --git a/docs/src/guides/tables.md b/docs/src/guides/tables.md
index 13cced31..f4431771 100644
--- a/docs/src/guides/tables.md
+++ b/docs/src/guides/tables.md
@@ -804,12 +804,13 @@ a table:
 
 You can add new columns to the table with the `add_columns` method. New columns
 are filled with values based on a SQL expression. For example, you can add a new
-column `y` to the table and fill it with the value of `x + 1`.
+column `y` to the table, fill it with the value of `x * 2` and set the expected 
+data type for it.
 
 === "Python"
 
     ```python
-    table.add_columns({"double_price": "price * 2"})
+    --8<-- "python/python/tests/docs/test_basic.py:add_columns"
     ```
     **API Reference:** [lancedb.table.Table.add_columns][]
 
@@ -849,8 +850,7 @@ rewriting the column, which can be a heavy operation.
 
     ```python
     import pyarrow as pa
-    table.alter_column({"path": "double_price", "rename": "dbl_price",
-                        "data_type": pa.float32(), "nullable": False})
+    --8<-- "python/python/tests/docs/test_basic.py:alter_columns"
     ```
     **API Reference:** [lancedb.table.Table.alter_columns][]
 
@@ -873,7 +873,7 @@ will remove the column from the schema.
 === "Python"
 
     ```python
-    table.drop_columns(["dbl_price"])
+     --8<-- "python/python/tests/docs/test_basic.py:drop_columns"
     ```
     **API Reference:** [lancedb.table.Table.drop_columns][]
 
diff --git a/nodejs/examples/basic.test.ts b/nodejs/examples/basic.test.ts
index d0485142..3754eb3a 100644
--- a/nodejs/examples/basic.test.ts
+++ b/nodejs/examples/basic.test.ts
@@ -119,7 +119,9 @@ test("basic table examples", async () => {
 
     {
       // --8<-- [start:add_columns]
-      await tbl.addColumns([{ name: "double_price", valueSql: "price * 2" }]);
+      await tbl.addColumns([
+        { name: "double_price", valueSql: "cast((price * 2) as Float)" },
+      ]);
       // --8<-- [end:add_columns]
       // --8<-- [start:alter_columns]
       await tbl.alterColumns([
diff --git a/python/python/tests/docs/test_basic.py b/python/python/tests/docs/test_basic.py
index 4e58a541..3f1280a2 100644
--- a/python/python/tests/docs/test_basic.py
+++ b/python/python/tests/docs/test_basic.py
@@ -75,6 +75,22 @@ def test_quickstart():
             for _ in range(1000)
         ]
     )
+    # --8<-- [start:add_columns]
+    tbl.add_columns({"double_price": "cast((price * 2) as float)"})
+    # --8<-- [end:add_columns]
+    # --8<-- [start:alter_columns]
+    tbl.alter_columns(
+        {
+            "path": "double_price",
+            "rename": "dbl_price",
+            "data_type": pa.float64(),
+            "nullable": True,
+        }
+    )
+    # --8<-- [end:alter_columns]
+    # --8<-- [start:drop_columns]
+    tbl.drop_columns(["dbl_price"])
+    # --8<-- [end:drop_columns]
     # --8<-- [start:create_index]
     # Synchronous client
     tbl.create_index(num_sub_vectors=1)