{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "compatible-thickness",
   "metadata": {},
   "source": [
    "This notebook briefly introduces you into doing TAP/ADQL queries interactively using the pyVO package (on Debian-derived systems, do ``apt install python3-pyvo``; otherwise, see http://pypi.org/project/pyvo).\n",
    "\n",
    "Note that for this sort of interactive use, most people prefer TOPCAT (Debian: topcat; otherwise http://www.star.bris.ac.uk/~mbt/topcat)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "inner-highway",
   "metadata": {},
   "outputs": [],
   "source": [
    "import pyvo\n",
    "# Also, shut up a few overzealous warnings\n",
    "import warnings\n",
    "warnings.filterwarnings('ignore', module=\"astropy.io.votable.*\")\n",
    "warnings.filterwarnings('ignore', module=\"pyvo.utils.xml.elements\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "intensive-performance",
   "metadata": {},
   "source": [
    "You typcially first have to discover a TAP service, perhaps based on names (blind discovery, finding tables by topic or coverage, is left as an exercise to the reader; see https://pyvo.readthedocs.io/en/latest/registry for inspration)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "demonstrated-groove",
   "metadata": {},
   "outputs": [],
   "source": [
    "svcs = pyvo.registry.search(servicetype=\"tap\", keywords=\"rave\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "floral-translator",
   "metadata": {},
   "source": [
    "You can now browse the various services matching your constraints."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "dynamic-solomon",
   "metadata": {},
   "outputs": [],
   "source": [
    "svcs.to_table().show_in_notebook()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "assigned-activation",
   "metadata": {},
   "source": [
    "Pick one of them by index of short name:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "tested-button",
   "metadata": {},
   "outputs": [],
   "source": [
    "svc = svcs[\"GAVO DC TAP\"].get_service()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "convertible-training",
   "metadata": {},
   "source": [
    "Equivalently, if you have the TAP access URL right away, you can directly construct a TAP service like this:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "prompt-camera",
   "metadata": {},
   "outputs": [],
   "source": [
    "svc = pyvo.dal.TAPService(\"http://dc.g-vo.org/tap\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "executive-button",
   "metadata": {},
   "source": [
    "Once you have such a service, you can see what tables are on it:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "adaptive-balloon",
   "metadata": {},
   "outputs": [],
   "source": [
    "svc.tables.describe()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "expensive-skirt",
   "metadata": {},
   "source": [
    "...and then inspect the columns of each table:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "desperate-peninsula",
   "metadata": {},
   "outputs": [],
   "source": [
    "svc.tables[\"rave.main\"].columns[:10]"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "greatest-nature",
   "metadata": {},
   "source": [
    "Based on this, you can now run your queries:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "included-trading",
   "metadata": {},
   "outputs": [],
   "source": [
    "res = svc.run_sync(\"SELECT TOP 5 raveid, raj2000, dej2000, rv FROM rave.main\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "junior-purple",
   "metadata": {},
   "source": [
    "The results's to_table method returns a normal astropy table:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "decimal-soldier",
   "metadata": {},
   "outputs": [],
   "source": [
    "res.to_table().show_in_notebook()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "stylish-virgin",
   "metadata": {},
   "source": [
    "For longer-running jobs, you can also run async jobs:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "educational-light",
   "metadata": {},
   "outputs": [],
   "source": [
    "svc.run_async(\"SELECT TOP 5 raveid, raj2000, dej2000, rv FROM rave.main\"\n",
    "            ).to_table().show_in_notebook()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "precious-rotation",
   "metadata": {},
   "source": [
    "Finally, the examples you see in TOPCAT are also available in pyVO, although for browsing you will probably want to go to the service's examples endpoint:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "affiliated-particle",
   "metadata": {},
   "outputs": [],
   "source": [
    "import webbrowser, pprint\n",
    "webbrowser.open(svc.baseurl+\"/examples\")\n",
    "pprint.pprint(svc.examples[:3])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "dynamic-spice",
   "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.9.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}