docs/source/example_graphql.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# GraphQL\n",
    "\n",
    "If you want to try out this notebook with a live Python kernel, use mybinder:\n",
    "\n",
    "<a class=\"reference external image-reference\" href=\"https://mybinder.org/v2/gh/vaexio/vaex/latest?filepath=docs%2Fsource%2Fexample_graphql.ipynb\"><img alt=\"https://mybinder.org/badge_logo.svg\" src=\"https://mybinder.org/badge_logo.svg\" width=\"150px\"></a>\n",
    "\n",
    "vaex-graphql is a plugin package that exposes a DataFrame via a GraphQL interface. This allows easy sharing of data or aggregations/statistics or machine learning models to frontends or other programs with a standard query languages.\n",
    "\n",
    "(Install with `$ pip install vaex-graphql`, no conda-forge support yet)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<table>\n",
       "<thead>\n",
       "<tr><th>#                                </th><th>pclass  </th><th>survived  </th><th>name                                           </th><th>sex   </th><th>age   </th><th>sibsp  </th><th>parch  </th><th>ticket  </th><th>fare    </th><th>cabin  </th><th>embarked  </th><th>boat  </th><th>body  </th><th>home_dest                      </th></tr>\n",
       "</thead>\n",
       "<tbody>\n",
       "<tr><td><i style='opacity: 0.6'>0</i>    </td><td>1       </td><td>True      </td><td>Allen, Miss. Elisabeth Walton                  </td><td>female</td><td>29.0  </td><td>0      </td><td>0      </td><td>24160   </td><td>211.3375</td><td>B5     </td><td>S         </td><td>2     </td><td>nan   </td><td>St Louis, MO                   </td></tr>\n",
       "<tr><td><i style='opacity: 0.6'>1</i>    </td><td>1       </td><td>True      </td><td>Allison, Master. Hudson Trevor                 </td><td>male  </td><td>0.9167</td><td>1      </td><td>2      </td><td>113781  </td><td>151.55  </td><td>C22 C26</td><td>S         </td><td>11    </td><td>nan   </td><td>Montreal, PQ / Chesterville, ON</td></tr>\n",
       "<tr><td><i style='opacity: 0.6'>2</i>    </td><td>1       </td><td>False     </td><td>Allison, Miss. Helen Loraine                   </td><td>female</td><td>2.0   </td><td>1      </td><td>2      </td><td>113781  </td><td>151.55  </td><td>C22 C26</td><td>S         </td><td>None  </td><td>nan   </td><td>Montreal, PQ / Chesterville, ON</td></tr>\n",
       "<tr><td><i style='opacity: 0.6'>3</i>    </td><td>1       </td><td>False     </td><td>Allison, Mr. Hudson Joshua Creighton           </td><td>male  </td><td>30.0  </td><td>1      </td><td>2      </td><td>113781  </td><td>151.55  </td><td>C22 C26</td><td>S         </td><td>None  </td><td>135.0 </td><td>Montreal, PQ / Chesterville, ON</td></tr>\n",
       "<tr><td><i style='opacity: 0.6'>4</i>    </td><td>1       </td><td>False     </td><td>Allison, Mrs. Hudson J C (Bessie Waldo Daniels)</td><td>female</td><td>25.0  </td><td>1      </td><td>2      </td><td>113781  </td><td>151.55  </td><td>C22 C26</td><td>S         </td><td>None  </td><td>nan   </td><td>Montreal, PQ / Chesterville, ON</td></tr>\n",
       "<tr><td>...                              </td><td>...     </td><td>...       </td><td>...                                            </td><td>...   </td><td>...   </td><td>...    </td><td>...    </td><td>...     </td><td>...     </td><td>...    </td><td>...       </td><td>...   </td><td>...   </td><td>...                            </td></tr>\n",
       "<tr><td><i style='opacity: 0.6'>1,304</i></td><td>3       </td><td>False     </td><td>Zabour, Miss. Hileni                           </td><td>female</td><td>14.5  </td><td>1      </td><td>0      </td><td>2665    </td><td>14.4542 </td><td>None   </td><td>C         </td><td>None  </td><td>328.0 </td><td>None                           </td></tr>\n",
       "<tr><td><i style='opacity: 0.6'>1,305</i></td><td>3       </td><td>False     </td><td>Zabour, Miss. Thamine                          </td><td>female</td><td>nan   </td><td>1      </td><td>0      </td><td>2665    </td><td>14.4542 </td><td>None   </td><td>C         </td><td>None  </td><td>nan   </td><td>None                           </td></tr>\n",
       "<tr><td><i style='opacity: 0.6'>1,306</i></td><td>3       </td><td>False     </td><td>Zakarian, Mr. Mapriededer                      </td><td>male  </td><td>26.5  </td><td>0      </td><td>0      </td><td>2656    </td><td>7.225   </td><td>None   </td><td>C         </td><td>None  </td><td>304.0 </td><td>None                           </td></tr>\n",
       "<tr><td><i style='opacity: 0.6'>1,307</i></td><td>3       </td><td>False     </td><td>Zakarian, Mr. Ortin                            </td><td>male  </td><td>27.0  </td><td>0      </td><td>0      </td><td>2670    </td><td>7.225   </td><td>None   </td><td>C         </td><td>None  </td><td>nan   </td><td>None                           </td></tr>\n",
       "<tr><td><i style='opacity: 0.6'>1,308</i></td><td>3       </td><td>False     </td><td>Zimmerman, Mr. Leo                             </td><td>male  </td><td>29.0  </td><td>0      </td><td>0      </td><td>315082  </td><td>7.875   </td><td>None   </td><td>S         </td><td>None  </td><td>nan   </td><td>None                           </td></tr>\n",
       "</tbody>\n",
       "</table>"
      ],
      "text/plain": [
       "#      pclass    survived    name                                             sex     age     sibsp    parch    ticket    fare      cabin    embarked    boat    body    home_dest\n",
       "0      1         True        Allen, Miss. Elisabeth Walton                    female  29.0    0        0        24160     211.3375  B5       S           2       nan     St Louis, MO\n",
       "1      1         True        Allison, Master. Hudson Trevor                   male    0.9167  1        2        113781    151.55    C22 C26  S           11      nan     Montreal, PQ / Chesterville, ON\n",
       "2      1         False       Allison, Miss. Helen Loraine                     female  2.0     1        2        113781    151.55    C22 C26  S           None    nan     Montreal, PQ / Chesterville, ON\n",
       "3      1         False       Allison, Mr. Hudson Joshua Creighton             male    30.0    1        2        113781    151.55    C22 C26  S           None    135.0   Montreal, PQ / Chesterville, ON\n",
       "4      1         False       Allison, Mrs. Hudson J C (Bessie Waldo Daniels)  female  25.0    1        2        113781    151.55    C22 C26  S           None    nan     Montreal, PQ / Chesterville, ON\n",
       "...    ...       ...         ...                                              ...     ...     ...      ...      ...       ...       ...      ...         ...     ...     ...\n",
       "1,304  3         False       Zabour, Miss. Hileni                             female  14.5    1        0        2665      14.4542   None     C           None    328.0   None\n",
       "1,305  3         False       Zabour, Miss. Thamine                            female  nan     1        0        2665      14.4542   None     C           None    nan     None\n",
       "1,306  3         False       Zakarian, Mr. Mapriededer                        male    26.5    0        0        2656      7.225     None     C           None    304.0   None\n",
       "1,307  3         False       Zakarian, Mr. Ortin                              male    27.0    0        0        2670      7.225     None     C           None    nan     None\n",
       "1,308  3         False       Zimmerman, Mr. Leo                               male    29.0    0        0        315082    7.875     None     S           None    nan     None"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "import vaex.ml\n",
    "df = vaex.ml.datasets.load_titanic()\n",
    "df"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "OrderedDict([('df',\n",
       "              OrderedDict([('min',\n",
       "                            OrderedDict([('age', 0.1667), ('fare', 0.0)])),\n",
       "                           ('mean',\n",
       "                            OrderedDict([('age', 29.8811345124283),\n",
       "                                         ('fare', 33.29547928134572)])),\n",
       "                           ('max',\n",
       "                            OrderedDict([('age', 80.0), ('fare', 512.3292)])),\n",
       "                           ('groupby',\n",
       "                            OrderedDict([('sex',\n",
       "                                          OrderedDict([('count', [466, 843]),\n",
       "                                                       ('mean',\n",
       "                                                        OrderedDict([('age',\n",
       "                                                                      [28.6870706185567,\n",
       "                                                                       30.585232978723408])]))]))]))]))])"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "result = df.graphql.execute(\"\"\"\n",
    "    {\n",
    "        df {\n",
    "            min {\n",
    "                age\n",
    "                fare\n",
    "            }\n",
    "            mean {\n",
    "                age\n",
    "                fare\n",
    "            }\n",
    "            max {\n",
    "                age\n",
    "                fare\n",
    "            }\n",
    "            groupby {\n",
    "                sex {\n",
    "                   count\n",
    "                   mean {\n",
    "                       age\n",
    "                   }\n",
    "                }\n",
    "            }\n",
    "        }\n",
    "    }\n",
    "    \"\"\")\n",
    "result.data"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Pandas support\n",
    "After importing vaex.graphql, vaex also installs a pandas accessor, so it is also accessible for Pandas DataFrames."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [],
   "source": [
    "df_pandas = df.to_pandas_df()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "OrderedDict([('df',\n",
       "              OrderedDict([('row',\n",
       "                            [OrderedDict([('name', 'Anderson, Mr. Harry'),\n",
       "                                          ('survived', True)]),\n",
       "                             OrderedDict([('name',\n",
       "                                           'Andrews, Miss. Kornelia Theodosia'),\n",
       "                                          ('survived', True)])])]))])"
      ]
     },
     "execution_count": 20,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "df_pandas.graphql.execute(\"\"\"\n",
    "    {\n",
    "        df(where: {age: {_gt: 20}}) {\n",
    "            row(offset: 3, limit: 2) {\n",
    "                name\n",
    "                survived\n",
    "            }\n",
    "        }\n",
    "    }\n",
    "    \"\"\"\n",
    ").data"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Server\n",
    "\n",
    "\n",
    "The easiest way to learn to use the GraphQL language/vaex interface is to launch a server, and play with the GraphiQL graphical interface, its autocomplete, and the schema explorer.\n",
    "\n",
    "We try to stay close to the Hasura API: https://docs.hasura.io/1.0/graphql/manual/api-reference/graphql-api/query.html\n",
    "\n",
    "\n",
    "A server can be started from the command line:\n",
    "   \n",
    " `$ python -m vaex.graphql myfile.hdf5`\n",
    " \n",
    "Or from within Python using [df.graphql.serve](api.html#vaex.graphql.DataFrameAccessorGraphQL.serve)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## GraphiQL\n",
    "See https://github.com/mariobuikhuizen/ipygraphql for a graphical widget, or a [mybinder to try out a live example](https://mybinder.org/v2/gh/mariobuikhuizen/ipygraphql/master?filepath=example.ipynb).\n",
    "![image](https://user-images.githubusercontent.com/1765949/66774282-8b057400-eec1-11e9-97ac-5b40f37bd30f.gif)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}