Skip to content

Commit ac281d6

Browse files
Add docstring to the insertion method & fix #21364
Credit for empty result documentation goes to @MagnetarAlex
1 parent cf25c5c commit ac281d6

File tree

1 file changed

+22
-0
lines changed

1 file changed

+22
-0
lines changed

doc/source/user_guide/io.rst

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5012,6 +5012,18 @@ Example of a callable using PostgreSQL `COPY clause
50125012
from io import StringIO
50135013

50145014
def psql_insert_copy(table, conn, keys, data_iter):
5015+
"""
5016+
Execute SQL statement inserting data
5017+
5018+
Parameters
5019+
----------
5020+
table : pandas.io.sql.SQLTable
5021+
conn : sqlalchemy.engine.Engine or sqlalchemy.engine.Connection
5022+
keys : list of str
5023+
Column names
5024+
data_iter : generator of list
5025+
Each item contains a list of values to be inserted
5026+
"""
50155027
# gets a DBAPI connection that can provide a cursor
50165028
dbapi_conn = conn.connection
50175029
with dbapi_conn.cursor() as cur:
@@ -5045,6 +5057,16 @@ table name and optionally a subset of columns to read.
50455057
50465058
pd.read_sql_table('data', engine)
50475059
5060+
Note that pandas infers column dtypes from query outputs, and not by looking
5061+
up data types in the physical database schema. For example, assume ``userid``
5062+
is an integer column in a table. Then, intuitively, ``select userid ...`` will
5063+
return integer-valued series, while ``select cast(userid as text) ...`` will
5064+
return object-valued (str) series. Accordingly, if the query output is empty,
5065+
then all resulting columns will be returned as object-valued (since they are
5066+
most general). If you foresee that your query will sometimes generate an empty
5067+
result, you may want to explicitly typecast afterwards to ensure dtype
5068+
integrity.
5069+
50485070
You can also specify the name of the column as the ``DataFrame`` index,
50495071
and specify a subset of columns to be read.
50505072

0 commit comments

Comments
 (0)