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, database=None, discover_client=None, storage_client=None, **grpc_client_kwargs)

Tables client for interacting with tabular data.

Parameters:

• host (str) – The backend host to connect to. Defaults to the correct value. Only override when debugging
• port (int) – The backend port to connect to. Defaults to the correct value. Only override when debugging.
• auth (Auth) – The authentication instance to use for the Tables client. Note that this does not apply to the default Discover and Storage clients. Defaults to Auth.get_default_auth().
• database – Backend database.
• discover_client – Discover client instance. Defaults to Discover.get_default_client()
• storage_client – Storage client instance Defaults to Storage.get_default_client()

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
get_default_client()	Retrieve the default client.
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
set_default_client(client)	Change the default client to the given client.
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

classmethod get_default_client()

Retrieve the default client.

This client is used whenever you don’t explicitly set the client.

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

classmethod set_default_client(client)

Change the default client to the given client.

This is the client that will be used whenever you don’t explicitly set the client

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'