Move feat from %sqlrender to %sqlcmd snippets (#681)

CHANGELOG.md

@@ -5,6 +5,7 @@
 * [Feature] Modified `TableDescription` to add styling, generate messages and format the calculated outputs (#459)
 * [Feature] Support flexible spacing `myvar=<<` operator ([#525](https://github.com/ploomber/jupysql/issues/525))
 * [Feature] Added a line under `ResultSet` to distinguish it from data frame and error message when invalid operations are performed (#468)
+* [Feature] Moved `%sqlrender` feature to `%sqlcmd snippets` (#647)
 
 * [Doc] Modified integrations content to ensure they're all consistent (#523)
 * [Doc] Document --persist-replace in API section (#539)

doc/_toc.yml

@@ -43,7 +43,6 @@ parts:
     chapters:
     - file: api/magic-sql
     - file: api/magic-plot
-    - file: api/magic-render
     - file: api/magic-snippets
     - file: api/configuration
     - file: api/python

doc/api/magic-snippets.md

@@ -5,15 +5,14 @@ jupytext:
     extension: .md
     format_name: myst
     format_version: 0.13
-    jupytext_version: 1.14.5
+    jupytext_version: 1.14.6
 kernelspec:
   display_name: Python 3 (ipykernel)
   language: python
   name: python3
 myst:
   html_meta:
-    description lang=en: Documentation for  %sqlcmd snippets
-      from JupySQL
+    description lang=en: Documentation for %sqlcmd snippets from JupySQL
     keywords: jupyter, sql, jupysql, snippets
     property=og:locale: en_US
 ---
@@ -73,28 +72,48 @@ Returns all the snippets saved in the environment
 
 Arguments:
 
+`{snippet_name}` Return a snippet.
+
 `-d`/`--delete` Delete a snippet.
 
 `-D`/`--delete-force` Force delete a snippet. This may be useful if there are other dependent snippets, and you still need to delete this snippet.
 
 `-A`/`--delete-force-all` Force delete a snippet and all dependent snippets.
 
 ```{code-cell} ipython3
+chinstrap_snippet = %sqlcmd snippets chinstrap
+print(chinstrap_snippet)
+```
+
+This returns the stored snippet `chinstrap`.
+
+Calling `%sqlcmd snippets {snippet_name}` also works on a snippet that is dependent on others. To demonstrate it, let's create a snippet dependent on the `chinstrap` snippet.
+
+```{code-cell} ipython3
+%%sql --save chinstrap_sub
+SELECT * FROM chinstrap where island == 'Dream'
+```
+
+```{code-cell} ipython3
+chinstrap_sub_snippet = %sqlcmd snippets chinstrap_sub
+print(chinstrap_sub_snippet)
+```
+
+This returns the stored snippet `chinstrap_sub`.
+
+Now, let's see how to delete a stored snippet.
 
+```{code-cell} ipython3
 %sqlcmd snippets -d gentoo
 ```
 
 This deletes the stored snippet `gentoo`.
 
-To demonstrate `force-delete` let's create a snippet dependent on `chinstrap` snippet.
+Now, let's see how to delete a stored snippet that other snippets are dependent on. Recall we have created `chinstrap_sub` which is dependent on `chinstrap`.
 
 ```{code-cell} ipython3
-:tags: [hide-output]
-
-%%sql --save chinstrap_sub
-SELECT * FROM chinstrap where island == 'Dream'
+print(chinstrap_sub_snippet)
 ```
-+++
 
 Trying to delete the `chinstrap` snippet will display an error message:
 
@@ -104,10 +123,9 @@ Trying to delete the `chinstrap` snippet will display an error message:
 %sqlcmd snippets -d chinstrap
 ```
 
-If you still wish to delete this snippet, you can run the below command:
+If you still wish to delete this snippet, you should use `force-delete` by running the below command:
 
 ```{code-cell} ipython3
-
 %sqlcmd snippets -D chinstrap
 ```
 
@@ -130,6 +148,5 @@ SELECT * FROM chinstrap where island == 'Dream'
 Now, force delete `chinstrap` and its dependent `chinstrap_sub`:
 
 ```{code-cell} ipython3
-
 %sqlcmd snippets -A chinstrap
 ```

doc/compose.md

@@ -5,16 +5,16 @@ jupytext:
     extension: .md
     format_name: myst
     format_version: 0.13
-    jupytext_version: 1.14.4
+    jupytext_version: 1.14.6
 kernelspec:
   display_name: Python 3 (ipykernel)
   language: python
   name: python3
 myst:
   html_meta:
-    description lang=en: "Use JupySQL to organize large SQL queries in a Jupyter notebook"
-    keywords: "jupyter, sql, jupysql"
-    property=og:locale: "en_US"
+    description lang=en: Use JupySQL to organize large SQL queries in a Jupyter notebook
+    keywords: jupyter, sql, jupysql
+    property=og:locale: en_US
 ---
 
 # Organizing Large Queries
@@ -144,10 +144,10 @@ top_artist.bar()
 
 It looks like Iron Maiden had the highest number of rock and metal songs in the table.
 
-We can render the full query with the `%sqlrender` magic:
+We can render the full query with the `%sqlcmd snippets {name}` magic:
 
 ```{code-cell} ipython3
-final = %sqlrender top_artist
+final = %sqlcmd snippets top_artist
 print(final)
 ```
 
@@ -160,4 +160,4 @@ We can verify the retrieved query returns the same result:
 
 ## Summary
 
-In the given example, we demonstrated JupySQL's usage as a tool for managing large SQL queries in Jupyter Notebooks. It effectively broke down a complex query into smaller, organized parts, simplifying the process of analyzing a record store's sales database. By using JupySQL, users can easily maintain and reuse their queries, enhancing the overall data analysis experience.
+In the given example, we demonstrated JupySQL's usage as a tool for managing large SQL queries in Jupyter Notebooks. It effectively broke down a complex query into smaller, organized parts, simplifying the process of analyzing a record store's sales database. By using JupySQL, users can easily maintain and reuse their queries, enhancing the overall data analysis experience.

doc/integrations/mariadb.ipynb

@@ -847,7 +847,7 @@
     }
    ],
    "source": [
-    "query = %sqlrender trip_stats\n",
+    "query = %sqlcmd snippets trip_stats\n",
     "print(query)"
    ]
   },

doc/integrations/mssql.ipynb

@@ -1049,7 +1049,7 @@
     }
    ],
    "source": [
-    "query = %sqlrender trip_stats\n",
+    "query = %sqlcmd snippets trip_stats\n",
     "print(query)"
    ]
   },

doc/integrations/mysql.ipynb

@@ -903,7 +903,7 @@
     }
    ],
    "source": [
-    "query = %sqlrender trip_stats\n",
+    "query = %sqlcmd snippets trip_stats\n",
     "print(query)"
    ]
   },

doc/integrations/oracle.ipynb

@@ -613,7 +613,7 @@
     }
    ],
    "source": [
-    "query = %sqlrender saved_cte\n",
+    "query = %sqlcmd snippets saved_cte\n",
     "print(query)"
    ]
   },
@@ -757,7 +757,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.10"
+   "version": "3.10.11"
   },
   "myst": {
    "html_meta": {

doc/integrations/postgres-connect.ipynb

@@ -771,7 +771,7 @@
     }
    ],
    "source": [
-    "query = %sqlrender trip_stats\n",
+    "query = %sqlcmd snippets trip_stats\n",
     "print(query)"
    ]
   },
@@ -1058,7 +1058,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.9"
+   "version": "3.10.11"
   },
   "myst": {
    "html_meta": {

doc/integrations/snowflake.ipynb

@@ -751,7 +751,7 @@
     }
    ],
    "source": [
-    "final = %sqlrender no_nulls\n",
+    "final = %sqlcmd snippets no_nulls\n",
     "print(final)"
    ]
   },

doc/integrations/trinodb.ipynb

@@ -775,7 +775,7 @@
     }
    ],
    "source": [
-    "query = %sqlrender trip_stats\n",
+    "query = %sqlcmd snippets trip_stats\n",
     "print(query)"
    ]
   },

doc/user-guide/template.md

@@ -5,7 +5,7 @@ jupytext:
     extension: .md
     format_name: myst
     format_version: 0.13
-    jupytext_version: 1.14.5
+    jupytext_version: 1.14.6
 kernelspec:
   display_name: Python 3 (ipykernel)
   language: python
@@ -41,7 +41,6 @@ The benefits of using parametrized SQL queries are:
 Let's load some data and connect to the in-memory DuckDB instance:
 
 ```{code-cell} ipython3
-
 %load_ext sql
 from pathlib import Path
 from urllib.request import urlretrieve
@@ -93,15 +92,15 @@ group by sex
 Here's the final compiled query:
 
 ```{code-cell} ipython3
-final = %sqlrender avg_body_mass
+final = %sqlcmd snippets avg_body_mass
 print(final)
 ```
 
 ## Macros + variable expansion
 
 `Macros` is a construct analogous to functions that promote re-usability. We'll first define a macro for converting a value from `millimetre` to `centimetre`. And then use this macro in the query using variable expansion.
 
-```{code-cell} python
+```{code-cell} ipython3
 %%sql --save convert
 {% macro mm_to_cm(column_name, precision=2) %}
     ({{ column_name }} / 10)::numeric(16, {{ precision }})
@@ -116,27 +115,31 @@ from penguins.csv
 
 Let's see the final rendered query:
 
-```{code-cell} python
-final = %sqlrender convert
+```{code-cell} ipython3
+final = %sqlcmd snippets convert
 print(final)
 ```
 
+```{code-cell} ipython3
+%sqlcmd snippets -d convert
+```
+
 ## Create tables in loop
 
 We can also create multiple tables in a loop using parametrized queries. Let's segregate the dataset by `island`.
 
-```{code-cell} python
+```{code-cell} ipython3
 for island in ("Torgersen", "Biscoe", "Dream"):
     %sql CREATE TABLE {{island}} AS (SELECT * from penguins.csv WHERE island = '{{island}}')
 ```
 
-```{code-cell} python
+```{code-cell} ipython3
 %sqlcmd tables
 ```
 
 Let's verify data in one of the tables:
 
-```{code-cell} python
+```{code-cell} ipython3
 %sql SELECT * FROM Torgersen;
 ```