From d1aad2b9607540daa419e593a48eaaa6ff422071 Mon Sep 17 00:00:00 2001
From: He Kaisheng <heks93@163.com>
Date: Tue, 23 Mar 2021 10:55:36 +0800
Subject: [PATCH] Add docs for downloading using multiprocessing (#146)

Co-authored-by: hekaisheng <kaisheng.hks@alibaba-inc.com>
---
 docs/source/base-sql.rst    | 22 ++++++++++++++++++++++
 docs/source/base-tables.rst | 20 ++++++++++++++++++++
 2 files changed, 42 insertions(+)

diff --git a/docs/source/base-sql.rst b/docs/source/base-sql.rst
index e7c22635..1d41412b 100644
--- a/docs/source/base-sql.rst
+++ b/docs/source/base-sql.rst
@@ -87,6 +87,28 @@ PyODPS 默认不限制能够从 Instance 读取的数据规模。对于受保护
 如果你所使用的 MaxCompute 只能支持旧 Result 接口，同时你需要读取所有数据，可将 SQL 结果写入另一张表后用读表接口读取
 （可能受到 Project 安全设置的限制）。
 
+同时，PyODPS 支持直接将运行结果数据读成 pandas DataFrame。
+
+.. code-block:: python
+
+  >>> # 直接使用 reader 的 to_pandas 方法
+  >>> with o.execute_sql('select * from dual').open_reader(tunnel=True) as reader:
+  >>>     # pd_df 类型为 pandas DataFrame
+  >>>     pd_df = reader.to_pandas()
+
+.. _sql_to_pandas_mp:
+
+如果需要使用多核加速读取速度，可以通过 `n_process` 指定使用进程数
+
+.. code-block:: python
+
+  >>> import multiprocessing
+  >>> n_process = multiprocessing.cpu_count()
+  >>> with o.execute_sql('select * from dual').open_reader(tunnel=True) as reader:
+  >>>     # n_process 指定成机器核数
+  >>>     pd_df = reader.to_pandas(n_process=n_process)
+
+
 设置alias
 ------------
 
diff --git a/docs/source/base-tables.rst b/docs/source/base-tables.rst
index 5dc67f5f..73da71a2 100644
--- a/docs/source/base-tables.rst
+++ b/docs/source/base-tables.rst
@@ -205,6 +205,26 @@ Record表示表的一行记录，我们在 Table 对象上调用 new_record 就
    >>> for record in reader[5:10]  # 可以执行多次，直到将count数量的record读完，这里可以改造成并行操作
    >>>     # 处理一条记录
 
+直接读取成 Pandas DataFrame:
+
+.. code-block:: python
+
+   >>> with t.open_reader(partition='pt=test') as reader:
+   >>>     pd_df = reader.to_pandas()
+
+
+.. _table_to_pandas_mp:
+
+利用多进程加速读取：
+
+.. code-block:: python
+
+   >>> import multiprocessing
+   >>> n_process = multiprocessing.cpu_count()
+   >>> with t.open_reader(partition='pt=test') as reader:
+   >>>     pd_df = reader.to_pandas(n_process=n_process)
+
+
 更简单的调用方法是使用 ODPS 对象的 ``read_table`` 方法，例如
 
 .. code-block:: python