@@ -3113,11 +3113,22 @@ DB-API <http://www.python.org/dev/peps/pep-0249/>`__.
3113
3113
See also some :ref: `cookbook examples <cookbook.sql >` for some advanced strategies.
3114
3114
3115
3115
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 `
3119
3116
3117
+ .. autosummary ::
3118
+ :toctree: generated/
3119
+
3120
+ read_sql_table
3121
+ read_sql_query
3122
+ read_sql
3123
+ DataFrame.to_sql
3120
3124
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
+
3121
3132
In the following example, we use the `SQlite <http://www.sqlite.org/ >`__ SQL database
3122
3133
engine. You can use a temporary SQLite database where data are stored in
3123
3134
"memory".
@@ -3129,7 +3140,7 @@ connecting to.
3129
3140
For more information on :func: `create_engine ` and the URI formatting, see the examples
3130
3141
below and the SQLAlchemy `documentation <http://docs.sqlalchemy.org/en/rel_0_9/core/engines.html >`__
3131
3142
3132
- .. code-block :: python
3143
+ .. ipython :: python
3133
3144
3134
3145
from sqlalchemy import create_engine
3135
3146
from pandas.io import sql
@@ -3140,8 +3151,7 @@ Writing DataFrames
3140
3151
~~~~~~~~~~~~~~~~~~
3141
3152
3142
3153
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 `.
3145
3155
3146
3156
+-----+------------+-------+-------+-------+
3147
3157
| id | Date | Col_1 | Col_2 | Col_3 |
@@ -3154,13 +3164,6 @@ the database using :func:`~pandas.io.sql.to_sql`.
3154
3164
+-----+------------+-------+-------+-------+
3155
3165
3156
3166
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
-
3164
3167
.. ipython :: python
3165
3168
:suppress:
3166
3169
@@ -3171,44 +3174,47 @@ the database using :func:`~pandas.io.sql.to_sql`.
3171
3174
(63 , datetime.datetime(2010 ,10 ,20 ), ' Z' , 5.73 , True )]
3172
3175
3173
3176
data = DataFrame(d, columns = c)
3174
- sql.to_sql(data, ' data' , engine)
3177
+
3178
+ .. ipython :: python
3179
+
3180
+ data.to_sql(' data' , engine)
3175
3181
3176
3182
Reading Tables
3177
3183
~~~~~~~~~~~~~~
3178
3184
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
3180
3186
table name and optionally a subset of columns to read.
3181
3187
3182
3188
.. note ::
3183
3189
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
3185
3191
SQLAlchemy optional dependency installed.
3186
3192
3187
3193
.. ipython :: python
3188
3194
3189
- sql.read_table (' data' , engine)
3195
+ pd.read_sql_table (' data' , engine)
3190
3196
3191
3197
You can also specify the name of the column as the DataFrame index,
3192
3198
and specify a subset of columns to be read.
3193
3199
3194
3200
.. ipython :: python
3195
3201
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' ])
3198
3204
3199
3205
And you can explicitly force columns to be parsed as dates:
3200
3206
3201
3207
.. ipython :: python
3202
3208
3203
- sql.read_table (' data' , engine, parse_dates = [' Date' ])
3209
+ pd.read_sql_table (' data' , engine, parse_dates = [' Date' ])
3204
3210
3205
3211
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 `:
3207
3213
3208
3214
.. code-block :: python
3209
3215
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' }})
3212
3218
3213
3219
3214
3220
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.
3219
3225
Querying
3220
3226
~~~~~~~~
3221
3227
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.
3223
3229
In this case you must use the SQL variant appropriate for your database.
3224
3230
When using SQLAlchemy, you can also pass SQLAlchemy Expression language constructs,
3225
3231
which are database-agnostic.
3226
3232
3227
3233
.. ipython :: python
3228
3234
3229
- sql.read_sql (' SELECT * FROM data' , engine)
3235
+ pd.read_sql_query (' SELECT * FROM data' , engine)
3230
3236
3231
3237
Of course, you can specify a more "complex" query.
3232
3238
3233
3239
.. ipython :: python
3234
3240
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)
3236
3242
3237
3243
3238
3244
You can also run a plain query without creating a dataframe with
@@ -3290,7 +3296,7 @@ you are using.
3290
3296
3291
3297
.. code-block :: python
3292
3298
3293
- sql .to_sql(data, ' data' , cnx, flavor = ' sqlite' )
3299
+ data .to_sql(' data' , cnx, flavor = ' sqlite' )
3294
3300
3295
3301
sql.read_sql(" SELECT * FROM data" , cnx, flavor = ' sqlite' )
3296
3302
0 commit comments