civis.io.read_civis

civis.io.read_civis(table, database, columns=None, use_pandas=False, encoding=None, job_name=None, client=None, credential_id=None, polling_interval=None, 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.
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.
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

>>> import civis
>>> table = "schema.table"
>>> database = "my_data"
>>> columns = ["column_a", "ROW_NUMBER() OVER(ORDER BY date) AS order"]
>>> data = civis.io.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 = civis.io.read_civis("schema.table", "my_data", use_pandas=True)
>>> col_a = df["column_a"]