civis.io.read_civis

civis.io.read_civis(table, database, columns=None, use_pandas=False, encoding=None, job_name=None, api_key=None, client=None, credential_id=None, polling_interval=None, archive=False, hidden=True, **kwargs)[source]

Read data from a Civis table.

Parameters
tablestr

Name of table, including schema, in the database. E.g. 'my_schema.my_table'. Schemas or tablenames with periods must be double quoted, e.g. 'my_schema."my.table"'.

databasestr or int

Read data from this database. Can be the database name or ID.

columnslist, optional

A list of column names. Column SQL transformations are possible. If omitted, all columns are exported.

use_pandasbool, optional

If True, return a pandas.DataFrame. Otherwise, return a list of results from csv.reader().

encodingstr, optional

If use_pandas is True, this parameter is passed to the encoding kwarg of pandas.read_csv(). If use_pandas is False, and if this parameter isn’t provided, then the UTF-8 encoding is assumed. In case you encounter a UnicodeDecodeError, consider choosing an encoding suitable for your data; see the list of standard encodings.

job_namestr, optional

A name to give the job. If omitted, a random job name will be used.

api_keyDEPRECATED str, optional

Your Civis API key. If not given, the CIVIS_API_KEY environment variable will be used.

clientcivis.APIClient, optional

If not provided, an civis.APIClient object will be created from the CIVIS_API_KEY.

credential_idstr or int, optional

The database credential ID. If None, the default credential will be used.

polling_intervalint or float, optional

Number of seconds to wait between checks for query completion.

archivebool, optional (deprecated)

If True, archive the import job as soon as it completes.

hiddenbool, optional

If True (the default), this job will not appear in the Civis UI.

**kwargskwargs

Extra keyword arguments are passed into pandas.read_csv() if use_pandas is True or passed into csv.reader() if use_pandas is False.

Returns
datapandas.DataFrame or list

A list of rows (with header as first row) if use_pandas is False, otherwise a pandas.DataFrame. Note that if use_pandas is False, no parsing of types is performed and each row will be a list of strings.

Raises
ImportError

If use_pandas is True and pandas is not installed.

EmptyResultError

If the table is empty.

See also

civis.io.read_civis_sql

Read directly into memory using SQL.

civis.io.civis_to_csv

Write directly to csv.

civis.io.export_to_civis_file

Store a SQL query’s results in a Civis file

Examples

>>> table = "schema.table"
>>> database = "my_data"
>>> columns = ["column_a", "ROW_NUMBER() OVER(ORDER BY date) AS order"]
>>> data = read_civis(table, database, columns=columns)
>>> columns = data.pop(0)
>>> col_a_index = columns.index("column_a")
>>> col_a = [row[col_a_index] for row in data]

>>> df = read_civis("schema.table", "my_data", use_pandas=True)
>>> col_a = df["column_a"]