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)[source]¶ 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)[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. 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)[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
-
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)[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
(name: str = None)[source]¶ 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)[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
- 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
-
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 toTrue
.
-
property
dialect
¶