Release v0.11.4.1 (#207)

aliyun · Jun 29, 2023 · 8f4f04f · 8f4f04f
1 parent 95404d3
commit 8f4f04f
Show file tree

Hide file tree

Showing 65 changed files with 2,611 additions and 1,102 deletions.
diff --git a/docs/source/base-sql.rst b/docs/source/base-sql.rst
@@ -3,8 +3,8 @@
 SQL
 =====
 
-PyODPS支持ODPS SQL的查询，并可以读取执行的结果。
-``execute_sql`` 或者 ``run_sql`` 方法的返回值是 :ref:`运行实例 <instances>` 。
+PyODPS支持ODPS SQL的查询，并可以读取执行的结果。 ``execute_sql`` / ``execute_sql_interactive`` /
+``run_sql`` / ``run_sql_interactive`` 方法的返回值是 :ref:`运行实例 <instances>` 。
 
 .. note::
 
@@ -14,23 +14,70 @@ PyODPS支持ODPS SQL的查询，并可以读取执行的结果。
 
 .. _execute_sql:
 
-执行SQL
--------
+执行 SQL
+--------
+
+你可以使用 ``execute_sql`` 方法以同步方式执行 SQL。调用时，该方法会阻塞直至 SQL 执行完成。
+
+.. code-block:: python
+
+   >>> o.execute_sql('select * from dual')  # 同步的方式执行，会阻塞直到SQL执行完成
+
+你也可以使用非阻塞方式异步执行 SQL。调用时，该方法在将 SQL 提交到 MaxCompute 后即返回 Instance
+对象。你需要使用 ``wait_for_success`` 方法等待该 SQL 执行完成。
 
 .. code-block:: python
 
-   >>> o.execute_sql('select * from dual')  #  同步的方式执行，会阻塞直到SQL执行完成
-   >>>
    >>> instance = o.run_sql('select * from dual')  # 异步的方式执行
    >>> print(instance.get_logview_address())  # 获取logview地址
    >>> instance.wait_for_success()  # 阻塞直到完成
 
+
+使用 MCQA 执行 SQL
+-------------------
+`MCQA <https://help.aliyun.com/document_detail/180701.html>`_ 是 MaxCompute 提供的查询加速功能，
+支持使用独立资源池对中小规模数据进行加速。PyODPS 从 0.11.4.1 开始支持以下列方式通过 MCQA 执行 SQL
+，同时需要 MaxCompute 具备 MCQA 的支持。
+
+你可以使用 ``execute_sql_interactive`` 通过 MCQA 执行 SQL 并返回 MCQA Instance。如果
+MCQA 无法执行相应的 SQL ，会自动回退到传统模式。此时，函数返回的 Instance 为回退后的 Instance。
+
+.. code-block:: python
+
+    >>> o.execute_sql_interactive('select * from dual')
+
+如果不希望回退，可以指定参数 ``fallback=False``。也可以指定为回退策略（或回退策略的组合，使用逗号分隔的字符串）。
+可用的策略名如下。默认策略为 ``unsupported,upgrading,noresource,timeout`` 。
+
+* ``generic`` ：指定时，表示发生未知错误时回退到传统模式。
+* ``noresource`` ：指定时，表示发生资源不足问题时回退到传统模式。
+* ``upgrading`` ：指定时，表示升级期间回退到传统模式。
+* ``timeout`` ：指定时，表示执行超时时回退到传统模式。
+* ``unsupported`` ：指定时，表示遇到 MCQA 不支持的场景时回退到传统模式。
+
+例如，下面的代码要求在 MCQA 不支持和资源不足时回退：
+
+.. code-block:: python
+
+    >>> o.execute_sql_interactive('select * from dual', fallback="noresource,unsupported")
+
+你也可以使用 ``run_sql_interactive`` 通过 MCQA 异步执行 SQL。类似 ``run_sql``，该方法会在提交任务后即返回
+MCQA Instance，你需要自行等待 Instance 完成。需要注意的是，该方法不会自动回退。当执行失败时，你需要自行重试或执行
+``execute_sql``。
+
+.. code-block:: python
+
+   >>> instance = o.run_sql_interactive('select * from dual')  # 异步的方式执行
+   >>> print(instance.get_logview_address())  # 获取logview地址
+   >>> instance.wait_for_success()  # 阻塞直到完成
+
 .. _sql_hints:
 
 设置运行参数
 ------------
 
-有时，我们在运行时，需要设置运行时参数，我们可以通过设置 ``hints`` 参数，参数类型是dict。
+有时，我们在运行时，需要设置运行时参数，我们可以通过设置 ``hints`` 参数，参数类型是 dict。该参数对 ``execute_sql`` /
+``execute_sql_interactive`` / ``run_sql`` / ``run_sql_interactive`` 均有效。
 
 .. code-block:: python
 

diff --git a/docs/source/locale/en/LC_MESSAGES/api-def.po b/docs/source/locale/en/LC_MESSAGES/api-def.po
@@ -8,7 +8,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: PyODPS 0.7.16\n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2023-05-18 11:20+0800\n"
+"POT-Creation-Date: 2023-06-06 14:29+0800\n"
 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
 "Language-Team: LANGUAGE <LL@li.org>\n"
@@ -62,22 +62,22 @@ msgstr ""
 #: odps.core.ODPS.delete_xflow odps.core.ODPS.execute_archive_table
 #: odps.core.ODPS.execute_merge_files odps.core.ODPS.execute_security_query
 #: odps.core.ODPS.execute_sql odps.core.ODPS.execute_sql_cost
-#: odps.core.ODPS.execute_xflow odps.core.ODPS.exist_function
-#: odps.core.ODPS.exist_instance odps.core.ODPS.exist_offline_model
-#: odps.core.ODPS.exist_project odps.core.ODPS.exist_resource
-#: odps.core.ODPS.exist_role odps.core.ODPS.exist_schema
-#: odps.core.ODPS.exist_table odps.core.ODPS.exist_user
-#: odps.core.ODPS.exist_volume odps.core.ODPS.exist_volume_partition
-#: odps.core.ODPS.exist_xflow odps.core.ODPS.get_function
-#: odps.core.ODPS.get_instance odps.core.ODPS.get_logview_address
-#: odps.core.ODPS.get_offline_model odps.core.ODPS.get_project
-#: odps.core.ODPS.get_project_policy odps.core.ODPS.get_resource
-#: odps.core.ODPS.get_role_policy odps.core.ODPS.get_schema
-#: odps.core.ODPS.get_security_option odps.core.ODPS.get_security_options
-#: odps.core.ODPS.get_table odps.core.ODPS.get_volume
-#: odps.core.ODPS.get_volume_file odps.core.ODPS.get_volume_partition
-#: odps.core.ODPS.get_xflow odps.core.ODPS.get_xflow_results
-#: odps.core.ODPS.get_xflow_sub_instances
+#: odps.core.ODPS.execute_sql_interactive odps.core.ODPS.execute_xflow
+#: odps.core.ODPS.exist_function odps.core.ODPS.exist_instance
+#: odps.core.ODPS.exist_offline_model odps.core.ODPS.exist_project
+#: odps.core.ODPS.exist_resource odps.core.ODPS.exist_role
+#: odps.core.ODPS.exist_schema odps.core.ODPS.exist_table
+#: odps.core.ODPS.exist_user odps.core.ODPS.exist_volume
+#: odps.core.ODPS.exist_volume_partition odps.core.ODPS.exist_xflow
+#: odps.core.ODPS.get_function odps.core.ODPS.get_instance
+#: odps.core.ODPS.get_logview_address odps.core.ODPS.get_offline_model
+#: odps.core.ODPS.get_project odps.core.ODPS.get_project_policy
+#: odps.core.ODPS.get_resource odps.core.ODPS.get_role_policy
+#: odps.core.ODPS.get_schema odps.core.ODPS.get_security_option
+#: odps.core.ODPS.get_security_options odps.core.ODPS.get_table
+#: odps.core.ODPS.get_volume odps.core.ODPS.get_volume_file
+#: odps.core.ODPS.get_volume_partition odps.core.ODPS.get_xflow
+#: odps.core.ODPS.get_xflow_results odps.core.ODPS.get_xflow_sub_instances
 #: odps.core.ODPS.iter_xflow_sub_instances odps.core.ODPS.list_functions
 #: odps.core.ODPS.list_instance_queueing_infos odps.core.ODPS.list_instances
 #: odps.core.ODPS.list_offline_models odps.core.ODPS.list_projects
@@ -223,20 +223,21 @@ msgstr ""
 #: odps.core.ODPS.delete_xflow odps.core.ODPS.execute_archive_table
 #: odps.core.ODPS.execute_merge_files odps.core.ODPS.execute_security_query
 #: odps.core.ODPS.execute_sql odps.core.ODPS.execute_sql_cost
-#: odps.core.ODPS.execute_xflow odps.core.ODPS.exist_function
-#: odps.core.ODPS.exist_instance odps.core.ODPS.exist_offline_model
-#: odps.core.ODPS.exist_project odps.core.ODPS.exist_resource
-#: odps.core.ODPS.exist_schema odps.core.ODPS.exist_table
-#: odps.core.ODPS.exist_volume odps.core.ODPS.exist_xflow
-#: odps.core.ODPS.get_function odps.core.ODPS.get_instance
-#: odps.core.ODPS.get_logview_address odps.core.ODPS.get_offline_model
-#: odps.core.ODPS.get_project odps.core.ODPS.get_project_policy
-#: odps.core.ODPS.get_resource odps.core.ODPS.get_role_policy
-#: odps.core.ODPS.get_schema odps.core.ODPS.get_security_option
-#: odps.core.ODPS.get_security_options odps.core.ODPS.get_table
-#: odps.core.ODPS.get_volume odps.core.ODPS.get_volume_file
-#: odps.core.ODPS.get_volume_partition odps.core.ODPS.get_xflow
-#: odps.core.ODPS.get_xflow_results odps.core.ODPS.get_xflow_sub_instances
+#: odps.core.ODPS.execute_sql_interactive odps.core.ODPS.execute_xflow
+#: odps.core.ODPS.exist_function odps.core.ODPS.exist_instance
+#: odps.core.ODPS.exist_offline_model odps.core.ODPS.exist_project
+#: odps.core.ODPS.exist_resource odps.core.ODPS.exist_schema
+#: odps.core.ODPS.exist_table odps.core.ODPS.exist_volume
+#: odps.core.ODPS.exist_xflow odps.core.ODPS.get_function
+#: odps.core.ODPS.get_instance odps.core.ODPS.get_logview_address
+#: odps.core.ODPS.get_offline_model odps.core.ODPS.get_project
+#: odps.core.ODPS.get_project_policy odps.core.ODPS.get_resource
+#: odps.core.ODPS.get_role_policy odps.core.ODPS.get_schema
+#: odps.core.ODPS.get_security_option odps.core.ODPS.get_security_options
+#: odps.core.ODPS.get_table odps.core.ODPS.get_volume
+#: odps.core.ODPS.get_volume_file odps.core.ODPS.get_volume_partition
+#: odps.core.ODPS.get_xflow odps.core.ODPS.get_xflow_results
+#: odps.core.ODPS.get_xflow_sub_instances
 #: odps.core.ODPS.iter_xflow_sub_instances odps.core.ODPS.list_functions
 #: odps.core.ODPS.list_instance_queueing_infos odps.core.ODPS.list_instances
 #: odps.core.ODPS.list_offline_models odps.core.ODPS.list_projects
@@ -836,8 +837,8 @@ msgstr ""
 #: odps.mars_extension.oscar.core.persist_mars_dataframe:17
 #: odps.models.function.Function.drop:3 odps.models.function.Function.update:3
 #: odps.models.instance.Instance.stop:3
-#: odps.models.instance.Instance.wait_for_completion:5
-#: odps.models.instance.Instance.wait_for_success:4
+#: odps.models.instance.Instance.wait_for_completion:7
+#: odps.models.instance.Instance.wait_for_success:7
 #: odps.models.partition.Partition.drop:5
 #: odps.models.resource.FileResource.close:3
 #: odps.models.resource.FileResource.flush:4
@@ -1217,6 +1218,35 @@ msgstr ""
 msgid "cost info in dict format"
 msgstr ""
 
+#: odps.core.ODPS.execute_sql_interactive:1 of
+msgid ""
+"Run SQL query in interactive mode (a.k.a MaxCompute QueryAcceleration). "
+"If query is not supported or fails, and fallback is True, will fallback "
+"to offline mode automatically"
+msgstr ""
+
+#: odps.core.ODPS.execute_sql_interactive:5 of
+msgid "the sql query."
+msgstr ""
+
+#: odps.core.ODPS.execute_sql_interactive:6 of
+msgid "settings for sql query."
+msgstr ""
+
+#: odps.core.ODPS.execute_sql_interactive:7 of
+msgid ""
+"fallback query to non-interactive mode, True by default. Both boolean "
+"type and policy names separated by commas are acceptable."
+msgstr ""
+
+#: odps.core.ODPS.execute_sql_interactive:9 of
+msgid "wait fallback instance to finish, True by default."
+msgstr ""
+
+#: odps.core.ODPS.execute_sql_interactive:10 of
+msgid "instance."
+msgstr ""
+
 #: odps.core.ODPS.execute_xflow:1 of
 msgid ""
 "Run xflow by given name, xflow project, paremeters, block until xflow "
@@ -2065,14 +2095,6 @@ msgid ""
 ":return: instance."
 msgstr ""
 
-#: odps.core.ODPS.run_sql_interactive_with_fallback:1 of
-msgid ""
-"Run SQL query in interactive mode (a.k.a MaxCompute QueryAcceleration). "
-"If query is not supported or fails, will fallback to offline mode "
-"automatically :param sql: the sql query. :param hints: settings for sql "
-"query. :return: instance."
-msgstr ""
-
 #: odps.core.ODPS.run_xflow:1 of
 msgid "Run xflow by given name, xflow project, paremeters asynchronously."
 msgstr ""
@@ -2214,6 +2236,8 @@ msgstr ""
 #: odps.models.instance.Instance.Status:1
 #: odps.models.instance.Instance.Task.TaskStatus:1
 #: odps.models.project.Project.AuthQueryStatus:1
+#: odps.models.project.Project.ProjectStatus:1
+#: odps.models.project.Project.ProjectType:1
 #: odps.models.resource.FileResource.Mode:1
 #: odps.models.resource.Resource.Type:1 of
 msgid "An enumeration."
@@ -2780,15 +2804,23 @@ msgstr ""
 msgid "Wait for the instance to complete, and neglect the consequence."
 msgstr ""
 
-#: odps.models.instance.Instance.wait_for_completion:4 of
+#: odps.models.instance.Instance.wait_for_completion:4
+#: odps.models.instance.Instance.wait_for_success:4 of
+msgid ""
+"if specified, next check interval will be multiplied by 2 till "
+"max_interval is reached."
+msgstr ""
+
+#: odps.models.instance.Instance.wait_for_completion:6
+#: odps.models.instance.Instance.wait_for_success:6 of
 msgid "time"
 msgstr ""
 
 #: odps.models.instance.Instance.wait_for_success:1 of
 msgid "Wait for instance to complete, and check if the instance is successful."
 msgstr ""
 
-#: odps.models.instance.Instance.wait_for_success:5 of
+#: odps.models.instance.Instance.wait_for_success:8 of
 msgid ":class:`odps.errors.ODPSError` if the instance failed"
 msgstr ""
 
@@ -3005,3 +3037,13 @@ msgid ""
 "this method might be incomplete due to size limitations."
 msgstr ""
 
+#~ msgid ""
+#~ "Run SQL query in interactive mode "
+#~ "(a.k.a MaxCompute QueryAcceleration). If query"
+#~ " is not supported or fails, will "
+#~ "fallback to offline mode automatically "
+#~ ":param sql: the sql query. :param "
+#~ "hints: settings for sql query. :return:"
+#~ " instance."
+#~ msgstr ""
+