import civis
from parsons.etl.table import Table
from parsons.utilities import check_env
[docs]class CivisClient(object):
"""
Instantiate the Civis class.
`Args:`
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 <https://civis-python.readthedocs.io/en/stable/client.html#civis.APIClient>`_.
`Returns:`
Civis class
""" # noqa: E501
def __init__(self, db=None, api_key=None, **kwargs):
self.db = check_env.check('CIVIS_DATABASE', db)
self.api_key = check_env.check('CIVIS_API_KEY', api_key)
self.client = civis.APIClient(api_key=api_key, **kwargs)
"""
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 <https://civis-python.readthedocs.io/en/stable/client.html>`_.
""" # noqa: E501
[docs] def query(self, sql, preview_rows=10, polling_interval=None, hidden=True, wait=True):
"""
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 :func:`~civis.io.read_civis_sql`.
`Args`
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`
Parsons Table or ``civis.CivisFuture``
See :ref:`parsons-table` for output options.
"""
fut = civis.io.query_civis(sql, self.db, preview_rows=preview_rows,
polling_interval=polling_interval, hidden=hidden)
if not wait:
return fut
result = fut.result()
if result['result_rows'] is None:
return None
result['result_rows'].insert(0, result['result_columns'])
return Table(result['result_rows'])
[docs] def table_import(self, table_obj, table, max_errors=None,
existing_table_rows='fail', diststyle=None, distkey=None,
sortkey1=None, sortkey2=None, wait=True, **civisargs):
"""
Write the table to a Civis Redshift cluster. Additional key word
arguments can passed to `civis.io.dataframe_to_civis() <https://civis-python.readthedocs.io/en/v1.9.0/generated/civis.io.dataframe_to_civis.html#civis.io.dataframe_to_civis>`_ # noqa: E501
`Args`
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: str
The behaviour if a table with the requested name already exists. One of
`'fail'`, `'truncate'`, `'append'` or `'drop'`. Defaults to `'fail'`.
diststyle: 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.CivisFuture``
""" # noqa: E501,E261
fut = civis.io.dataframe_to_civis(table_obj.to_dataframe(), database=self.db,
table=table, max_errors=max_errors,
existing_table_rows=existing_table_rows,
diststyle=diststyle, distkey=distkey,
sortkey1=sortkey1, sortkey2=sortkey2,
headers=True, **civisargs)
if wait:
return fut.result()
return fut