Python Client
GeoDBClient
- class xcube_geodb.core.geodb.GeoDBClient(server_url: Optional[str] = None, server_port: Optional[int] = None, client_id: Optional[str] = None, client_secret: Optional[str] = None, username: Optional[str] = None, password: Optional[str] = None, access_token: Optional[str] = None, dotenv_file: str = '.env', auth_mode: Optional[str] = None, auth_aud: Optional[str] = None, config_file: str = '/home/docs/.geodb', database: Optional[str] = None, access_token_uri: Optional[str] = None, gs_server_url: Optional[str] = None, gs_server_port: Optional[int] = None, raise_it: bool = True)
Constructing the geoDB client. Dpending on the setup it will automatically setup credentials from environment variables. The user can also pass credentials into the constructor.
- Parameters
server_url (str) – The URL of the PostGrest Rest API service
server_port (str) – The port to the PostGrest Rest API service
dotenv_file (str) – Name of the dotenv file [.env] to set client IDs and secrets
client_secret (str) – Client secret (overrides environment variables)
client_id (str) – Client ID (overrides environment variables)
auth_mode (str) – Authentication mode [silent]. Can be thw oauth2 modes ‘client-credentials’, ‘password’, ‘interactive’ and ‘none’ for no authentication
auth_aud (str) – Authentication audience
config_file (str) – Filename that stores config info for the geodb client
- Raises
GeoDBError – if the auth mode does not exist
NotImplementedError – on auth mode interactive
Examples
>>> geodb = GeoDBClient(auth_mode='client-credentials', client_id='***', client_secret='***') >>> geodb.whoami my_user
- get_collection_info(collection: str, database: Optional[str] = None) → Dict
- Parameters
collection (str) – The name of the collection to inspect
database (str) – The database the database resides in [current database]
- Returns
A dictionary with collection information
- Raises
GeoDBError – When the collection does not exist
Examples
>>> geodb = GeoDBClient(auth_mode='client-credentials', client_id='***', client_secret='***') >>> geodb.get_collection_info('my_collection') { 'required': ['id', 'geometry'], 'properties': { 'id': { 'format': 'integer', 'type': 'integer', 'description': 'Note:This is a Primary Key.' }, 'created_at': {'format': 'timestamp with time zone', 'type': 'string'}, 'modified_at': {'format': 'timestamp with time zone', 'type': 'string'}, 'geometry': {'format': 'public.geometry(Geometry,3794)', 'type': 'string'}, 'my_property1': {'format': 'double precision', 'type': 'number'}, 'my_property2': {'format': 'double precision', 'type': 'number'}, 'type': 'object' }
- get_my_collections(database: Optional[str] = None) → Sequence
- Parameters
database (str) – The database to list collections from
- Returns
A Dataframe of collection names
Examples
>>> geodb = GeoDBClient(auth_mode='client-credentials', client_id='***', client_secret='***') >>> geodb.get_my_collections() owner database collection 0 geodb_9bfgsdfg-453f-445b-a459 geodb_9bfgsdfg-453f-445b-a459 land_use
- property raise_it: bool
Returns: The current error message behaviour
- property database: str
Returns: The current database
- property whoami: str
Returns: The current database user
- property capabilities: Dict
Returns: A dictionary of the geoDB PostGrest REST API service’s capabilities
- refresh_config_from_env(dotenv_file: str = '.env', use_dotenv: bool = False)
Refresh the configuration from environment variables. The variables can be preset by a dotenv file. :param dotenv_file: A dotenv config file :type dotenv_file: str :param use_dotenv: Whether to use GEODB_AUTH_CLIENT_ID a dotenv file. :type use_dotenv: bool
- get_my_usage(pretty=True) → Union[Dict, xcube_geodb.core.message.Message]
Get my geoDB data usage.
- Parameters
pretty (bool) – Whether to return in human readable form or in bytes
- Returns
A dict containing the usage in bytes (int) or as a human readable string
Example
>>> geodb = GeoDBClient() >>> geodb.get_my_usage(True) {'usage': '6432 kB'}
- create_collection_if_not_exists(collection: str, properties: Dict, crs: Union[int, str] = 4326, database: Optional[str] = None, **kwargs) → Union[Dict, xcube_geodb.core.message.Message]
Creates a collection only if the collection does not exist already.
- Parameters
collection (str) – The name of the collection to be created
properties (Dict) – Properties to be added to the collection
crs (int, str) – projection
database (str) – The database the collection is to be created in [current database]
kwargs – Placeholder for deprecated parameters
- Returns
Collection info id operation succeeds None: If operation fails
- Return type
Collection
Examples
See create_collection for an example
- create_collections_if_not_exist(collections: Dict, database: Optional[str] = None, **kwargs) → Dict
Creates collections only if collections do not exist already.
- Parameters
collections (Dict) – The name of the collection to be created
database (str) – The database the collection is to be created in [current database]
kwargs – Placeholder for deprecated parameters
- Returns
List of informations about created collections
- Return type
List of Collections
Examples
See create_collections for examples
- create_collections(collections: Dict, database: Optional[str] = None, clear: bool = False) → Union[Dict, xcube_geodb.core.message.Message]
Create collections from a dictionary :param clear: Delete collections prioer to creation :type clear: bool :param collections: A dictionalry of collections :type collections: Dict :param database: Database to use for creating the collection :type database: str
- Returns
Success
- Return type
bool
Examples
>>> geodb = GeoDBClient() >>> collections = {'[MyCollection]': {'crs': 1234, 'properties': {'[MyProp1]': 'float', '[MyProp2]': 'date'}}} >>> geodb.create_collections(collections)
- create_collection(collection: str, properties: Dict, crs: Union[int, str] = 4326, database: Optional[str] = None, clear: bool = False) → Dict
Create collections from a dictionary
- Parameters
collection (str) – Name of the collection to be created
clear (bool) – Whether to delete existing collections
properties (Dict) – Property definitions for the collection
database (str) – Database to use for creating the collection
crs – sfdv
- Returns
Success
- Return type
bool
Examples
>>> geodb = GeoDBClient() >>> properties = {'[MyProp1]': 'float', '[MyProp2]': 'date'} >>> geodb.create_collection(collection='[MyCollection]', crs=3794, properties=properties)
- drop_collection(collection: str, database: Optional[str] = None) → xcube_geodb.core.message.Message
- Parameters
collection (str) – Name of the collection to be dropped
database (str) – The database the colections resides in [current database]
- Returns
Success
- Return type
bool
Examples
>>> geodb = GeoDBClient() >>> geodb.drop_collection(collection='[MyCollection]')
- drop_collections(collections: Sequence[str], cascade: bool = False, database: Optional[str] = None) → xcube_geodb.core.message.Message
- Parameters
database (str) – The database the colections resides in [current database]
collections (Sequence[str]) – Collections to be dropped
cascade (bool) – Drop in cascade mode. This can be necessary if e.g. sequences have not been deleted properly
- Returns
Message
Examples
>>> geodb = GeoDBClient() >>> geodb.drop_collections(collections=['[MyCollection1]', '[MyCollection2]'])
- grant_access_to_collection(collection: str, usr: str, database: Optional[str] = None) → xcube_geodb.core.message.Message
- Parameters
collection (str) – Collection name to grant access to
usr (str) – Username to grant access to
database (str) – The database the collection resides in
- Returns
Success
- Return type
bool
- Raises
HttpError – when http request fails
Examples
>>> geodb = GeoDBClient() >>> geodb.grant_access_to_collection('[Collection]', '[User who gets access]') Access granted on Collection to User who gets access}
- rename_collection(collection: str, new_name: str, database: Optional[str] = None)
- Parameters
collection (str) – The name of the collection to be renamed
new_name (str) – The new name of the collection
database (str) – The database the collection resides in
- Raises
HttpError – When request fails
- move_collection(collection: str, new_database: str, database: Optional[str] = None)
Move a collection from one database to another
- Parameters
collection (str) – The name of the collection to be renamed
new_database (str) – The database the collection will be moved to
database (str) – The database the collection resides in
Examples
>>> geodb = GeoDBClient() >>> geodb.move_collection('[Collection]', '[New Database]')
- copy_collection(collection: str, new_collection: str, new_database: str, database: Optional[str] = None)
- Parameters
collection (str) – The name of the collection to be copied
new_collection (str) – The new name of the collection
database (str) – The database the collection resides in [current database]
new_database (str) – The database the collection will be copied to
Examples
>>> geodb = GeoDBClient() >>> geodb.copy_collection('[Collection]', '[New Collection]')
- publish_collection(collection: str, database: Optional[str] = None) → xcube_geodb.core.message.Message
Publish a collection. The collection will bew accessible by all users in the geoDB. :param database: The database the collection resides in [current database] :type database: str :param collection: The name of the collection that will be made public :type collection: str
- Returns
Message whether operation succeeded
- Return type
Message
Examples
>>> geodb = GeoDBClient() >>> geodb.publish_collection('[Collection]')
- unpublish_collection(collection: str, database: Optional[str] = None) → xcube_geodb.core.message.Message
Revoke public access to a collection. The collection will nor be accessible by all users in the geoDB. :param database: The database the collection resides in [current database] :type database: str :param collection: The name of the collection that will be removed from public access :type collection: str
- Returns
Message whether operation succeeded
- Return type
Message
Examples
>>> geodb = GeoDBClient() >>> geodb.unpublish_collection('[Collection]')
- revoke_access_from_collection(collection: str, usr: str, database: Optional[str] = None, **kwargs) → xcube_geodb.core.message.Message
Revoke access from a collection :param collection: Name of the collection :type collection: str :param usr: User to revoke access from :type usr: str :param database: The database the collection resides in [current database] :type database: str
- Returns
Whether operation has succeeded
- Return type
Message
- list_my_grants() → Union[pandas.DataFrame, xcube_geodb.core.message.Message]
List the access grants the current user has granted
- Returns
A list of the current user’s access grants
- Return type
DataFrame
- Raises
GeoDBError – If access to geoDB fails
- add_property(collection: str, prop: str, typ: str, database: Optional[str] = None) → xcube_geodb.core.message.Message
Add a property to an existing collection
- Parameters
collection (str) – The name of the collection to add a property to
prop (str) – Property name
typ (str) – The data type of the property (Postgres type)
database (str) – The database the collection resides in [current database]
- Returns
Success Message
- Return type
Message
Examples
>>> geodb = GeoDBClient() >>> geodb.add_property(collection='[MyCollection]', name='[MyProperty]', type='[PostgresType]')
- add_properties(collection: str, properties: Dict, database: Optional[str] = None, **kwargs) → xcube_geodb.core.message.Message
Add properties to a collection
- Parameters
collection (str) – The name of the collection to add properties to
properties (Dict) – Property definitions as dictionary
database (str) – The database the collection resides in [current database]
- Returns
Whether the operation succeeded
- Return type
Message
Examples
>>> properties = {'[MyName1]': '[PostgresType1]', '[MyName2]': '[PostgresType2]'} >>> geodb = GeoDBClient() >>> geodb.add_property(collection='[MyCollection]', properties=properties)
- drop_property(collection: str, prop: str, database: Optional[str] = None, **kwargs) → xcube_geodb.core.message.Message
Drop a property from a collection :param collection: The name of the collection to drop the property from :type collection: str :param prop: The property to delete :type prop: str :param database: The database the collection resides in [current database] :type database: str
- Returns
Whether the operation succeeded
- Return type
Message
Examples
>>> geodb = GeoDBClient() >>> geodb.drop_property(collection='[MyCollection]', prop='[MyProperty]')
- drop_properties(collection: str, properties: Sequence[str], database: Optional[str] = None, **kwargs) → xcube_geodb.core.message.Message
Drop poperties from a collection :param collection: The name of the collection to delete properties from :type collection: str :param properties: A dictionary containing the property definitions :type properties: Dict :param database: The database the collection resides in [current database] :type database: str
- Returns
Whether the operation succeeded
- Return type
Message
Examples
>>> geodb = GeoDBClient() >>> geodb.drop_properties(collection='[MyCollection]', properties=['[MyProperty1]', '[MyProperty2]'])
- get_properties(collection: str, database: Optional[str] = None, **kwargs) → pandas.DataFrame
Get a list of properties of a collection
- Parameters
collection (str) – The name of the collection to retrieve a list of properties from
database (str) – The database the collection resides in [current database]
- Returns
A list of properties
- Return type
DataFrame
- create_database(database: str) → xcube_geodb.core.message.Message
Create a database
- Parameters
database (str) – The name of the database to be created
- Returns
A message about the success or failure of the operation
- Return type
Message
- truncate_database(database: str) → xcube_geodb.core.message.Message
Delete all tables in the given database
- Parameters
database (str) – The name of the database to be created
- Returns
A message about the success or failure of the operation
- Return type
Message
- get_my_databases() → pandas.DataFrame
Get a list of databases the current user owns
- Returns
A list of databases the user owns
- Return type
DataFrame
- database_exists(database: str) → bool
Checks whether a database exists
- Parameters
database (str) – The name of the database to be checked
- Returns
database exists
- Return type
bool
- Raises
HttpError – If request fails
- delete_from_collection(collection: str, query: str, database: Optional[str] = None) → xcube_geodb.core.message.Message
Delete :param collection: The name of the collection to delete rows from :type collection: str :param database: The name of the database to be checked :type database: str :param query: Filter which records to delete. Follow the http://postgrest.org/en/v6.0/api.html query :type query: str :param convention.:
- Returns
Whether the operation has succeeded
- Return type
Message
Examples
>>> geodb = GeoDBClient() >>> geodb.delete_from_collection('[MyCollection]', 'id=eq.1')
- update_collection(collection: str, values: Dict, query: str, database: Optional[str] = None, **kwargs) → xcube_geodb.core.message.Message
Update data in a collection by a query
- Parameters
collection (str) – The name of the collection to be updated
database (str) – The name of the database to be checked
values (Dict) – Values to update
query (str) – Filter which values to be updated. Follow the http://postgrest.org/en/v6.0/api.html query
convention. –
- Returns
Success
- Return type
Message
- Raises
GeoDBError – if the values is not a Dict or request fails
Example:
- insert_into_collection(collection: str, values: geopandas.GeoDataFrame, upsert: bool = False, crs: Optional[Union[int, str]] = None, database: Optional[str] = None, max_transfer_chunk_size: int = 1000) → xcube_geodb.core.message.Message
Insert data into a collection
- Parameters
collection (str) – Collection to be inserted to
database (str) – The name of the database the collection resides in [current database]
values (GeoDataFrame) – Values to be inserted
upsert (bool) – Whether the insert shall replace existing rows (by PK)
crs (int, str) – crs (in the form of an SRID) of the geometries. If not present, the method will attempt
it from the GeoDataFrame input. Must be in sync with the target collection in the GeoDatabase (guessing) –
max_transfer_chunk_size (int) – Maximum number of rows per chunk to be sent to the geodb.
- Raises
ValueError – When crs is not given and cannot be guessed from the GeoDataFrame
GeoDBError – If the values are not in format Dict
- Returns
Success
- Return type
bool
Example:
- static transform_bbox_crs(bbox: Tuple[float, float, float, float], from_crs: Union[int, str], to_crs: Union[int, str], wsg84_order: str = 'lat_lon')
This function can be used to reproject bboxes particularly with the use of GeoDBClient.get_collection_by_bbox.
- Parameters
bbox – Tuple[float, float, float, float]: bbox to be reprojected
from_crs – Source crs e.g. 3974
to_crs – Target crs e.g. 4326
wsg84_order (str) – WSG84 (EPSG:4326) is expected to be in Lat Lon format (“lat_lon”). Use “lon_lat” if Lon Lat is used.
- Returns
The reprojected bounding box
- Return type
Tuple[float, float, float, float]
Examples
>>> bbox = GeoDBClient.transform_bbox_crs(bbox=(450000, 100000, 470000, 110000), from_crs=3794, to_crs=4326) >>> bbox (49.36588643725233, 46.012889756941775, 14.311548793848758, 9.834303086688251)
- get_collection_by_bbox(collection: str, bbox: Tuple[float, float, float, float], comparison_mode: str = 'contains', bbox_crs: Union[int, str] = 4326, limit: int = 0, offset: int = 0, where: Optional[str] = 'id>-1', op: str = 'AND', database: Optional[str] = None, wsg84_order='lat_lon', **kwargs) → Union[geopandas.GeoDataFrame, pandas.DataFrame]
Query the database by a bounding box. Please be careful with the bbox crs. The easiest is using the same crs as the collection. However, if the bbox crs differs from the collection, the geoDB client will attempt to automatially transform the bbox crs according to the collection’s crs. You can also directly use the method GeoDBClient.transform_bbox_crs yourself before you pass the bbox into this method.
- Parameters
collection (str) – The name of the collection to be quried
bbox (Tuple[float, float, float, float]) – minx, miny, maxx, maxy
comparison_mode (str) – Filter mode. Can be ‘contains’ or ‘within’ [‘contains’]
bbox_crs (int, str) – Projection code. [4326]
op (str) – Operator for where (AND, OR) [‘AND’]
where (str) – Additional SQL where statement to further filter the collection
limit (int) – The maximum number of rows to be returned
offset (int) – Offset (start) of rows to return. Used in combination with limit.
database (str) – The name of the database the collection resides in [current database]
wsg84_order (str) – WSG84 (EPSG:4326) is expected to be in Lat Lon format (“lat_lon”). Use “lon_lat” if
Lat is used. (Lon) –
- Returns
A GeoPandas Dataframe
- Raises
HttpError – When the database raises an error
Examples
>>> geodb = GeoDBClient() >>> geodb.get_collection_by_bbox(table="[MyCollection]", bbox=(452750.0, 88909.549, 464000.0, 102486.299), comparison_mode="contains", bbox_crs=3794, limit=10, offset=10)
- head_collection(collection: str, num_lines: int = 10, database: Optional[str] = None) → Union[geopandas.GeoDataFrame, pandas.DataFrame]
Get the first num_lines of a collection
- Parameters
collection (str) – The collection’s name
num_lines (int) – The number of line to return
database (str) – The name of the database the collection resides in [current database]
- Returns
results
- Return type
GeoDataFrame or DataFrame
- Raises
HttpError – When the database raises an error
Examples
>>> geodb = GeoDBClient() >>> geodb.head_collection(collection='[MyCollection]', num_lines=10)
- get_collection(collection: str, query: Optional[str] = None, database: Optional[str] = None, limit: Optional[int] = None, offset: Optional[int] = None) → Union[geopandas.GeoDataFrame, pandas.DataFrame]
Query a collection
- Parameters
collection (str) – The collection’s name
query (str) – A query. Follow the http://postgrest.org/en/v6.0/api.html query convention.
database (str) – The name of the database the collection resides in [current database]
- Returns
results
- Return type
GeoDataFrame or DataFrame
- Raises
HttpError – When the database raises an error
Examples
>>> geodb = GeoDBClient() >>> geodb.get_collection(collection='[MyCollection]', query='id=ge.1000')
- get_collection_pg(collection: str, select: str = '*', where: Optional[str] = None, group: Optional[str] = None, order: Optional[str] = None, limit: Optional[int] = None, offset: Optional[int] = None, database: Optional[str] = None) → Union[geopandas.GeoDataFrame, pandas.DataFrame]
- Parameters
collection (str) – The name of the collection to query
select (str) – Properties (columns) to return. Can contain aggregation functions
where (Optional[str]) – SQL WHERE statement
group (Optional[str]) – SQL GROUP statement
order (Optional[str]) – SQL ORDER statement
limit (Optional[int]) – Limit for paging
offset (Optional[int]) – Offset (start) of rows to return. Used in combination with limit.
database (str) – The name of the database the collection resides in [current database]
- Returns
results
- Return type
GeoDataFrame or DataFrame
- Raises
HttpError – When the database raises an error
Examples
>>> geodb = GeoDBClient() >>> df = geodb.get_collection_pg(collection='[MyCollection]', where='raba_id=1410', group='d_od', select='COUNT(d_od) as ct, d_od')
- property server_url: str
Get URL of the geoDb server
- Returns
The URL of the GeoDB REST service
- Return type
str
- get_collection_srid(collection: str, database: Optional[str] = None) → Union[str, None, xcube_geodb.core.message.Message]
Get the SRID of a collection
- Parameters
collection (str) – The collection’s name
database (str) – The name of the database the collection resides in [current database]
- Returns
The name of the SRID
- publish_gs(collection: str, database: Optional[str] = None)
Publishes collection to a BC geoservice (geoserver instance). Requires access registration. :param collection: Name of the collection :type collection: str :param database: Name of the database. Defaults to user database :type database: Optional[str]
- Returns
Dict
- get_all_published_gs(database: Optional[str] = None) → Union[Sequence, xcube_geodb.core.message.Message]
- Parameters
database (str) – The database to list collections from a database which are published via geoserver
- Returns
A Dataframe of collection names
- get_published_gs(database: Optional[str] = None) → Union[Sequence, xcube_geodb.core.message.Message]
- Parameters
database (str) – The database to list collections from a database which are published via geoserver
- Returns
A Dataframe of collection names
Examples
>>> geodb = GeoDBClient(auth_mode='client-credentials', client_id='***', client_secret='***') >>> geodb.get_published_gs() owner database collection 0 geodb_9bfgsdfg-453f-445b-a459 geodb_9bfgsdfg-453f-445b-a459 land_use
- unpublish_gs(collection: str, database: str)
‘UnPublishes’ collection to a BC geoservice (geoserver instance). Requires access registration. :param collection: Name of the collection :type collection: str :param database: Name of the database. Defaults to user database :type database: Optional[str]
- Returns
Dict
- property auth_access_token: str
Get the user’s access token from
- Returns
The current authentication access_token
- Raises
GeoDBError on missing ipython shell –
- refresh_auth_access_token()
Refresh the authentication token
- collection_exists(collection: str, database: str) → bool
Checks whether a collection exists
- Parameters
collection (str) – The collection’s name
database (str) – The name of the database the collection resides in [current database]
- Returns
Whether the collection exists
- static setup(host: Optional[str] = None, port: Optional[str] = None, user: Optional[str] = None, passwd: Optional[str] = None, dbname: Optional[str] = None, conn: Optional[any] = None)
Sets up the database. Needs DB credentials and the database user requires CREATE TABLE/FUNCTION grants.