Query

The Query module provides functionality for working with queries.

class Query(api, uuid=None, data={})[source]

Bases: Base

Parameters:
BASE_ENDPOINT: str = 'queries/'
__init__(api, uuid=None, data={})[source]

Constructs all the necessary attributes for the Query object.

Parameters:

  • api (Api) – The API instance.

  • uuid (str) – The UUID of the query.

  • data (dict, optional) – The data of the query.

_check_access()[source]

Check if the query is a system query.

Returns:

None

Raises:

PermissionError – If the query is a read-only system query.

Return type:

None

property sql: str

Get the SQL of the query.

Returns:

The SQL of the query.

Return type:

str

Example

>>> from geobox import GeoboxClient
>>> from geobox.query import Query
>>> client = GeoboxClient()
>>> query = Query.get_query(client, uuid="12345678-1234-5678-1234-567812345678")
>>> query.sql
'SELECT * FROM some_layer'
property params: List[Dict]

Get the parameters of the query.

Returns:

The parameters of the query.

Return type:

List[Dict]

Example

>>> from geobox import GeoboxClient
>>> from geobox.query import Query
>>> client = GeoboxClient()
>>> query = Query.get_query(client, uuid="12345678-1234-5678-1234-567812345678")
>>> query.params
[{'name': 'layer', 'value': '12345678-1234-5678-1234-567812345678', 'type': 'Layer'}]
classmethod get_queries(api, **kwargs)[source]

Get Queries

Parameters:

api (GeoboxClient) – The GeoboxClient instance for making requests.

Keyword Arguments:

  • q (str) – query filter based on OGC CQL standard. e.g. “field1 LIKE ‘%GIS%’ AND created_at > ‘2021-01-01’”

  • search (str) – search term for keyword-based searching among search_fields or all textual fields if search_fields does not have value. NOTE: if q param is defined this param will be ignored.

  • search_fields (str) – comma separated list of fields for searching

  • order_by (str) – comma separated list of fields for sorting results [field1 A|D, field2 A|D, …]. e.g. name A, type D. NOTE: “A” denotes ascending order and “D” denotes descending order.

  • return_count (bool) – Whether to return total count. default is False.

  • skip (int) – Number of queries to skip. default is 0.

  • limit (int) – Maximum number of queries to return. default is 10.

  • user_id (int) – Specific user. privileges required.

  • shared (bool) – Whether to return shared queries. default is False.

Returns:

list of queries or the number of queries.

Return type:

List[Query] | int

Example

>>> from geobox import GeoboxClient
>>> from geobox.query import Query
>>> client = GeoboxClient()
>>> queries = Query.get_queries(client)
or
>>> queries = client.get_queries()
classmethod create_query(api, name, display_name=None, description=None, sql=None, params=None)[source]

Creates a new query.

Parameters:

  • api (Api) – The GeoboxClient instance for making requests.

  • name (str) – The name of the query.

  • display_name (str, optional) – The display name of the query.

  • description (str, optional) – The description of the query.

  • sql (str, optional) – The SQL statement for the query.

  • params (list, optional) – The parameters for the SQL statement.

Returns:

The created query instance.

Return type:

Query

Example

>>> from geobox import GeoboxClient
>>> from geobox.query import Query
>>> client = GeoboxClient()
>>> query = Query.create_query(client, name='query_name', display_name='Query Name', sql='SELECT * FROM some_layer')
or
>>> query = client.create_query(name='query_name', display_name='Query Name', sql='SELECT * FROM some_layer')
classmethod get_query(api, uuid, user_id=None)[source]

Retrieves a query by its UUID.

Parameters:

  • api (Api) – The GeoboxClient instance for making requests.

  • uuid (str) – The UUID of the query.

  • user_id (int, optional) – specific user ID. privileges required.

Returns:

The retrieved query instance.

Return type:

Query

Example

>>> from geobox import GeoboxClient
>>> from geobox.query import Query
>>> client = GeoboxClient()
>>> query = Query.get_query(client, uuid="12345678-1234-5678-1234-567812345678")
or
>>> query = client.get_query(uuid="12345678-1234-5678-1234-567812345678")
classmethod get_query_by_name(api, name, user_id=None)[source]

Get a query by name

Parameters:

  • api (GeoboxClient) – The GeoboxClient instance for making requests.

  • name (str) – the name of the query to get

  • user_id (int, optional) – specific user. privileges required.

Returns:

returns the query if a query matches the given name, else None

Return type:

Query | None

Example

>>> from geobox import GeoboxClient
>>> from geobox.query import Query
>>> client = GeoboxClient()
>>> query = Query.get_query_by_name(client, name='test')
or
>>> query = client.get_query_by_name(name='test')
classmethod get_system_queries(api, **kwargs)[source]

Returns the system queries as a list of Query objects.

Parameters:

api (GeoboxClient) – The GeoboxClient instance for making requests.

Keyword Arguments:

  • q (str) – query filter based on OGC CQL standard. e.g. “field1 LIKE ‘%GIS%’ AND created_at > ‘2021-01-01’”.

  • search (str) – search term for keyword-based searching among search_fields or all textual fields if search_fields does not have value. NOTE: if q param is defined this param will be ignored.

  • search_fields (str) – comma separated list of fields for searching.

  • order_by (str) – comma separated list of fields for sorting results [field1 A|D, field2 A|D, …]. e.g. name A, type D. NOTE: “A” denotes ascending order and “D” denotes descending order.

  • return_count (bool) – whether to return the total count of queries. default is False.

  • skip (int) – number of queries to skip. minimum is 0. default is 0.

  • limit (int) – number of queries to return. minimum is 1. default is 100.

  • user_id (int) – specific user. privileges required.

  • shared (bool) – whether to return shared queries. default is False.

Returns:

list of system queries.

Return type:

List[Query]

Example

>>> from geobox import GeoboxClient
>>> from geobox.query import Query
>>> client = GeoboxClient()
>>> queries = Query.get_system_queries(client)
or
>>> queries = client.get_system_queries()
add_param(name, value, type, default_value=None, Domain=None)[source]

Add a parameter to the query parameters.

Parameters:

  • name (str) – The name of the parameter.

  • value (str) – The value of the parameter.

  • type (str) – The type of the parameter (default: ‘Layer’).

  • default_value (str, optional) – The default value for the parameter.

  • Domain (Dict, optional) – Domain information for the parameter.

Returns:

None

Raises:

PermissionError – If the query is a read-only system query.

Return type:

None

Example

>>> from geobox import GeoboxClient
>>> from geobox.query import Query
>>> client = GeoboxClient()
>>> query = Query.get_query(client, uuid="12345678-1234-5678-1234-567812345678")
or
>>> query = client.get_query(uuid="12345678-1234-5678-1234-567812345678")
>>> query.add_param(name='param_name', value='param_value', type=QueryParamType.LAYER)
>>> query.save()
remove_param(name)[source]

Remove a parameter from the query parameters by name.

Parameters:

name (str) – The name of the parameter to remove.

Returns:

None

Raises:

  • ValueError – If the parameter is not found in query parameters.

  • PermissionError – If the query is a read-only system query.

Return type:

None

Example

>>> from geobox import GeoboxClient
>>> from geobox.query import Query
>>> client = GeoboxClient()
>>> query = Query.get_query(client, uuid="12345678-1234-5678-1234-567812345678")
or
>>> query = client.get_query(uuid="12345678-1234-5678-1234-567812345678")
>>> query.remove_param(name='param_name')
>>> query.save()
execute(f='json', result_type=QueryResultType.both, return_count=False, out_srid=None, quant_factor=1000000, bbox_srid=None, skip=None, limit=None, skip_geometry=False)[source]

Execute a query with the given SQL statement and parameters.

Parameters:

  • f (str) – the output format of the executed query. options are: json, topojson. default is json.

  • result_type (QueryResultType, optional) – The type of result to return (default is “both”).

  • return_count (bool, optional) – Whether to return the count of results.

  • out_srid (int, optional) – The output spatial reference ID.

  • quant_factor (int, optional) – The quantization factor (default is 1000000).

  • bbox_srid (int, optional) – The bounding box spatial reference ID.

  • skip (int, optional) – The number of results to skip.

  • limit (int, optional) – The maximum number of results to return.

  • skip_geometry (bool, optional) – Whether to skip the geometry part of the features or not. default is False.

Returns:

The result of the query execution or the count number of the result

Return type:

Dict | int

Example

>>> from geobox import GeoboxClient
>>> from geobox.query import Query
>>> client = GeoboxClient()
>>> query = Query.get_query(client, uuid="12345678-1234-5678-1234-567812345678")
or
>>> query = client.get_query(uuid="12345678-1234-5678-1234-567812345678")
>>> query.execute()
classmethod direct_execute(api, sql, params, f='json', result_type=QueryResultType.both, return_count=False, out_srid=None, quant_factor=1000000, bbox_srid=None, skip=None, limit=None, skip_geometry=False)[source]

Execute raw query with the given SQL statement and parameters directly on geobox, without creating and saving the query instance

Parameters:

  • api (GeoboxClient) – The GeoboxClient instance for making requests

  • sql (str) – the sql query

  • params (List[Dict]) –

    query parameters. a list of dictionaries with these keys: {

    ”name”: str, “type”: Layer, Table, Attribute, Float, Integer, Text, Boolean, “value”: str, “domain”: str(optional),

    }

  • f (str) – the output format of the executed query. options are: json, topojson. default is json.

  • result_type (QueryResultType, optional) – The type of result to return (default is “both”).

  • return_count (bool, optional) – Whether to return the count of results.

  • out_srid (int, optional) – The output spatial reference ID.

  • quant_factor (int, optional) – The quantization factor (default is 1000000).

  • bbox_srid (int, optional) – The bounding box spatial reference ID.

  • skip (int, optional) – The number of results to skip.

  • limit (int, optional) – The maximum number of results to return.

  • skip_geometry (bool, optional) – Whether to skip the geometry part of the features or not. default is False.

Returns:

The result of the query execution or the count number of the result

Return type:

Dict | int

Example

>>> from geobox import GeoboxClient
>>> from geobox.query import Query
>>> client = GeoboxClient()
>>> result = Query.direct_execute(
...     client,
...     sql="SELECT * FROM some_layer",
...     params=[
...         {
...             "name": "some_layer",
...             "type": "Layer",
...             "value": "12345678-1234-5678-1234-567812345678",
...         },
...     ],
... )
update(**kwargs)[source]

Updates the query with new data.

Keyword Arguments:

  • name (str) – The new name of the query.

  • display_name (str) – The new display name of the query.

  • sql (str) – The new SQL statement for the query.

  • params (list) – The new parameters for the SQL statement.

Returns:

The updated query data.

Return type:

Dict

Raises:

PermissionError – If the query is a read-only system query.

Example

>>> from geobox import GeoboxClient
>>> from geobox.query import Query
>>> client = GeoboxClient()
>>> query = Query.get_query(client, uuid="12345678-1234-5678-1234-567812345678")
or
>>> query = client.get_query(uuid="12345678-1234-5678-1234-567812345678")
>>> query.update(name='new_name')
save()[source]

Save the query. Creates a new query if query uuid is None, updates existing query otherwise.

Returns:

None

Return type:

None

Example

>>> from geobox import GeoboxClient
>>> from geobox.query import Query
>>> client = GeoboxClient()
>>> query = Query.get_query(client, uuid="12345678-1234-5678-1234-567812345678")
>>> query.save()
delete()[source]

Deletes a query.

Returns:

The response from the API.

Return type:

str

Raises:

PermissionError – If the query is a read-only system query

Example

>>> from geobox import GeoboxClient
>>> from geobox.query import Query
>>> client = GeoboxClient()
>>> query = Query.get_query(client, uuid="12345678-1234-5678-1234-567812345678")
>>> query.delete()
share(users)[source]

Shares the query with specified users.

Parameters:

users (List[User]) – The list of user objects to share the query with.

Returns:

None

Raises:

PermissionError – If the query is a read-only system query.

Return type:

None

Example

>>> from geobox import GeoboxClient
>>> from geobox.query import Query
>>> client = GeoboxClient()
>>> query = Query.get_query(client, uuid="12345678-1234-5678-1234-567812345678")
>>> users = client.search_users(search="John")
>>> query.share(users=users)
unshare(users)[source]

Unshares the query with specified users.

Parameters:

users (List[User]) – The list of user objects to unshare the query with.

Returns:

None

Raises:

PermissionError – If the query is a read-only system query.

Return type:

None

Example

>>> from geobox import GeoboxClient
>>> from geobox.query import Query
>>> client = GeoboxClient()
>>> query = Query.get_query(client, uuid="12345678-1234-5678-1234-567812345678")
>>> users = client.search_users(search="John")
>>> query.unshare(users=users)
get_shared_users(search=None, skip=0, limit=10)[source]

Retrieves the list of users the query is shared with.

Parameters:

  • search (str, optional) – the search query.

  • skip (int, optional) – The number of users to skip.

  • limit (int, optional) – The maximum number of users to retrieve.

Returns:

The list of shared users.

Return type:

List[User]

Example

>>> from geobox import GeoboxClient
>>> from geobox.query import Query
>>> client = GeoboxClient()
>>> query = Query.get_query(client, uuid="12345678-1234-5678-1234-567812345678")
>>> users = client.search_users(search="John")
>>> query.get_shared_users(search='John', skip=0, limit=10)
property thumbnail: str

Retrieves the thumbnail URL for the query.

Returns:

The thumbnail URL.

Return type:

str

Example

>>> from geobox import GeoboxClient
>>> from geobox.query import Query
>>> client = GeoboxClient()
>>> query = Query.get_query(client, uuid="12345678-1234-5678-1234-567812345678")
>>> query.thumbnail
save_as_layer(layer_name, layer_type=None)[source]

Saves the query as a new layer.

Parameters:

  • layer_name (str) – The name of the new layer.

  • layer_type (QueryGeometryType, optional) – The type of the new layer.

Returns:

The response task object.

Return type:

Task

Example

>>> from geobox import GeoboxClient
>>> from geobox.query import Query
>>> client = GeoboxClient()
>>> query = Query.get_query(client, uuid="12345678-1234-5678-1234-567812345678")
>>> query.add_param(
...     name='layer',
...     value="12345678-1234-5678-1234-567812345678",
...     type=QueryParamType.LAYER,
... )
>>> task = query.save_as_layer(layer_name='test')
classmethod direct_save_as_layer(api, sql, params, layer_name, layer_type=None)[source]

Save a sql query as a new layer without saving

Parameters:

  • api (GeoboxClient) – The GeoboxClient instance for making requests

  • sql (str) – the sql query

  • params (List[Dict]) –

    query parameters. a list of dictionaries with these keys: {

    ”name”: str, “type”: Layer, Table, Attribute, Float, Integer, Text, Boolean, “value”: str, “domain”: str(optional),

    }

  • layer_name (str) – The name of the new layer.

  • layer_type (QueryGeometryType, optional) – The type of the new layer.

Returns:

The response task object.

Return type:

Task

Example

>>> from geobox import GeoboxClient
>>> from geobox.query import Query
>>> client = GeoboxClient()
>>> task = Query.direct_save_as_layer(
...     sql="SELECT * FROM some_layer",
...     params=[
...         {
...             "name": "some_layer",
...             "type": "Layer",
...             "value": "12345678-1234-5678-1234-567812345678",
...         },
...     ],
...     layer_name="test",
... )
save_as_table(table_name)[source]

Saves the query as a new table.

Parameters:

table_name (str) – The name of the new table.

Returns:

The response task object.

Return type:

Task

Example

>>> from geobox import GeoboxClient
>>> from geobox.query import Query
>>> client = GeoboxClient()
>>> query = Query.get_query(client, uuid="12345678-1234-5678-1234-567812345678")
>>> query.add_param(
...     name='table',
...     value="12345678-1234-5678-1234-567812345678",
...     type=QueryParamType.TABLE,
... )
>>> task = query.save_as_table(table_name='test')
classmethod direct_save_as_table(api, sql, params, table_name)[source]

Save a new query as a new table without saving

Parameters:

  • table_name (str) – The name of the new table.

  • api (GeoboxClient)

  • sql (str)

  • params (List[Dict])

Returns:

The response task object.

Return type:

Task

Example

>>> from geobox import GeoboxClient
>>> from geobox.query import Query
>>> client = GeoboxClient()
>>> task = Query.direct_save_as_table(
...     sql="SELECT * FROM some_table",
...     params=[
...         {
...             "name": "some_table",
...             "type": "Table",
...             "value": "12345678-1234-5678-1234-567812345678",
...         },
...     ],
...     table_name="test",
... )