, sql, database, job_name=None, api_key=None, client=None, credential_id=None, include_header=True, compression='none', delimiter=',', unquoted=False, archive=False, hidden=True, polling_interval=None)[source]

Export data from Civis to a local CSV file.

The custom SQL string will be executed twice; once to attempt to retrieve headers and once to retrieve the data. This is done to use a more performant method for retrieving the data. The first execution of the custom SQL is controlled such that changes in state cannot occur (e.g., INSERT, UPDATE, DELETE, etc.).


Download exported data into this file.


The SQL select string to be executed.

databasestr or int

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

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

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.


A CivisFuture object.

See also

Read table contents into memory.

Read results of a SQL query into memory.

Store a SQL query’s results in a Civis file


>>> sql = "SELECT * FROM schema.table"
>>> fut = civis_to_csv("file.csv", sql, "my_database")
>>> fut.result()  # Wait for job to complete