civis.io.read_civis

civis.io.read_civis(table, database, columns=None, use_pandas=False, 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:
table : str

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"'.

database : str or int

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

columns : list, optional

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

use_pandas : bool, optional

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

job_name : str, optional

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

api_key : DEPRECATED str, optional

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

client : civis.APIClient, optional

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

credential_id : str or int, optional

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

polling_interval : int or float, optional

Number of seconds to wait between checks for query completion.

archive : bool, optional (deprecated)

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

hidden : bool, optional

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

**kwargs : kwargs

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:
data : pandas.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.

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"]