Add example SQL query for all how-to pages

doc/howtos/devices.md

@@ -12,4 +12,15 @@ Assuming you already have a [connection](heavydb-connect) to the HeavyDB server:
 :linenos:
 ```
 
-By default, both devices are used if available. Otherwise, only the CPU is used.
+By default, both devices are used if available. Otherwise, only the CPU is used.
+
+:::{dropdown} Example SQL Query
+```{literalinclude} ../../rbc/tests/heavydb/test_howtos.py
+:language: python
+:caption: from ``test_devices`` of ``rbc/tests/heavydb/test_howtos.py``
+:start-after: magictoken.devices.sql.begin
+:end-before: magictoken.devices.sql.end
+:dedent: 4
+:linenos:
+```
+:::

doc/howtos/external_functions.md

@@ -15,6 +15,17 @@ libraries within python code.
 :linenos:
 ```
 
+:::{dropdown} Example SQL Query
+```{literalinclude} ../../rbc/tests/heavydb/test_howtos.py
+:language: python
+:caption: from ``test_external_functions`` of ``rbc/tests/heavydb/test_howtos.py``
+:start-after: magictoken.external_functions.abs.sql.begin
+:end-before: magictoken.external_functions.abs.sql.end
+:dedent: 4
+:linenos:
+```
+:::
+
 RBC already exposes a small set of C functions from the C stdlib. Check the API
 reference page for more details.
 
@@ -27,4 +38,15 @@ reference page for more details.
 :end-before: magictoken.external_functions.printf.end
 :dedent: 4
 :linenos:
-```
+```
+
+:::{dropdown} Example SQL Query
+```{literalinclude} ../../rbc/tests/heavydb/test_howtos.py
+:language: python
+:caption: from ``test_external_functions`` of ``rbc/tests/heavydb/test_howtos.py``
+:start-after: magictoken.external_functions.printf.sql.begin
+:end-before: magictoken.external_functions.printf.sql.end
+:dedent: 4
+:linenos:
+```
+:::

doc/howtos/manager.md

@@ -11,13 +11,24 @@ the [dictionary proxy](string-dict-proxy), and raise exceptions.
 
 ```{literalinclude} ../../rbc/tests/heavydb/test_howtos.py
 :language: python
-:caption: from ``test_mgr`` of ``rbc/tests/heavydb/test_howtos.py``
+:caption: from ``test_tablefunctionmanager`` of ``rbc/tests/heavydb/test_howtos.py``
 :start-after: magictoken.udtf.mgr.basic.begin
 :end-before: magictoken.udtf.mgr.basic.end
 :dedent: 4
 :linenos:
 ```
 
+:::{dropdown} Example SQL Query
+```{literalinclude} ../../rbc/tests/heavydb/test_howtos.py
+:language: python
+:caption: from ``test_tablefunctionmanager`` of ``rbc/tests/heavydb/test_howtos.py``
+:start-after: magictoken.udtf.mgr.basic.sql.begin
+:end-before: magictoken.udtf.mgr.basic.sql.end
+:dedent: 4
+:linenos:
+```
+:::
+
 ### Retrieving the dictionary string proxy
 
 When the Column has type `TextEncodingDict`, users can access the dictionary
@@ -40,9 +51,20 @@ proxy in HeavyDB.
 
 ```{literalinclude} ../../rbc/tests/heavydb/test_howtos.py
 :language: python
-:caption: from ``test_mgr`` of ``rbc/tests/heavydb/test_howtos.py``
+:caption: from ``test_rowfunctionmanager`` of ``rbc/tests/heavydb/test_howtos.py``
 :start-after: magictoken.udf.mgr.basic.begin
 :end-before: magictoken.udf.mgr.basic.end
 :dedent: 8
 :linenos:
-```
+```
+
+:::{dropdown} Example SQL Query
+```{literalinclude} ../../rbc/tests/heavydb/test_howtos.py
+:language: python
+:caption: from ``test_rowfunctionmanager`` of ``rbc/tests/heavydb/test_howtos.py``
+:start-after: magictoken.udf.mgr.basic.sql.begin
+:end-before: magictoken.udf.mgr.basic.sql.end
+:dedent: 8
+:linenos:
+```
+:::

doc/howtos/raise_exception.md

@@ -5,6 +5,11 @@ Exceptions in HeavyDB are quite different from the ones used in Python. In RBC
 code, you signal to the database an exception happened by calling a specific
 method (`error_message`) in the runner manager.
 
+## In a UDF:
+
+It is currently not possible to raise an exception in a UDF. The server must
+implement support for it first before RBC can support it.
+
 ## In a UDTF
 
 ```{literalinclude} ../../rbc/tests/heavydb/test_howtos.py
@@ -16,7 +21,13 @@ method (`error_message`) in the runner manager.
 :linenos:
 ```
 
-## In a UDF:
-
-It is currently not possible to raise an exception in a UDF. The server must
-implement support for it first before RBC can support it.
+:::{dropdown} Example SQL Query
+```{literalinclude} ../../rbc/tests/heavydb/test_howtos.py
+:language: python
+:caption: from ``test_raise_exception`` of ``rbc/tests/heavydb/test_howtos.py``
+:start-after: magictoken.raise_exception.sql.begin
+:end-before: magictoken.raise_exception.sql.end
+:dedent: 4
+:linenos:
+```
+:::

doc/howtos/template.md

@@ -18,3 +18,15 @@ Assuming you already have a [connection](heavydb-connect) to the HeavyDB server:
 In the case above, the template arguments `T` and `Z`, are specified within the
 decorator, indicating the valid data types that can be used for the `add`
 function.
+
+
+:::{dropdown} Example SQL Query
+```{literalinclude} ../../rbc/tests/heavydb/test_howtos.py
+:language: python
+:caption: from ``test_templates`` of ``rbc/tests/heavydb/test_howtos.py``
+:start-after: magictoken.templates.sql.begin
+:end-before: magictoken.templates.sql.end
+:dedent: 4
+:linenos:
+```
+:::

doc/howtos/udtf.md

@@ -11,3 +11,15 @@ UDTFs take a set of columns as input and return a set of columns as output.
 :dedent: 4
 :linenos:
 ```
+
+
+:::{dropdown} Example SQL Query
+```{literalinclude} ../../rbc/tests/heavydb/test_howtos.py
+:language: python
+:caption: from ``test_udtf`` of ``rbc/tests/heavydb/test_howtos.py``
+:start-after: magictoken.udtf.sql.begin
+:end-before: magictoken.udtf.sql.end
+:dedent: 4
+:linenos:
+```
+:::

rbc/tests/heavydb/test_howtos.py

@@ -30,10 +30,11 @@ def test_external_functions(heavydb):
     @heavydb('int64(int64)')
     def apply_abs(x):
         return cmath_abs(x)
-
-    _, result = heavydb.sql_execute('SELECT apply_abs(-3);')
     # magictoken.external_functions.abs.end
-    assert list(result) == [(3,)]
+
+    # magictoken.external_functions.abs.sql.begin
+    assert apply_abs(-3).execute() == 3
+    # magictoken.external_functions.abs.sql.end
 
     # magictoken.external_functions.printf.begin
     from rbc.externals.stdio import printf
@@ -43,16 +44,17 @@ def power_2(x):
         # This message will show in the heavydb logs
         printf("input number: %d\n", x)
         return x * x
-
-    _, result = heavydb.sql_execute('SELECT power_2(3);')
     # magictoken.external_functions.printf.end
-    assert list(result) == [(9,)]
+
+    # magictoken.external_functions.printf.sql.begin
+    assert power_2(3).execute() == 9
+    # magictoken.external_functions.printf.sql.end
 
 
 def test_raise_exception(heavydb):
     heavydb.unregister()
     # magictoken.raise_exception.begin
-    @heavydb('int32(TableFunctionManager, Column<int>, OutputColumn<int>)')
+    @heavydb('int32(TableFunctionManager, Column<int64>, OutputColumn<int64>)')
     def udtf_copy(mgr, inp, out):
         size = len(inp)
         if size > 4:
@@ -65,23 +67,19 @@ def udtf_copy(mgr, inp, out):
         return size
     # magictoken.raise_exception.end
 
-    col = 'i4'
-    table_name = heavydb.table_name
-
+    # magictoken.raise_exception.sql.begin
     query = f'''
-        SELECT
-          *
-        FROM
-            TABLE(udtf_copy(
-                cursor(SELECT {col} FROM {table_name})
-            ))
+        SELECT * FROM TABLE(udtf_copy(
+            cursor(SELECT * FROM TABLE(generate_series(1, 5, 1)))
+        ));
     '''
 
     with pytest.raises(HeavyDBServerError) as exc:
         heavydb.sql_execute(query)
     exc_msg = ('Error executing table function: TableFunctionManager '
                'error_message!')
     assert exc.match(exc_msg)
+    # magictoken.raise_exception.sql.end
 
 
 def test_devices(heavydb):
@@ -91,8 +89,11 @@ def test_devices(heavydb):
     def add(a, b):
         return a + b
     # magictoken.devices.end
+
+    # magictoken.devices.sql.begin
     _, result = heavydb.sql_execute('SELECT add(-3, 3);')
     assert list(result) == [(0,)]
+    # magictoken.devices.sql.end
 
 
 def test_templates(heavydb):
@@ -102,11 +103,14 @@ def test_templates(heavydb):
     @heavydb('Z(T, Z)', T=['int32', 'float'], Z=['int64', 'double'])
     def add(a, b):
         return a + b
-
+    # magictoken.templates.end
     heavydb.register()
+
+    # magictoken.templates.sql.begin
     assert heavydb.function_names(runtime_only=True) == ['add']
     assert len(heavydb.function_details('add')) == 4
-    # magictoken.templates.end
+    assert add(2, 3).execute() == 5
+    # magictoken.templates.sql.end
 
 
 def test_udf(heavydb):
@@ -138,11 +142,9 @@ def multiply(a, b):
 
 def test_udtf(heavydb):
     heavydb.unregister()
-    col = 'f4'
-    table_name = heavydb.table_name
 
     # magictoken.udtf.begin
-    @heavydb('int32(TableFunctionManager, Column<float>, OutputColumn<float>)')
+    @heavydb('int32(TableFunctionManager, Column<int64>, OutputColumn<int64>)')
     def my_copy(mgr, inp, out):
         size = len(inp)
         mgr.set_output_row_size(size)
@@ -151,16 +153,15 @@ def my_copy(mgr, inp, out):
         return size
     # magictoken.udtf.end
 
+    # magictoken.udtf.sql.begin
     query = f'''
-        SELECT
-            *
-        FROM
-            TABLE(my_copy(
-                cursor(SELECT {col} FROM {table_name})
-            ))
+        SELECT * FROM TABLE(my_copy(
+            cursor(SELECT * FROM TABLE(generate_series(1, 5, 1)))
+        ));
     '''
     _, result = heavydb.sql_execute(query)
-    assert list(result) == [(0.0,), (1.0,), (2.0,), (3.0,), (4.0,)]
+    assert list(result) == [(1,), (2,), (3,), (4,), (5,)]
+    # magictoken.udtf.sql.end
 
 
 def test_udf_text_copy(heavydb):
@@ -323,7 +324,7 @@ def test_tablefunctionmanager(heavydb):
     table = heavydb.table_name
 
     # magictoken.udtf.mgr.basic.begin
-    @heavydb('int32(TableFunctionManager, Column<int>, OutputColumn<int>)')
+    @heavydb('int32(TableFunctionManager, Column<int64>, OutputColumn<int64>)')
     def table_copy(mgr, inp, out):
         size = len(inp)
         mgr.set_output_row_size(size)
@@ -332,16 +333,15 @@ def table_copy(mgr, inp, out):
         return size
     # magictoken.udtf.mgr.basic.end
 
+    # magictoken.udtf.mgr.basic.sql.begin
     query = f'''
-        SELECT
-            *
-        FROM
-            TABLE(table_copy(
-                cursor(SELECT i4 FROM {table})
-            ))
+        SELECT * FROM TABLE(table_copy(
+            cursor(SELECT * FROM TABLE(generate_series(0, 4, 1)))
+        ))
     '''
     _, r = heavydb.sql_execute(query)
     assert list(r) == [(0,), (1,), (2,), (3,), (4,)]
+    # magictoken.udtf.mgr.basic.sql.end
 
 
 def test_rowfunctionmanager(heavydb):
@@ -364,15 +364,14 @@ def concat(mgr, text):
                                          s_concat)
         # magictoken.udf.mgr.basic.end
 
+        # magictoken.udf.mgr.basic.sql.begin
         query = f'''
-            SELECT
-                concat(t1)
-            FROM
-                {table}
+            SELECT concat(t1) FROM {table}
         '''
         _, r = heavydb.sql_execute(query)
         assert list(r) == [('test: fun',), ('test: bar',), ('test: foo',),
                            ('test: barr',), ('test: foooo',)]
+        # magictoken.udf.mgr.basic.sql.end
 
 
 def test_column_power(heavydb):