civis.io.civis_to_csv

civis.io.civis_to_csv(filename: str, sql: str, database: str | int, sql_params_arguments: dict | None = None, job_name: str | None = None, client: APIClient | None = None, credential_id: int | None = None, include_header: bool = True, compression: str = 'none', delimiter: str = ',', unquoted: bool = False, hidden: bool = True, polling_interval: int | float | None = None) → CivisFuture

Export data from Civis to a local CSV file.

Parameters:

filenamestr

Download exported data into this file.

sqlstr

The SQL select string to be executed.

databasestr or int

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

sql_params_argumentsdict, optional

A dictionary of SQL query parameters to pass directly to civis.APIClient.scripts.post_sql. The only allowed keys are "params" (whose value is a list[dict]) and "arguments" (whose value is a dict). Please refer to the linked API documentation for how to format these two keys’ values.

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 ID of the database credential. If None, the default credential will be used.

include_header: bool, optional

If True, the first line of the CSV will be headers. Default: True.

compression: str, optional

Type of compression to use, if any. One of 'none', 'zip', or 'gzip'. Default 'none'. 'gzip' currently returns a file with no compression unless include_header is set to False. In a future release, a 'gzip' compressed file will be returned for all cases.

delimiter: str, optional

Which delimiter to use, if any. One of ',', '     ', or '|'. Default: ','.

unquoted: bool, optional

Whether or not to quote fields. Default: False.

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.

Returns:

resultsCivisFuture

A CivisFuture object that represents the SQL query that unloads data from Civis Platform. Note that this unloading process has an arbitrary filename assigned and made available through the CivisFuture object, which is not the same as the filename parameter. It is recommended that a separate variable is used to store the desired filename beforehand so that it’s accessible after this function finishes, see the code example below.

See also

civis.io.read_civis

Read table contents into memory.

civis.io.read_civis_sql

Read results of a SQL query into memory.

civis.io.export_to_civis_file

Store a SQL query’s results in a Civis file

Examples

>>> import civis
>>> sql = "SELECT * FROM schema.table"
>>> file_path = "file.csv"
>>> fut = civis.io.civis_to_csv(file_path, sql, "my_database")
>>> fut.result()  # Wait for job to complete
>>> import pandas as pd  # Let's say we want to read the data into a DataFrame
>>> df = pd.read_csv(file_path)