Merge pull request #45 from treasure-data/query-type

Disable query parameter `type`
treasure-data · Sep 6, 2019 · 26a061a · 26a061a
2 parents e20bb32 + eda21b8
commit 26a061a
Show file tree

Hide file tree

Showing 3 changed files with 117 additions and 6 deletions.
diff --git a/pytd/client.py b/pytd/client.py
@@ -146,6 +146,25 @@ def query(self, query, engine=None, **kwargs):
             Query engine. If not given, default query engine created in the
             constructor will be used.
 
+        **kwargs
+            Treasure Data-specific optional query parameters. Giving these
+            keyword arguments forces query engine to issue a query via Treasure
+            Data REST API provided by ``tdclient``; that is, if ``engine`` is
+            Presto, you cannot enjoy efficient direct access to the query
+            engine provided by ``prestodb``.
+
+            - ``db`` (str): use the database
+            - ``result_url`` (str): result output URL
+            - ``priority`` (int or str): priority
+                - -2: "VERY LOW"
+                - -1: "LOW"
+                -  0: "NORMAL"
+                -  1: "HIGH"
+                -  2: "VERY HIGH"
+            - ``retry_limit`` (int): max number of automatic retries
+            - ``wait_interval`` (int): sleep interval until job finish
+            - ``wait_callback`` (function): called every interval against job itself
+
         Returns
         -------
         dict : keys ('data', 'columns')

diff --git a/pytd/pandas_td/__init__.py b/pytd/pandas_td/__init__.py
@@ -121,12 +121,23 @@ def read_td_query(
         See https://prestodb.io/docs/current/release/release-0.77.html
 
     params : dict, optional
-        Parameters to pass to execute method.
+        Parameters to pass to execute method. pytd does not support parameter
+        ``type`` ('hive', 'presto'), and query type needs to be defined by
+        ``engine``.
+
         Available parameters:
-        - result_url (str): result output URL
-        - priority (int or str): priority (e.g. "NORMAL", "HIGH", etc.)
-        - retry_limit (int): retry limit
-        pytd: This argument will be ignored.
+
+        - ``db`` (str): use the database
+        - ``result_url`` (str): result output URL
+        - ``priority`` (int or str): priority
+            - -2: "VERY LOW"
+            - -1: "LOW"
+            -  0: "NORMAL"
+            -  1: "HIGH"
+            -  2: "VERY HIGH"
+        - ``retry_limit`` (int): max number of automatic retries
+        - ``wait_interval`` (int): sleep interval until job finish
+        - ``wait_callback`` (function): called every interval against job itself
 
     Returns
     -------

diff --git a/pytd/query_engine.py b/pytd/query_engine.py
@@ -49,6 +49,24 @@ def execute(self, query, **kwargs):
         query : string
             Query.
 
+        **kwargs
+            Treasure Data-specific optional query parameters. Giving these
+            keyword arguments forces query engine to issue a query via Treasure
+            Data REST API provided by ``tdclient``, rather than using a direct
+            connection established by the ``prestodb`` package.
+
+            - ``db`` (str): use the database
+            - ``result_url`` (str): result output URL
+            - ``priority`` (int or str): priority
+                - -2: "VERY LOW"
+                - -1: "LOW"
+                -  0: "NORMAL"
+                -  1: "HIGH"
+                -  2: "VERY HIGH"
+            - ``retry_limit`` (int): max number of automatic retries
+            - ``wait_interval`` (int): sleep interval until job finish
+            - ``wait_callback`` (function): called every interval against job itself
+
         Returns
         -------
         dict : keys ('data', 'columns')
@@ -125,13 +143,30 @@ def _get_tdclient_cursor(self, con, **kwargs):
         con : tdclient.connection.Connection
             Handler created by ``tdclient#connect``.
 
+        **kwargs
+            Treasure Data-specific optional query parameters. Giving these
+            keyword arguments forces query engine to issue a query via Treasure
+            Data REST API provided by ``tdclient``, rather than using a direct
+            connection established by the ``prestodb`` package.
+
+            - ``db`` (str): use the database
+            - ``result_url`` (str): result output URL
+            - ``priority`` (int or str): priority
+                - -2: "VERY LOW"
+                - -1: "LOW"
+                -  0: "NORMAL"
+                -  1: "HIGH"
+                -  2: "VERY HIGH"
+            - ``retry_limit`` (int): max number of automatic retries
+            - ``wait_interval`` (int): sleep interval until job finish
+            - ``wait_callback`` (function): called every interval against job itself
+
         Returns
         -------
         tdclient.cursor.Cursor
         """
         api_param_names = set(
             [
-                "type",
                 "db",
                 "result_url",
                 "priority",
@@ -141,6 +176,13 @@ def _get_tdclient_cursor(self, con, **kwargs):
             ]
         )
 
+        if "type" in kwargs:
+            raise RuntimeError(
+                "optional query parameter 'type' is unsupported. Issue query "
+                "from a proper QueryEngine instance: "
+                "{PrestoQueryEngine, HiveQueryEngine}."
+            )
+
         # update a clone of the original params
         cursor_kwargs = con._cursor_kwargs.copy()
         for k, v in kwargs.items():
@@ -215,6 +257,26 @@ def presto_api_host(self):
     def cursor(self, **kwargs):
         """Get cursor defined by DB-API.
 
+        Parameters
+        ----------
+        **kwargs
+            Treasure Data-specific optional query parameters. Giving these
+            keyword arguments forces query engine to issue a query via Treasure
+            Data REST API provided by ``tdclient``, rather than using a direct
+            connection established by the ``prestodb`` package.
+
+            - ``db`` (str): use the database
+            - ``result_url`` (str): result output URL
+            - ``priority`` (int or str): priority
+                - -2: "VERY LOW"
+                - -1: "LOW"
+                -  0: "NORMAL"
+                -  1: "HIGH"
+                -  2: "VERY HIGH"
+            - ``retry_limit`` (int): max number of automatic retries
+            - ``wait_interval`` (int): sleep interval until job finish
+            - ``wait_callback`` (function): called every interval against job itself
+
         Returns
         -------
         prestodb.dbapi.Cursor, or tdclient.cursor.Cursor
@@ -282,6 +344,25 @@ def user_agent(self):
     def cursor(self, **kwargs):
         """Get cursor defined by DB-API.
 
+        Parameters
+        ----------
+        **kwargs
+            Treasure Data-specific optional query parameters. Giving these
+            keyword arguments forces query engine to issue a query via Treasure
+            Data REST API provided by ``tdclient``.
+
+            - ``db`` (str): use the database
+            - ``result_url`` (str): result output URL
+            - ``priority`` (int or str): priority
+                - -2: "VERY LOW"
+                - -1: "LOW"
+                -  0: "NORMAL"
+                -  1: "HIGH"
+                -  2: "VERY HIGH"
+            - ``retry_limit`` (int): max number of automatic retries
+            - ``wait_interval`` (int): sleep interval until job finish
+            - ``wait_callback`` (function): called every interval against job itself
+
         Returns
         -------
         tdclient.cursor.Cursor