Civis

Overview

The Civis Platform is a cloud-based data science platform. This Parsons connector utilizes the Civis API Python client to interact with the Civis Platform. It supports executing Civis SQL queries and writing Parsons Tables to a Civis Redshift cluster.

Authentication

The CivisClient class requires your Redshift database ID or name, and an API Key. To obtain an API Key, log in to Civis and follow the instructions for Creating an API Key.

Quickstart

To instantiate the CivisClient class, you can either store your database identifier and API Key as environmental variables (CIVIS_DATABASE and CIVIS_API_KEY) or pass them as keyword arguments.

Authorize with environmental variables
from parsons import CivisClient
civis = CivisClient()
Pass API credentials as arguments
from parsons import CivisClient
civis = CivisClient(db='my_db_name', api_key='my_api_key')
Execute a Civis query
civis.query(sql="SELECT * FROM my_table")

API

class parsons.civis.civisclient.CivisClient(db=None, api_key=None, **kwargs)[source]

Instantiate the Civis class.

Parameters:

  • db – str or int The Civis Redshift database. Can be a database id or the name of the database.

  • api_key – str The Civis api key.

  • **kwargs – args Option settings for the client that are described in the documentation.

Returns:

Civis class

client

The Civis API client. Utilize this attribute to access to lower level and more advanced methods which might not be surfaced in Parsons. A list of the methods can be found by reading the Civis API client documentation.

query(sql, preview_rows=10, polling_interval=None, hidden=True, wait=True)[source]

Execute a SQL statement as a Civis query.

Run a query that may return no results or where only a small preview is required. To execute a query that returns a large number of rows, see read_civis_sql().

Parameters:

  • sql – str The SQL statement to execute.

  • preview_rows – int, optional The maximum number of rows to return. No more than 100 rows can be returned at once.

  • polling_interval – int or float, optional Number of seconds to wait between checks for query completion.

  • hidden – bool, optional If True (the default), this job will not appear in the Civis UI.

  • wait – boolean If True, will wait for query to finish executing before exiting the method. If False, returns the future object.

Returns:

Table or civis.futures.CivisFuture

See Table for output options.

table_import(table_obj, table, max_errors=None, existing_table_rows: Literal['fail', 'truncate', 'append', 'drop'] = 'fail', diststyle: Literal['even', 'all', 'key'] | None = None, distkey=None, sortkey1=None, sortkey2=None, wait=True, **civisargs)[source]

Write the table to a Civis Redshift cluster.

Additional keyword arguments can passed to civis.io.dataframe_to_civis().

Parameters:

  • table_obj – obj A Parsons Table object

  • table – str The schema and table you want to upload to. E.g., ‘scratch.table’. Schemas or tablenames with periods must be double quoted, e.g. ‘scratch.”my.table”’.

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

  • max_errors – int The maximum number of rows with errors to remove from the import before failing.

  • existing_table_rows (Literal['fail', 'truncate', 'append', 'drop']) – str The behaviour if a table with the requested name already exists. One of ‘fail’, ‘truncate’, ‘append’ or ‘drop’. Defaults to ‘fail’.

  • diststyle (Literal['even', 'all', 'key'] | None) – str The distribution style for the table. One of ‘even’, ‘all’ or ‘key’.

  • distkey – str The column to use as the distkey for the table.

  • sortkey1 – str The column to use as the sortkey for the table.

  • sortkey2 – str The second column in a compound sortkey for the table.

  • wait – boolean Wait for write job to complete before exiting method. If False, returns the future object.

Returns:

None or civis.futures.CivisFuture