From cebe215517478a56c4a117e07d21d9c743cd54e2 Mon Sep 17 00:00:00 2001
From: Damien Garaud <damien.garaud@gmail.com>
Date: Fri, 21 Dec 2012 00:56:08 +0100
Subject: [PATCH 1/2] DOC: Write a section about SQL query wrappers to I/O
 part. close 2541

---
 doc/source/io.rst | 95 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 95 insertions(+)

diff --git a/doc/source/io.rst b/doc/source/io.rst
index c73240725887f..1bf17bf7c0293 100644
--- a/doc/source/io.rst
+++ b/doc/source/io.rst
@@ -1251,3 +1251,98 @@ These, by default, index the three axes ``items, major_axis, minor_axis``. On an
    store.close()
    import os
    os.remove('store.h5')
+
+
+.. _io.sql:
+
+DataBase Queries
+----------------
+
+The :mod:`pandas.io.sql` module provides a collection of query wrappers to both
+facilitate data retrieval and to reduce dependency on DB-specific API. There
+wrappers only support the Python database adapters which respect the `Python
+DB-API <http://www.python.org/dev/peps/pep-0249/>`_.
+
+Suppose you want to query some data with different types from a table such as:
+
++-----+------------+-------+-------+-------+
+| id  |    Date    | Col_1 | Col_2 | Col_3 |
++=====+============+=======+=======+=======+
+| 26  | 2012-10-18 |   X   |  25.7 | True  |
++-----+------------+-------+-------+-------+
+| 42  | 2012-10-19 |   Y   | -12.4 | False |
++-----+------------+-------+-------+-------+
+| 63  | 2012-10-20 |   Z   |  5.73 | True  |
++-----+------------+-------+-------+-------+
+
+Functions from :mod:`pandas.io.sql` can extract some data into a DataFrame. In
+the following example, we use `SQlite <http://www.sqlite.org/>`_ SQL database
+engine. You can use a temporary SQLite database where data are stored in
+"memory". Just do:
+
+.. code-block:: python
+
+   import sqlite3
+   from pandas.io import sql
+   # Create your connection.
+   cnx = sqlite3.connect(':memory:')
+
+.. ipython:: python
+   :suppress:
+
+   import sqlite3
+   from pandas.io import sql
+   cnx = sqlite3.connect(':memory:')
+
+.. ipython:: python
+   :suppress:
+
+   cu = cnx.cursor()
+   # Create a table named 'data'.
+   cu.execute("""CREATE TABLE data(id integer,
+                                   date date,
+                                   Col_1 string,
+                                   Col_2 float,
+                                   Col_3 bool);""")
+   cu.executemany('INSERT INTO data VALUES (?,?,?,?,?)',
+                  [(26, datetime(2010,10,18), 'X', 27.5, True),
+                   (42, datetime(2010,10,19), 'Y', -12.5, False),
+                   (63, datetime(2010,10,20), 'Z', 5.73, True)])
+
+
+Let ``data`` be the name of your SQL table. With a query and your database
+connection, just use the :func:`~pandas.io.sql.read_frame` function to get the
+query results into a DataFrame:
+
+.. ipython:: python
+
+   sql.read_frame("SELECT * FROM data;", cnx)
+
+You can also specify the name of the column as the DataFrame index:
+
+.. ipython:: python
+
+   sql.read_frame("SELECT * FROM data;", cnx, index_col='id')
+   sql.read_frame("SELECT * FROM data;", cnx, index_col='date')
+
+Of course, you can specify more "complex" query.
+
+.. ipython:: python
+
+   sql.read_frame("SELECT id, Col_1, Col_2 FROM data WHERE id = 42;", cnx)
+
+.. ipython:: python
+   :suppress:
+
+   cu.close()
+   cnx.close()
+
+.. note::
+
+   For now, writing your DataFrame into a database works only with
+   SQLite. Moreover, the index will currently be dropped.
+
+.. todo::
+
+   - methods list
+

From 1d20c7a07ab9927c651f6e2267a88ef1b0caad44 Mon Sep 17 00:00:00 2001
From: Damien Garaud <damien.garaud@logilab.fr>
Date: Mon, 7 Jan 2013 13:46:45 +0100
Subject: [PATCH 2/2] DOC: Complete IO/SQL part.

- Change the title.
- List other functions of the module 'io.sql'.
---
 doc/source/io.rst | 18 +++++++++++-------
 1 file changed, 11 insertions(+), 7 deletions(-)

diff --git a/doc/source/io.rst b/doc/source/io.rst
index 1bf17bf7c0293..6abaee8f8f070 100644
--- a/doc/source/io.rst
+++ b/doc/source/io.rst
@@ -1255,8 +1255,8 @@ These, by default, index the three axes ``items, major_axis, minor_axis``. On an
 
 .. _io.sql:
 
-DataBase Queries
-----------------
+SQL Queries
+-----------
 
 The :mod:`pandas.io.sql` module provides a collection of query wrappers to both
 facilitate data retrieval and to reduce dependency on DB-specific API. There
@@ -1337,12 +1337,16 @@ Of course, you can specify more "complex" query.
    cu.close()
    cnx.close()
 
-.. note::
 
-   For now, writing your DataFrame into a database works only with
-   SQLite. Moreover, the index will currently be dropped.
+There are a few other available functions:
 
-.. todo::
+  - ``tquery`` returns list of tuples corresponding to each row.
+  - ``uquery`` does the same thing as tquery, but instead of returning results,
+    it returns the number of related rows.
+  - ``write_frame`` writes records stored in a DataFrame into the SQL table.
+  - ``has_table`` checks if a given SQLite table exists.
 
-   - methods list
+.. note::
 
+   For now, writing your DataFrame into a database works only with
+   **SQLite**. Moreover, the **index** will currently be **dropped**.