{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f687df90",
   "metadata": {
    "tags": [
     "hide-output"
    ]
   },
   "outputs": [],
   "source": [
    "!pip install pandas gql requests_toolbelt"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1fdebf43",
   "metadata": {},
   "outputs": [],
   "source": [
    "import pandas as pd\n",
    "from gql import gql, Client\n",
    "from gql.transport.requests import RequestsHTTPTransport"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "76fa365c-b6d9-479f-99d8-d0d53ec30e8e",
   "metadata": {},
   "source": [
    "# GraphQL Examples\n",
    "\n",
    "In this notebook we explore searching for metadata from the GraphQL API. The GraphQL API provides a method to programmatically extract a JSON representation of the meta data from the API. It has the advantage over REST that it can prevent under and over fetching data.\n",
    "\n",
    "First we load some python dependancies that we will use as part of this notebook and set the variable `API_URL` to the location of the GraphQL API."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ebba03b7-34c4-4b49-94d8-112c7176ac7f",
   "metadata": {},
   "outputs": [],
   "source": [
    "# This is the location of the GraphQL API\n",
    "API_URL = \"https://mastapp.site/graphql\""
   ]
  },
  {
   "cell_type": "markdown",
   "id": "22ff9d86",
   "metadata": {},
   "source": [
    "Setup a `gql` client. This is used to query the graphql API"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "bc504ba6",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Select your transport with a defined url endpoint\n",
    "transport = RequestsHTTPTransport(url=API_URL)\n",
    "# Create a GraphQL client using the defined transport\n",
    "client = Client(transport=transport, fetch_schema_from_transport=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8a9a779a-3cc2-4557-8cb1-a9849f01a434",
   "metadata": {},
   "source": [
    "## Querying Shots with GraphQL\n",
    "\n",
    "With GraphQL you can query exactly what you want, rather than having to recieve the whole table from the database This is useful in cases where the whole table has many columns, but you are interested in just a subset of them.\n",
    "\n",
    "The GraphQL endpoint is located at `/graphql`. You can find the documentation and an interactive query explorer at the URL below:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "dfb0f1c7",
   "metadata": {},
   "outputs": [],
   "source": [
    "print(f\"GraphQL API Endpoint {API_URL}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fa9ab9b8",
   "metadata": {},
   "source": [
    "Unlike the REST API which uses HTTP `GET` requests to return data, with GraphQL we use HTTP `POST` to post our query to the API.\n",
    "\n",
    "Here is a simple example of getting some shot data from the GraphQL API. We need to explicity state what information we want to return from the API. Here we are asking for:\n",
    " - the shot ID\n",
    " - the timestamp that the shot was taken\n",
    " - the preshot description\n",
    " - the divertor configuration"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "4970f970-2e6a-414a-8722-427f57c62964",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Write our GraphQL query.\n",
    "query = gql(\"\"\"\n",
    "query {\n",
    "    all_shots  {\n",
    "        shots {\n",
    "            shot_id\n",
    "            timestamp\n",
    "            preshot_description\n",
    "            divertor_config\n",
    "        }\n",
    "    }\n",
    "}\n",
    "\"\"\")\n",
    "\n",
    "# # Query the API and get a JSON response\n",
    "result = client.execute(query)\n",
    "shots = result['all_shots']['shots']\n",
    "df = pd.DataFrame(shots)\n",
    "df.head()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6c8a11b9",
   "metadata": {},
   "source": [
    "### Searching & Filtering Data\n",
    "We can also supply query parameters to GraphQL, such as limiting the number of returned values or filtering by value. Here we are limiting the first 3 values and we are selcting only shots from the M9 campaign."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "399c75c1-16ab-4a34-b968-5a9f3c6f99e0",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Write our GraphQL query.\n",
    "query = gql(\"\"\"\n",
    "query ($campaign: String!) {\n",
    "    all_shots (limit: 3, where: {campaign: {eq: $campaign}}) {\n",
    "        shots {\n",
    "            shot_id\n",
    "            timestamp\n",
    "            preshot_description\n",
    "            divertor_config\n",
    "        }\n",
    "    }\n",
    "}\n",
    "\"\"\")\n",
    "# Query the API and get a JSON response\n",
    "result = client.execute(query, variable_values={\"campaign\": \"M9\"})\n",
    "df = pd.DataFrame(result['all_shots']['shots'])\n",
    "df.head()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5aa79e2b",
   "metadata": {},
   "source": [
    "### Nested Queries\n",
    "\n",
    "One feature which makes GraphQL much more powerful than REST is that you may perform nested queries to gather different subsets of the data. For example, here we are going to query for all datasets with \"AMC\" in the name, and query for information about shots associated with this dataset."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "88bdab08",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Write our GraphQL query.\n",
    "query = gql(\"\"\"\n",
    "query ($signal: String!) {\n",
    "    all_signals (limit: 3, where: {name: {contains: $signal}}) {\n",
    "        signals {\n",
    "          name\n",
    "          url\n",
    "          shot {\n",
    "            shot_id\n",
    "            timestamp\n",
    "            divertor_config\n",
    "          }\n",
    "        }\n",
    "    }\n",
    "}\n",
    "\"\"\")\n",
    "# Query the API and get a JSON response\n",
    "client.execute(query, variable_values={\"signal\": \"AMC\"})"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6e2ac419-db72-4a95-88a0-d5226b399376",
   "metadata": {},
   "source": [
    "### Pagination in GraphQL\n",
    "\n",
    "GraphQL queries are paginated. You may access other entries by including the page metadata and its associated elements. Here's an example of getting paginated entries:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f4566e66-215c-4d41-aa3a-44fb9d6a0447",
   "metadata": {},
   "outputs": [],
   "source": [
    "def do_query(cursor: str = None):\n",
    "    query = gql(\"\"\"\n",
    "    query ($cursor: String) {\n",
    "        all_shots (limit: 3, where: {campaign: {contains: \"M9\"}}, cursor: $cursor) {\n",
    "            shots {\n",
    "                shot_id\n",
    "                timestamp\n",
    "                preshot_description\n",
    "                divertor_config\n",
    "            }\n",
    "            page_meta {\n",
    "              next_cursor\n",
    "              total_items\n",
    "              total_pages\n",
    "            }\n",
    "        }\n",
    "    }\n",
    "    \"\"\")\n",
    "    return client.execute(query, {'cursor': cursor})\n",
    "\n",
    "\n",
    "def iterate_responses():\n",
    "    cursor = None\n",
    "    while True:\n",
    "        response = do_query(cursor)\n",
    "        yield response\n",
    "        cursor = response['all_shots']['page_meta']['next_cursor']\n",
    "        if cursor is None:\n",
    "            return\n",
    "\n",
    "responses = iterate_responses()\n",
    "print(next(responses))\n",
    "print(next(responses))\n",
    "print(next(responses))"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": ".venv",
   "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.13.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}