Skip to content
This repository

Writing doc about I/O SQL features. See #2541 #2652

Closed
wants to merge 2 commits into from

2 participants

Damien Garaud Wes McKinney
Damien Garaud

Hi there,

I wrote some contents about I/O SQL pandas features:

  • some examples about the read_frame function with SQLite ;
  • list other functions such as tquery (without example) ;
  • write a tiny note about write_frame function.

I'm not sure about the title of this section. Any proposal is welcome ! Don't hesitate to comment the content (typo, misunderstanding, ...)

Cheers

Damien G.

garaud and others added some commits
Damien Garaud

closes #2541

Wes McKinney
Owner

thanks!

Wes McKinney wesm closed this
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Showing 2 unique commits by 2 authors.

Dec 21, 2012
Damien Garaud garaud DOC: Write a section about SQL query wrappers to I/O part. close 2541 cebe215
Jan 07, 2013
Damien Garaud garaud DOC: Complete IO/SQL part.
- Change the title.
- List other functions of the module 'io.sql'.
1d20c7a
This page is out of date. Refresh to see the latest.

Showing 1 changed file with 99 additions and 0 deletions. Show diff stats Hide diff stats

  1. +99 0 doc/source/io.rst
99 doc/source/io.rst
Source Rendered
@@ -1251,3 +1251,102 @@ These, by default, index the three axes ``items, major_axis, minor_axis``. On an
1251 1251 store.close()
1252 1252 import os
1253 1253 os.remove('store.h5')
  1254 +
  1255 +
  1256 +.. _io.sql:
  1257 +
  1258 +SQL Queries
  1259 +-----------
  1260 +
  1261 +The :mod:`pandas.io.sql` module provides a collection of query wrappers to both
  1262 +facilitate data retrieval and to reduce dependency on DB-specific API. There
  1263 +wrappers only support the Python database adapters which respect the `Python
  1264 +DB-API <http://www.python.org/dev/peps/pep-0249/>`_.
  1265 +
  1266 +Suppose you want to query some data with different types from a table such as:
  1267 +
  1268 ++-----+------------+-------+-------+-------+
  1269 +| id | Date | Col_1 | Col_2 | Col_3 |
  1270 ++=====+============+=======+=======+=======+
  1271 +| 26 | 2012-10-18 | X | 25.7 | True |
  1272 ++-----+------------+-------+-------+-------+
  1273 +| 42 | 2012-10-19 | Y | -12.4 | False |
  1274 ++-----+------------+-------+-------+-------+
  1275 +| 63 | 2012-10-20 | Z | 5.73 | True |
  1276 ++-----+------------+-------+-------+-------+
  1277 +
  1278 +Functions from :mod:`pandas.io.sql` can extract some data into a DataFrame. In
  1279 +the following example, we use `SQlite <http://www.sqlite.org/>`_ SQL database
  1280 +engine. You can use a temporary SQLite database where data are stored in
  1281 +"memory". Just do:
  1282 +
  1283 +.. code-block:: python
  1284 +
  1285 + import sqlite3
  1286 + from pandas.io import sql
  1287 + # Create your connection.
  1288 + cnx = sqlite3.connect(':memory:')
  1289 +
  1290 +.. ipython:: python
  1291 + :suppress:
  1292 +
  1293 + import sqlite3
  1294 + from pandas.io import sql
  1295 + cnx = sqlite3.connect(':memory:')
  1296 +
  1297 +.. ipython:: python
  1298 + :suppress:
  1299 +
  1300 + cu = cnx.cursor()
  1301 + # Create a table named 'data'.
  1302 + cu.execute("""CREATE TABLE data(id integer,
  1303 + date date,
  1304 + Col_1 string,
  1305 + Col_2 float,
  1306 + Col_3 bool);""")
  1307 + cu.executemany('INSERT INTO data VALUES (?,?,?,?,?)',
  1308 + [(26, datetime(2010,10,18), 'X', 27.5, True),
  1309 + (42, datetime(2010,10,19), 'Y', -12.5, False),
  1310 + (63, datetime(2010,10,20), 'Z', 5.73, True)])
  1311 +
  1312 +
  1313 +Let ``data`` be the name of your SQL table. With a query and your database
  1314 +connection, just use the :func:`~pandas.io.sql.read_frame` function to get the
  1315 +query results into a DataFrame:
  1316 +
  1317 +.. ipython:: python
  1318 +
  1319 + sql.read_frame("SELECT * FROM data;", cnx)
  1320 +
  1321 +You can also specify the name of the column as the DataFrame index:
  1322 +
  1323 +.. ipython:: python
  1324 +
  1325 + sql.read_frame("SELECT * FROM data;", cnx, index_col='id')
  1326 + sql.read_frame("SELECT * FROM data;", cnx, index_col='date')
  1327 +
  1328 +Of course, you can specify more "complex" query.
  1329 +
  1330 +.. ipython:: python
  1331 +
  1332 + sql.read_frame("SELECT id, Col_1, Col_2 FROM data WHERE id = 42;", cnx)
  1333 +
  1334 +.. ipython:: python
  1335 + :suppress:
  1336 +
  1337 + cu.close()
  1338 + cnx.close()
  1339 +
  1340 +
  1341 +There are a few other available functions:
  1342 +
  1343 + - ``tquery`` returns list of tuples corresponding to each row.
  1344 + - ``uquery`` does the same thing as tquery, but instead of returning results,
  1345 + it returns the number of related rows.
  1346 + - ``write_frame`` writes records stored in a DataFrame into the SQL table.
  1347 + - ``has_table`` checks if a given SQLite table exists.
  1348 +
  1349 +.. note::
  1350 +
  1351 + For now, writing your DataFrame into a database works only with
  1352 + **SQLite**. Moreover, the **index** will currently be **dropped**.

Tip: You can add notes to lines in a file. Hover to the left of a line to make a note

Something went wrong with that request. Please try again.