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='platform.descarteslabs.com', port=443, auth=None, discover_client=None, database=None, **grpc_client_kwargs)[source]¶

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`()	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)[source]¶

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)[source]¶

Create a table

Parameters

table_name (str) – name of table
schema (str) – 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)[source]¶

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)[source]¶

Delete a table by name

Parameters: table_name (str) – name of table to delete

insert_features(obj, table_name, owner=None)[source]¶

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)[source]¶

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)[source]¶

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()[source]¶

Return a list of tables

Returns: list of tables owned by the authenticated user organized by schema
Return type: Dict(str, Dict(str, List(str)))

table(name, owner=None)[source]¶

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)[source]¶

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)[source]¶

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[source]¶

An enumeration.

Attributes:

`CANCELLED`
`FAILURE`
`PENDING`
`REGISTERED`
`RUNNING`
`SUCCESS`

CANCELLED = 'CANCELLED'¶

FAILURE = 'FAILURE'¶

PENDING = 'PENDING'¶

REGISTERED = 'REGISTERED'¶

RUNNING = 'RUNNING'¶

SUCCESS = 'SUCCESS'¶