02-Create-a-Table.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Create a Table\n",
    "\n",
    "Before we can add any data to our database, we'll need to create a table in which to hold it.\n",
    "\n",
    "First, let's connect to our database:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import sqlalchemy as sa\n",
    "engine = sa.create_engine('sqlite:///flight.db')\n",
    "connection = engine.connect()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We want to hold readings of temperature and pressure taken during balloon flights.\n",
    "\n",
    "We'll use a table with eight columns for the flight name, a timestamp, measured values for temperature, pressure and humidity and some readings from an onboard accelerometer.\n",
    "\n",
    "Here's the sql to create that table:\n",
    "\n",
    "```sql\n",
    "CREATE TABLE readings (\n",
    "    flight,\n",
    "    ts,\n",
    "    temp,\n",
    "    pressure,\n",
    "    humidity,\n",
    "    accel_x,\n",
    "    accel_y,\n",
    "    accel_z,\n",
    ")\n",
    "```\n",
    "**NOTE:** _It is a common convention that SQL keywords are capitalised but this isn't strictly necessary in order to be valid SQL. It's largely redundant today since most editors will apply syntax highlighting to SQL but, for this tutorial, the convention is useful as we'll see shortly._\n",
    "\n",
    "Although this SQL statement would work perfectly in SQLite, it is non-standard and wouldn't work in any other DBMS.\n",
    "\n",
    "In most DBMSs, we have to define the data type for each column. For the purposes of this tutorial, we'll write SQL that conforms to the standard and would work in any DBMS including SQLite.\n",
    "\n",
    "For a full description of exactly how SQLite differs, you can read the [SQLite documentation](https://www.sqlite.org/datatype3.html).\n",
    "\n",
    "Here's the standard form of the SQL to create our table with the data types included:\n",
    "\n",
    "```sql\n",
    "CREATE TABLE readings (\n",
    "    flight    VARCHAR(10),\n",
    "    ts        TIMESTAMP,\n",
    "    temp      NUMERIC(3,1),\n",
    "    pressure  NUMERIC(4,0),\n",
    "    humidity  NUMERIC(3,0),\n",
    "    accel_x   REAL,\n",
    "    accel_y   REAL,\n",
    "    accel_z   REAL,\n",
    ")\n",
    "```\n",
    "We defined the flight name as a variable length character string (VARCHAR) and we set a maximum length for those strings of 10 characters.\n",
    "\n",
    "Most DBMSs have a VARCHAR data type (although they may use a different name) and also a type for holding strings of fixed length.\n",
    "\n",
    "The column 'ts' will hold the date and time of the reading.\n",
    "\n",
    "For the temperature, pressure and humidity values, we defined those to be numeric values with precision  (the maximum number of digits in the number) and scale (the number of digits following the decimal point). \n",
    "\n",
    "i.e. Temperature readings will have 3 digits in total with one of those to the right of the decimal point. Pressure and humidity readings will both be integers of 4 and 3 digits respectively.\n",
    "\n",
    "The accelerometer readings will be floating point numbers.\n",
    "\n",
    "By default, each column will allow null values but we can specify that nulls are not allowed and, optionally, whether a default value should be used instead:\n",
    "\n",
    "```sql\n",
    "CREATE TABLE readings (\n",
    "    flight    VARCHAR(10) NOT NULL,\n",
    "    ts        TIMESTAMP NOT NULL,\n",
    "    temp      NUMERIC(3,1) NOT NULL,\n",
    "    pressure  NUMERIC(4,0) NOT NULL,\n",
    "    humidity  NUMERIC(3,0) NOT NULL,\n",
    "    accel_x   REAL DEFAULT 0 NOT NULL,\n",
    "    accel_y   REAL DEFAULT 0 NOT NULL,\n",
    "    accel_z   REAL DEFAULT 0 NOT NULL,\n",
    ")\n",
    "```\n",
    "\n",
    "We can (and should) define a 'primary key' constraint for the table. This defines a field, or combination of fields, which must be unique for each record. The primary key can then be used by the DBMS to perform efficient indexed searches of the table contents.\n",
    "\n",
    "The constraint is given a name which, by convention, is often suffixed with \\_pk but can be anything you like:\n",
    "\n",
    "```sql\n",
    "CREATE TABLE readings (\n",
    "    flight    VARCHAR(10) NOT NULL,\n",
    "    ts        TIMESTAMP NOT NULL,\n",
    "    temp      NUMERIC(3,1) NOT NULL,\n",
    "    pressure  NUMERIC(4,0) NOT NULL,\n",
    "    humidity  NUMERIC(3,0) NOT NULL,\n",
    "    accel_x   REAL DEFAULT 0 NOT NULL,\n",
    "    accel_y   REAL DEFAULT 0 NOT NULL,\n",
    "    accel_z   REAL DEFAULT 0 NOT NULL,\n",
    "\n",
    "    CONSTRAINT readings_pk PRIMARY KEY (flight, ts),\n",
    ")\n",
    "```\n",
    "\n",
    "We can also add constraints to each column so that the database will throw an error if any attempt is made to enter invalid values. These are know as CHECK constraints and again, each has a name - commonly the field to which the constraint applies followed by \\_ck:\n",
    "\n",
    "\n",
    "```sql\n",
    "CREATE TABLE readings (\n",
    "    flight    VARCHAR(10) NOT NULL,\n",
    "    ts        TIMESTAMP NOT NULL,\n",
    "    temp      NUMERIC(3,1) NOT NULL,\n",
    "    pressure  NUMERIC(4,0) NOT NULL,\n",
    "    humidity  NUMERIC(3,0) NOT NULL,\n",
    "    accel_x   REAL DEFAULT 0 NOT NULL,\n",
    "    accel_y   REAL DEFAULT 0 NOT NULL,\n",
    "    accel_z   REAL DEFAULT 0 NOT NULL,\n",
    "\n",
    "    CONSTRAINT readings_pk PRIMARY KEY (flight, ts),\n",
    "    CONSTRAINT temp_ck CHECK (temp BETWEEN -70 AND 70),\n",
    "    CONSTRAINT pres_ck CHECK (pressure BETWEEN 0 AND 2000),\n",
    "    CONSTRAINT hum_ck CHECK (humidity BETWEEN 0 AND 100)\n",
    ")\n",
    "```\n",
    "\n",
    "In order to execute an SQL statement, we use the 'execute' method of our connection object and pass it our SQL statement as a string.\n",
    "\n",
    "Let's create a variable to hold our SQL statement and pass that variable to the execute method.\n",
    "\n",
    "_This technique is why the capitalisation convention is useful for us. Most editors cannot handle syntax highlighting for SQL within string variables_"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<sqlalchemy.engine.result.ResultProxy at 0x10eccd0f0>"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "sql = \"\"\"\n",
    "CREATE TABLE readings (\n",
    "    flight    VARCHAR(10) NOT NULL,\n",
    "    ts        TIMESTAMP NOT NULL,\n",
    "    temp      NUMERIC(3,1) NOT NULL,\n",
    "    pressure  NUMERIC(4,0) NOT NULL,\n",
    "    humidity  NUMERIC(3,0) NOT NULL,\n",
    "    accel_x   REAL DEFAULT 0 NOT NULL,\n",
    "    accel_y   REAL DEFAULT 0 NOT NULL,\n",
    "    accel_z   REAL DEFAULT 0 NOT NULL,\n",
    "\n",
    "    CONSTRAINT readings_pk PRIMARY KEY (flight, ts),\n",
    "    CONSTRAINT temp_ck CHECK (temp BETWEEN -70 AND 70),\n",
    "    CONSTRAINT pres_ck CHECK (pressure BETWEEN 0 AND 2000),\n",
    "    CONSTRAINT hum_ck CHECK (humidity BETWEEN 0 AND 100)\n",
    ")\n",
    "\"\"\"\n",
    "connection.execute(sql)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you opted to [run the code on your own computer](http://owencampbell.me.uk/pages/howto#howto-local) and also installed the graphical tool, you should now be able to open 'flight.db' and see the new table within your database."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python [conda env:sql_python_tutorial]",
   "language": "python",
   "name": "conda-env-sql_python_tutorial-py"
  },
  "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.6.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}