Skip to content

Commit e6a531d

Browse files
API: update SQL functional api #6300
1 parent f30278e commit e6a531d

File tree

5 files changed

+223
-158
lines changed

5 files changed

+223
-158
lines changed

doc/source/api.rst

Lines changed: 3 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -78,17 +78,11 @@ SQL
7878

7979
.. autosummary::
8080
:toctree: generated/
81-
81+
82+
read_sql_table
83+
read_sql_query
8284
read_sql
8385

84-
.. currentmodule:: pandas.io.sql
85-
86-
.. autosummary::
87-
:toctree: generated/
88-
89-
read_frame
90-
write_frame
91-
9286
Google BigQuery
9387
~~~~~~~~~~~~~~~
9488
.. currentmodule:: pandas.io.gbq

doc/source/io.rst

Lines changed: 33 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -3113,11 +3113,22 @@ DB-API <http://www.python.org/dev/peps/pep-0249/>`__.
31133113
See also some :ref:`cookbook examples <cookbook.sql>` for some advanced strategies.
31143114

31153115
The key functions are:
3116-
:func:`~pandas.io.sql.to_sql`
3117-
:func:`~pandas.io.sql.read_sql`
3118-
:func:`~pandas.io.sql.read_table`
31193116

3117+
.. autosummary::
3118+
:toctree: generated/
3119+
3120+
read_sql_table
3121+
read_sql_query
3122+
read_sql
3123+
DataFrame.to_sql
31203124

3125+
.. note::
3126+
3127+
The function :func:`~pandas.read_sql` is a convenience wrapper around
3128+
:func:`~pandas.read_sql_table` and :func:`~pandas.read_sql_query` (and for
3129+
backward compatibility) and will delegate to specific function depending on
3130+
the provided input (database table name or sql query).
3131+
31213132
In the following example, we use the `SQlite <http://www.sqlite.org/>`__ SQL database
31223133
engine. You can use a temporary SQLite database where data are stored in
31233134
"memory".
@@ -3129,7 +3140,7 @@ connecting to.
31293140
For more information on :func:`create_engine` and the URI formatting, see the examples
31303141
below and the SQLAlchemy `documentation <http://docs.sqlalchemy.org/en/rel_0_9/core/engines.html>`__
31313142

3132-
.. code-block:: python
3143+
.. ipython:: python
31333144
31343145
from sqlalchemy import create_engine
31353146
from pandas.io import sql
@@ -3140,8 +3151,7 @@ Writing DataFrames
31403151
~~~~~~~~~~~~~~~~~~
31413152

31423153
Assuming the following data is in a DataFrame ``data``, we can insert it into
3143-
the database using :func:`~pandas.io.sql.to_sql`.
3144-
3154+
the database using :func:`~pandas.DataFrame.to_sql`.
31453155

31463156
+-----+------------+-------+-------+-------+
31473157
| id | Date | Col_1 | Col_2 | Col_3 |
@@ -3154,13 +3164,6 @@ the database using :func:`~pandas.io.sql.to_sql`.
31543164
+-----+------------+-------+-------+-------+
31553165

31563166

3157-
.. ipython:: python
3158-
:suppress:
3159-
3160-
from sqlalchemy import create_engine
3161-
from pandas.io import sql
3162-
engine = create_engine('sqlite:///:memory:')
3163-
31643167
.. ipython:: python
31653168
:suppress:
31663169
@@ -3171,44 +3174,47 @@ the database using :func:`~pandas.io.sql.to_sql`.
31713174
(63, datetime.datetime(2010,10,20), 'Z', 5.73, True)]
31723175
31733176
data = DataFrame(d, columns=c)
3174-
sql.to_sql(data, 'data', engine)
3177+
3178+
.. ipython:: python
3179+
3180+
data.to_sql('data', engine)
31753181
31763182
Reading Tables
31773183
~~~~~~~~~~~~~~
31783184

3179-
:func:`~pandas.io.sql.read_table` will read a databse table given the
3185+
:func:`~pandas.read_sql_table` will read a database table given the
31803186
table name and optionally a subset of columns to read.
31813187

31823188
.. note::
31833189

3184-
In order to use :func:`~pandas.io.sql.read_table`, you **must** have the
3190+
In order to use :func:`~pandas.read_sql_table`, you **must** have the
31853191
SQLAlchemy optional dependency installed.
31863192

31873193
.. ipython:: python
31883194
3189-
sql.read_table('data', engine)
3195+
pd.read_sql_table('data', engine)
31903196
31913197
You can also specify the name of the column as the DataFrame index,
31923198
and specify a subset of columns to be read.
31933199

31943200
.. ipython:: python
31953201
3196-
sql.read_table('data', engine, index_col='id')
3197-
sql.read_table('data', engine, columns=['Col_1', 'Col_2'])
3202+
pd.read_sql_table('data', engine, index_col='id')
3203+
pd.read_sql_table('data', engine, columns=['Col_1', 'Col_2'])
31983204
31993205
And you can explicitly force columns to be parsed as dates:
32003206

32013207
.. ipython:: python
32023208
3203-
sql.read_table('data', engine, parse_dates=['Date'])
3209+
pd.read_sql_table('data', engine, parse_dates=['Date'])
32043210
32053211
If needed you can explicitly specifiy a format string, or a dict of arguments
3206-
to pass to :func:`pandas.tseries.tools.to_datetime`.
3212+
to pass to :func:`pandas.to_datetime`:
32073213

32083214
.. code-block:: python
32093215
3210-
sql.read_table('data', engine, parse_dates={'Date': '%Y-%m-%d'})
3211-
sql.read_table('data', engine, parse_dates={'Date': {'format': '%Y-%m-%d %H:%M:%S'}})
3216+
pd.read_sql_table('data', engine, parse_dates={'Date': '%Y-%m-%d'})
3217+
pd.read_sql_table('data', engine, parse_dates={'Date': {'format': '%Y-%m-%d %H:%M:%S'}})
32123218
32133219
32143220
You can check if a table exists using :func:`~pandas.io.sql.has_table`
@@ -3219,20 +3225,20 @@ instantiated directly for more manual control over the SQL interaction.
32193225
Querying
32203226
~~~~~~~~
32213227

3222-
You can query using raw SQL in the :func:`~pandas.io.sql.read_sql` function.
3228+
You can query using raw SQL in the :func:`~pandas.read_sql_query` function.
32233229
In this case you must use the SQL variant appropriate for your database.
32243230
When using SQLAlchemy, you can also pass SQLAlchemy Expression language constructs,
32253231
which are database-agnostic.
32263232

32273233
.. ipython:: python
32283234
3229-
sql.read_sql('SELECT * FROM data', engine)
3235+
pd.read_sql_query('SELECT * FROM data', engine)
32303236
32313237
Of course, you can specify a more "complex" query.
32323238

32333239
.. ipython:: python
32343240
3235-
sql.read_frame("SELECT id, Col_1, Col_2 FROM data WHERE id = 42;", engine)
3241+
pd.read_sql_query("SELECT id, Col_1, Col_2 FROM data WHERE id = 42;", engine)
32363242
32373243
32383244
You can also run a plain query without creating a dataframe with
@@ -3290,7 +3296,7 @@ you are using.
32903296

32913297
.. code-block:: python
32923298
3293-
sql.to_sql(data, 'data', cnx, flavor='sqlite')
3299+
data.to_sql('data', cnx, flavor='sqlite')
32943300
32953301
sql.read_sql("SELECT * FROM data", cnx, flavor='sqlite')
32963302

pandas/io/api.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88
from pandas.io.pytables import HDFStore, Term, get_store, read_hdf
99
from pandas.io.json import read_json
1010
from pandas.io.html import read_html
11-
from pandas.io.sql import read_sql
11+
from pandas.io.sql import read_sql, read_sql_table, read_sql_query
1212
from pandas.io.stata import read_stata
1313
from pandas.io.pickle import read_pickle, to_pickle
1414
from pandas.io.packers import read_msgpack, to_msgpack

0 commit comments

Comments
 (0)