What are Civis Files?

While tabular data on Civis Platform (with the associated concepts of databases, schemas, and tablenames) is a popular form of data for most users, it is also possible to handle non-tabular data on Civis Platform. Depending on your use case, such data can be any arbitrary files (e.g., PDFs, documents and spreadsheets from word-processing software, images, videos, any unstructured plain text files, etc).

You can create, store, and access arbitrary files on Civis Platform as Civis files. Under the hood, a Civis file is an AWS S3 file object managed by Civis Platform. This means that Civis files have the same permission features as other Civis Platform objects for access and sharing with other Platform users. Therefore, you won’t need to worry about authentication with any actual AWS credentials for your Civis files.

Creating and Accessing Civis Files

Parameterized Civis Platform scripts have the parameter type “File” that can upload a file from your local drive to Civis Platform. Moreover, the Civis API (https://api.civisanalytics.com/) has the Files endpoint to work with Civis files. To facilitate programmatic interactions with Civis files, the Civis API clients have convenience functions defined:

Python

civis.io.file_to_civis uploads an arbitrary file to Civis Platform, whereas civis.io.civis_to_file accesses a Civis file. Various other functions have also been defined to work with Civis files (e.g., between Platform tables and Civis files) – please see the Data Import and Export section of the Python API client documentation.

R

write_civis_file uploads an arbitrary file to Civis Platform, whereas read_civis accesses such a file back from Platform.

Tips and Best Practices

• By default, a Civis file expires after 30 days from creation. The expiry date can be set at the time of file creation or modified afterwards through the Civis API. Please see also S3 File Retention.
• Each Civis file is associated with a file ID, which you will need to keep track of so that the file can be accessed later on. A common strategy is to put Civis files in a Project on Civis Platform, so that your Civis files are both more organized and searchable.