docs: add sample notebook for magics

Author: tswast

notebooks/getting_started/magics.ipynb

@@ -1,35 +1,46 @@
 {
  "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "91edcf7b",
+   "metadata": {},
+   "source": [
+    "# %%bqsql cell magics\n",
+    "\n",
+    "The BigQuery DataFrames (aka BigFrames) package provides a `%%bqsql` cell magics for Jupyter environments.\n",
+    "\n",
+    "To use it, first activate the extension:"
+   ]
+  },
   {
    "cell_type": "code",
-   "execution_count": 3,
+   "execution_count": 1,
    "id": "98cd0489",
    "metadata": {},
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "The bigframes extension is already loaded. To reload it, use:\n",
-      "  %reload_ext bigframes\n"
-     ]
-    }
-   ],
+   "outputs": [],
    "source": [
     "%load_ext bigframes"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "f18fdc63",
+   "metadata": {},
+   "source": [
+    "Now, use the magics by including SQL in the body."
+   ]
+  },
   {
    "cell_type": "code",
-   "execution_count": 4,
+   "execution_count": 2,
    "id": "269c5862",
    "metadata": {},
    "outputs": [
     {
      "data": {
       "text/html": [
        "\n",
-       "    Query processed 0 Bytes. [<a target=\"_blank\" href=\"https://console.cloud.google.com/bigquery?project=bigframes-dev&j=bq:US:job_HiiqKoJVBj9_EYqkrjVsmzkVZCb5&page=queryresults\">Job bigframes-dev:US.job_HiiqKoJVBj9_EYqkrjVsmzkVZCb5 details</a>]\n",
+       "    Query processed 0 Bytes. [<a target=\"_blank\" href=\"https://console.cloud.google.com/bigquery?project=bigframes-dev&j=bq:US:job_UVe7FsupxF3CbYuLcLT7fpw9dozg&page=queryresults\">Job bigframes-dev:US.job_UVe7FsupxF3CbYuLcLT7fpw9dozg details</a>]\n",
        "    "
       ],
       "text/plain": [
@@ -42,7 +53,7 @@
     {
      "data": {
       "application/vnd.jupyter.widget-view+json": {
-       "model_id": "c6fbeec6762f4a3fa0c9d3e71ca4c00d",
+       "model_id": "1e2fb7b019754d31b11323a054f97f47",
        "version_major": 2,
        "version_minor": 1
       },
@@ -184,11 +195,189 @@
     "SELECT * FROM `bigquery-public-data.usa_names.usa_1910_2013`"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "8771e10f",
+   "metadata": {},
+   "source": [
+    "The output DataFrame can be saved to a variable."
+   ]
+  },
   {
    "cell_type": "code",
-   "execution_count": null,
+   "execution_count": 3,
    "id": "30bb6327",
    "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/html": [
+       "\n",
+       "    Query processed 0 Bytes. [<a target=\"_blank\" href=\"https://console.cloud.google.com/bigquery?project=bigframes-dev&j=bq:US:c142adf3-cd95-42da-bbdc-c176b36b934f&page=queryresults\">Job bigframes-dev:US.c142adf3-cd95-42da-bbdc-c176b36b934f details</a>]\n",
+       "    "
+      ],
+      "text/plain": [
+       "<IPython.core.display.HTML object>"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    }
+   ],
+   "source": [
+    "%%bqsql mydf\n",
+    "SELECT * FROM `bigquery-public-data.usa_names.usa_1910_2013`"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "533e2e9e",
+   "metadata": {},
+   "source": [
+    "You can chain cells together using format strings. DataFrame objects are automatically turned into table expressions."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "id": "6a8a8123",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/html": [
+       "\n",
+       "    Query processed 88.1 MB in a moment of slot time.\n",
+       "    "
+      ],
+      "text/plain": [
+       "<IPython.core.display.HTML object>"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    },
+    {
+     "data": {
+      "application/vnd.jupyter.widget-view+json": {
+       "model_id": "c4889de9296440428de90defb5c58070",
+       "version_major": 2,
+       "version_minor": 1
+      },
+      "text/html": [
+       "<div>\n",
+       "<style scoped>\n",
+       "    .dataframe tbody tr th:only-of-type {\n",
+       "        vertical-align: middle;\n",
+       "    }\n",
+       "\n",
+       "    .dataframe tbody tr th {\n",
+       "        vertical-align: top;\n",
+       "    }\n",
+       "\n",
+       "    .dataframe thead th {\n",
+       "        text-align: right;\n",
+       "    }\n",
+       "</style>\n",
+       "<table border=\"1\" class=\"dataframe\">\n",
+       "  <thead>\n",
+       "    <tr style=\"text-align: right;\">\n",
+       "      <th></th>\n",
+       "      <th>total_count</th>\n",
+       "      <th>name</th>\n",
+       "    </tr>\n",
+       "  </thead>\n",
+       "  <tbody>\n",
+       "    <tr>\n",
+       "      <th>0</th>\n",
+       "      <td>304036</td>\n",
+       "      <td>Tracy</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>1</th>\n",
+       "      <td>293876</td>\n",
+       "      <td>Travis</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>2</th>\n",
+       "      <td>203784</td>\n",
+       "      <td>Troy</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>3</th>\n",
+       "      <td>150127</td>\n",
+       "      <td>Trevor</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>4</th>\n",
+       "      <td>96397</td>\n",
+       "      <td>Tristan</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>5</th>\n",
+       "      <td>89996</td>\n",
+       "      <td>Tracey</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>6</th>\n",
+       "      <td>65546</td>\n",
+       "      <td>Trinity</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>7</th>\n",
+       "      <td>50112</td>\n",
+       "      <td>Traci</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>8</th>\n",
+       "      <td>49657</td>\n",
+       "      <td>Trenton</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>9</th>\n",
+       "      <td>45692</td>\n",
+       "      <td>Trent</td>\n",
+       "    </tr>\n",
+       "  </tbody>\n",
+       "</table>\n",
+       "<p>10 rows × 2 columns</p>\n",
+       "</div>[238 rows x 2 columns in total]"
+      ],
+      "text/plain": [
+       "   total_count     name\n",
+       "0       304036    Tracy\n",
+       "1       293876   Travis\n",
+       "2       203784     Troy\n",
+       "3       150127   Trevor\n",
+       "4        96397  Tristan\n",
+       "5        89996   Tracey\n",
+       "6        65546  Trinity\n",
+       "7        50112    Traci\n",
+       "8        49657  Trenton\n",
+       "9        45692    Trent\n",
+       "...\n",
+       "\n",
+       "[238 rows x 2 columns]"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    }
+   ],
+   "source": [
+    "%%bqsql\n",
+    "SELECT sum(number) as total_count, name\n",
+    "FROM {mydf}\n",
+    "WHERE name LIKE 'Tr%'\n",
+    "GROUP BY name\n",
+    "ORDER BY total_count DESC"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "d2a17078",
+   "metadata": {},
    "outputs": [],
    "source": []
   }