Tables

Warning

The Tables client is in an Alpha release. Descartes Labs reserves the right to modify this API without any guarantees about backwards compatibility.

Tables	Tables client for interacting with tabular data.
JobStatus	An enumeration.

---

class Tables(host=None, port=None, auth=None, discover_client=None, database=None, **grpc_client_kwargs)

Tables client for interacting with tabular data.

Parameters

• host (str) – Service hostname.

• port (int) – Service port.

• auth (Auth) – A custom user authentication (defaults to the user authenticated locally by token information on disk or by environment variables)

• database – Backend database

Methods:

check_status(jobid)	Returns the status of a job
create_table(table_name, schema, srid[, …])	Create a table
delete_rows(ids, table_name[, pk_order, owner])	Deletes rows from an existing table
delete_table(table_name)	Delete a table by name
insert_features(obj, table_name[, owner])	param object obj Python object representing GeoJSON-like features.
insert_rows(obj, table_name[, owner])	Add rows to an existing table
inspect_dataset(dataset)	Extract schema and crs from an existing local dataset
list_tables([name])	Return a list of tables
table(name[, owner])	Retrieve a table by name
upload_file(file_obj, table_name[, owner, …])	Upload an file to an existing table.
wait_until_completion(jobid[, …])	Returns the status of the job, blocking until the job is completed

Attributes:

dialect

check_status(jobid)

Returns the status of a job

Parameters

jobid (int) – Job identifier

Returns

Tuple; completed, message

Return type

(JobStatus, str)

create_table(table_name, schema, srid, primary_key=None)

Create a table

Parameters

• table_name (str) – name of table. Can only contain alphanumeric and “_” characters.

• schema (dict) – schema mapping

• srid (int) – spatial reference identifier

• primary_key (str|list) – column name(s) to use as primary key. If None, a default key is used.

Returns

table name

Return type

str

delete_rows(ids, table_name, pk_order=None, owner=None)

Deletes rows from an existing table

Parameters

• pd.Series (list,) – Iterable of ids to delete. These ids must match the primary key or keys of the table. Ids may be either elements by themselves or list/tuples of elements in the case of composite primary keys.

• table_name (str) – name of table

• owner (str) – table owner, defaults to the user’s email.

• pk_order (list) – Required when deleting rows from tables with composite primary keys. Specify the column order for each element in ids.

Returns

Job identifier

Return type

str

delete_table(table_name)

Delete a table by name

Parameters

table_name (str) – name of table to delete

insert_features(obj, table_name, owner=None)

Parameters

• obj (object) – Python object representing GeoJSON-like features. This can be an object with __geo_interface__ method (e.g. GeoDataFrame), a GeoJSON-like FeatureCollection mapping, or a single GeoJSON-like Feature mapping, or an iterable of GeoJSON-like Feature mappings

• table_name (str) – name of vector table

• owner (str) – table owner, defaults to the user’s email.

Returns

Job identifier

Return type

str

insert_rows(obj, table_name, owner=None)

Add rows to an existing table

Parameters

• obj (object) – Python object representing GeoJSON-like features. This can be an object with __geo_interface__ method (e.g. GeoDataFrame), a GeoJSON-like FeatureCollection mapping, or a single GeoJSON-like Feature mapping, or an iterable of GeoJSON-like Feature mappings

• table_name (str) – name of vector table

• owner (str) – table owner, defaults to the user’s email.

Returns

Job identifier

Return type

str

inspect_dataset(dataset)

Extract schema and crs from an existing local dataset

Parameters

dataset (str|dataframe) – tabular dataset, path to a file or a pandas geodataframe

Returns

Tuple; schema, srid

Return type

(mapping, int)

list_tables(name: str = None)

Return a list of tables

Parameters

name (str) – tables matching the search string will be included. Wildcards * and ? can be used to match any number of any character or a single character respectively.

Returns

list of tables owned by the authenticated user organized by schema

Return type

Dict(str, Dict(str, List(str)))

table(name, owner=None)

Retrieve a table by name

Parameters

• name (str) – name of table

• owner (str) – table owner, defaults to the user’s email.

Returns

table expression

Return type

ibis.expr.types.TableExpr

upload_file(file_obj, table_name, owner=None, file_ext=None)

Upload an file to an existing table.

Parameters

• file_obj (str|file-like) – File-like object or name of file which will be uploaded. If this is a file-like object it must use byte mode (for example, a file opened in binary mode such as with open(filename, 'rb')).

• table_name (str) – name of table

• owner (str) – table owner, defaults to the user’s email.

• file_ext (str) – file extension to use, including the leading ‘.’. Required for a file-like file_obj. Ignored if file_obj is a string.

Returns

Job identifier

Return type

str

wait_until_completion(jobid, raise_on_failure=True, poll_interval=5.0)

Returns the status of the job, blocking until the job is completed

Parameters

• jobid (int) – Job identifier

• raise_on_failure (bool) – Raise an exception if the service reports an asyncronous failure.

• poll_interval (float) – Pause between status checks, seconds

Returns

Tuple; completed, message

Return type

(JobStatus, str)

Raises

RuntimeError – In case the service reports an asynchronous failure

and the raise_on_failure is set to True.

property dialect

class JobStatus

An enumeration.

Attributes:

CANCELLED
FAILURE
PENDING
REGISTERED
RUNNING
SUCCESS

CANCELLED = 'CANCELLED'

FAILURE = 'FAILURE'

PENDING = 'PENDING'

REGISTERED = 'REGISTERED'

RUNNING = 'RUNNING'

SUCCESS = 'SUCCESS'