docs: improve external function documentation with end-to-end examples and protocol fix (#3153)

* docs: add end-to-end Python UDF server example for external function

* docs: fix external function protocol description, replace HTTP/HTTPS with Arrow Flight

Author: wubx

docs/cn/sql-reference/10-sql-commands/00-ddl/11-external-function/ddl-create-function.md

@@ -35,12 +35,59 @@ CREATE [ OR REPLACE ] FUNCTION [ IF NOT EXISTS ] <function_name>
 
 ## 示例
 
-以下示例创建一个外部函数，用于计算两个整数的最大公约数（GCD）：
+以下示例完整演示如何创建一个计算最大公约数（GCD）的外部函数。
+
+### 第一步：启动 Python UDF 服务
+
+安装 `databend-udf` 包：
+
+```bash
+pip install databend-udf
+```
+
+创建文件 `udf_server.py`：
+
+```python
+from databend_udf import udf, UDFServer
+
+@udf(
+    input_types=["INT", "INT"],
+    result_type="INT",
+    skip_null=True,
+)
+def gcd(x: int, y: int) -> int:
+    while y != 0:
+        (x, y) = (y, x % y)
+    return x
+
+if __name__ == '__main__':
+    server = UDFServer("0.0.0.0:8815")
+    server.add_function(gcd)
+    server.serve()
+```
+
+启动服务：
+
+```bash
+python udf_server.py
+```
+
+### 第二步：在 Databend 中注册函数
 
 ```sql
-CREATE FUNCTION gcd AS (INT, INT) 
-    RETURNS INT 
-    LANGUAGE python 
-    HANDLER = 'gcd' 
+CREATE FUNCTION gcd AS (INT, INT)
+    RETURNS INT
+    LANGUAGE python
+    HANDLER = 'gcd'
     ADDRESS = 'http://localhost:8815';
 ```
+
+### 第三步：调用函数
+
+```sql
+SELECT gcd(48, 18);
+-- 返回：6
+
+SELECT gcd(100, 75);
+-- 返回：25
+```

docs/cn/sql-reference/10-sql-commands/00-ddl/11-external-function/index.md

@@ -13,5 +13,5 @@ title: 外部函数（External Function）
 | [DROP EXTERNAL FUNCTION](ddl-drop-function.md) | 移除一个外部函数（External Function） |
 
 :::note
-Databend 中的外部函数（External Function）允许你通过与 HTTP/HTTPS 端点集成的外部服务来扩展功能，从而利用外部处理能力。
+Databend 外部函数允许你用自定义逻辑扩展 SQL，逻辑运行在远程服务器上，通过 [Apache Arrow Flight](https://arrow.apache.org/docs/format/Flight.html) 协议与 Databend 通信。远程处理程序可以用任意语言实现，Python 是最常见的选择，可通过 [databend-udf](https://pypi.org/project/databend-udf) 包快速上手。
 :::

docs/en/sql-reference/10-sql-commands/00-ddl/11-external-function/ddl-create-function.md

@@ -35,12 +35,59 @@ CREATE [ OR REPLACE ] FUNCTION [ IF NOT EXISTS ] <function_name>
 
 ## Examples
 
-This example creates an external function that calculates the greatest common divisor (GCD) of two integers:
+This example walks through a complete end-to-end setup for an external function that calculates the greatest common divisor (GCD) of two integers.
+
+### Step 1: Set Up the Python UDF Server
+
+Install the `databend-udf` package:
+
+```bash
+pip install databend-udf
+```
+
+Create a file `udf_server.py` with the following content:
+
+```python
+from databend_udf import udf, UDFServer
+
+@udf(
+    input_types=["INT", "INT"],
+    result_type="INT",
+    skip_null=True,
+)
+def gcd(x: int, y: int) -> int:
+    while y != 0:
+        (x, y) = (y, x % y)
+    return x
+
+if __name__ == '__main__':
+    server = UDFServer("0.0.0.0:8815")
+    server.add_function(gcd)
+    server.serve()
+```
+
+Start the server:
+
+```bash
+python udf_server.py
+```
+
+### Step 2: Register the Function in Databend
 
 ```sql
-CREATE FUNCTION gcd AS (INT, INT) 
-    RETURNS INT 
-    LANGUAGE python 
-    HANDLER = 'gcd' 
+CREATE FUNCTION gcd AS (INT, INT)
+    RETURNS INT
+    LANGUAGE python
+    HANDLER = 'gcd'
     ADDRESS = 'http://localhost:8815';
 ```
+
+### Step 3: Call the Function
+
+```sql
+SELECT gcd(48, 18);
+-- Returns: 6
+
+SELECT gcd(100, 75);
+-- Returns: 25
+```

docs/en/sql-reference/10-sql-commands/00-ddl/11-external-function/index.md

@@ -13,5 +13,5 @@ This page provides a comprehensive overview of External Function operations in D
 | [DROP EXTERNAL FUNCTION](ddl-drop-function.md) | Removes an external function |
 
 :::note
-External Functions in Databend allow you to extend functionality by integrating with external services through HTTP/HTTPS endpoints, enabling you to leverage external processing capabilities.
+External Functions in Databend allow you to extend SQL with custom logic running on a remote server. The server communicates with Databend over the [Apache Arrow Flight](https://arrow.apache.org/docs/format/Flight.html) protocol. The remote handler can be written in any language — Python is the most common choice via the [databend-udf](https://pypi.org/project/databend-udf) package.
 :::