Async Relationship

The async Relationship module provides functionality for working with relationships.

class RelationshipEndpoint(table, field, fk_field=None)[source]

Bases: object

Represents one endpoint (source or target) of a relationship

Parameters:

table (AsyncTable | AsyncVectorLayer) – The source or target table or vector layer
field (AsyncTableField | AsyncField | str) – The field name or object on the source/target entity
fk_field (AsyncTableField | AsyncField | str, optional) – The foreign key field name or object on the relation table. (Required for Many-to-Many relationships)

table: AsyncTable | AsyncVectorLayer

field: AsyncTableField | AsyncField | str

fk_field: AsyncTableField | AsyncField | str | None = None

class AsyncRelationship(api, uuid, data={})[source]

Bases: AsyncBase

Parameters:

api (AsyncGeoboxClient)
uuid (str)
data (Dict | None)

BASE_ENDPOINT = 'relationships/'

__init__(api, uuid, data={})[source]

Initialize a relationship instance.

Parameters:

api (AsyncGeoboxClient) – The GeoboxClient instance for making requests.
uuid (str) – The unique identifier for the relationship.
data (Dict) – The response data of the table.

__repr__()[source]

Return a string representation of the AsyncRelationship.

Returns:: The string representation of the AsyncRelationship.
Return type:: str

property cardinality: RelationshipCardinality: Return: RelationshipCardinality: the relationship cardinality

async classmethod get_relationships(api, **kwargs)[source]

[async] Get a list of relationships with optional filtering and pagination.

Parameters:

api (AsyncGeoboxClient) – 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: False.
skip (int) – Number of items to skip. default: 0
limit (int) – Number of items to return. default: 10
user_id (int) – Specific user. privileges required
shared (bool) – Whether to return shared tables. default: False

Returns:

A list of relationship instances or the total number of relationships.

Return type:

List[AsyncRelationship] | int

Example

>>> from geobox.aio import AsyncGeoboxClient
>>> from geobox.aio.table import AsyncRelatinship
>>> async with AsyncGeoboxClient() as client:
>>>     relationships = await client.get_relationships(q="name LIKE '%My relationship%'")
or
>>>     relationships = await Table.get_relationships(client, q="name LIKE '%My relationship%'")

async classmethod create_relationship(api, name, cardinality, *, source, target, relation_table=None, display_name=None, description=None, user_id=None)[source]

[async] Create a new AsyncRelationship

Parameters:

api (AsyncGeoboxClient) – The GeoboxClient instance for making requests.
name (str) – name of the relationship
cardinality (RelationshipCardinality) – One to One, One to Many, or Many to Many
source (RelationshipEndpoint)
target (RelationshipEndpoint)
relation_table (AsyncTable | None)
display_name (str | None)
description (str | None)
user_id (int | None)

Keyword Arguments:

source (RelationshipEndpoint) – Definition of the source side of the relationship, including the table (or layer), field, and foreign-key field
target (RelationshipEndpoint) – Definition of the target side of the relationship, including the table (or layer), field, and foreign-key field
relation_table (AsyncTable, optional) – The table that stores the relationship metadata or join records. (Required for Many-to-Many relationships)
display_name (str, optional) – Human-readable name for the relationship
description (str, optional) – the description of the relationship
user_id (int, optional) – Specific user. privileges required.

Returns:

a relationship instance

Return type:

AsyncRelationship

Example

>>> from geobox.aio import AsyncGeoboxClient
>>> from geobox.aio.table import AsyncRelationship, RelationshipEndpoint, RelationshipCardinality
>>> async with AsyncGeoboxClient() as client:
>>>     source = RelationshipEndpoint(
...         table=client.get_table_by_name('owner'),
...         field="name", # on source table
...         fk_field="book_name", # on relation table
...     )
>>>     target = RelationshipEndpoint(
...         table=client.get_table_by_name('parcel'),
...         field="name", # on target table
...         fk_field="author_name", # on relation table
...     )
>>>     relationship = await client.create_relationship(
...         name="owner_parcel",
...         cardinality=RelationshipCardinality.ManytoMany,
...         source=source,
...         target=target,
...         relation_table=client.get_table_by_name('owner_parcel'),
...     )
or
>>>     relationship = await AsyncRelationship.create_relationship(
...         client,
...         name="owner_parcel",
...         cardinality=RelationshipCardinality.ManytoMany,
...         source=source,
...         target=target,
...         relation_table=client.get_table_by_name('owner_parcel'),
...     )

async classmethod get_relationship(api, uuid, user_id=None)[source]

[async] Get a relationship by UUID.

Parameters:

api (AsyncGeoboxClient) – The AsyncGeoboxClient instance for making requests.
uuid (str) – The UUID of the relationship to get.
user_id (int, optional) – Specific user. privileges required.

Returns:

The AsyncRelationship object.

Return type:

AsyncRelationship

Raises:

NotFoundError – If the AsyncRelationship with the specified UUID is not found.

Example

>>> from geobox.aio import AsyncGeoboxClient
>>> from geobox.aio.table import AsyncRelationship
>>> async with AsyncGeoboxClient() as client:
>>>     relationship = await client.get_relationship(uuid="12345678-1234-5678-1234-567812345678")
or
>>>     relationship = await AsyncRelationship.get_relationship(client, uuid="12345678-1234-5678-1234-567812345678")

async classmethod get_relationship_by_name(api, name, user_id=None)[source]

[async] Get a relationship by name

Parameters:

api (AsyncGeoboxClient) – The GeoboxClient instance for making requests.
name (str) – the name of the relationship to get
user_id (int, optional) – specific user. privileges required.

Returns:

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

Return type:

AsyncRelationship | None

Example

>>> from geobox.aio import AsyncGeoboxClient
>>> from geobox.aio.table import AsyncRelationship
>>> async with AsyncGeoboxClient() as client:
>>>     relationship = await client.get_relationship_by_name(name='test')
or
>>>     relationship = await AsyncRelationship.get_relationship_by_name(client, name='test')

async update(*, name=None, cardinality=None, source=None, target=None, relation_table=None, display_name=None, description=None)[source]

[async] Update the relationship.

Keyword Arguments:

name (str) – The name of the relationship.
cardinality (RelationshipCardinality) – One to One, One to Many, or Many to Many
source (RelationshipEndpoint) – Definition of the source side of the relationship, including the table (or layer), field, and foreign-key field
target (RelationshipEndpoint) – Definition of the target side of the relationship, including the table (or layer), field, and foreign-key field
relation_table (AsyncTable, optional) – The table that stores the relationship metadata or join records. (Required for Many-to-Many relationships)
display_name (str, optional) – Human-readable name for the relationship
description (str, optional) – the description of the relationship

Returns:

The updated relationship data.

Return type:

Dict

Raises:

ValidationError – If the relationship data is invalid.

Parameters:

name (str | None)
cardinality (RelationshipCardinality | None)
source (RelationshipEndpoint | None)
target (RelationshipEndpoint | None)
relation_table (AsyncTable | None)
display_name (str | None)
description (str | None)

Example

>>> from geobox.aio import AsyncGeoboxClient
>>> from geobox.aio.table import AsyncRelationship
>>> async with AsyncGeoboxClient() as client:
>>>     relationship = await AsyncRelationship.get_relationship(client, uuid="12345678-1234-5678-1234-567812345678")
>>>     await relationship.update(display_name="New Display Name")

async delete()[source]

[async] Delete the AsyncRelationship

Returns:: None
Return type:: None

Example

>>> from geobox.aio import AsyncGeoboxClient
>>> from geobox.aio.table import AsyncRelationship
>>> async with AsyncGeoboxClient() as client:
>>>     relationship = await AsyncRelationship.get_relationship(client, uuid="12345678-1234-5678-1234-567812345678")
>>>     await relationship.delete()

async get_source()[source]

[async] Get the source table or layer

Returns:: the source table or layer
Return type:: AsyncTable | AsyncVectorLayer
Raises:: NotFoundError – if the table or layer has been deleted

Example

>>> from geobox.aio import AsyncGeoboxClient
>>> async with AsyncGeoboxClient() as client:
>>>     relationship = await client.get_relationship(uuid="12345678-1234-5678-1234-567812345678")
>>>     source_table = await relationship.get_source()

async get_target()[source]

[async] Get the target table or layer

Returns:: the target table or layer
Return type:: AsyncTable
Raises:: NotFoundError – if the table or layer has been deleted

Example

>>> from geobox.aio import AsyncGeoboxClient
>>> async with AsyncGeoboxClient() as client:
>>>     relationship = await client.get_relationship(uuid="12345678-1234-5678-1234-567812345678")
>>>     target_table = await relationship.get_target()

async get_relation_table()[source]

[async] Get the relation table

Returns:

the relation table

Return type:

AsyncTable

Raises:

ValueError – If the relationship is not Many-to-Many and thus has no relation table
NotFoundError – if the table has been deleted

Example

>>> from geobox.aio import AsyncGeoboxClient
>>> async with AsyncGeoboxClient() as client:
>>>     relationship = await client.get_relationship(uuid="12345678-1234-5678-1234-567812345678")
>>>     relation_table = await relationship.get_relation_table()

async associate_records(source_id, *, target_ids=None, q=None)[source]

[async] Create relationships between the source record and target records

Parameters:

source_id (int) – the id of feature/row in the source layer/table
target_ids (List[int], optional) – a list of target record ids to be associated with the current record
q (str, optional) – query filter on target layer or table to select which target features or rows that are going to be related to the current record

Returns:

the record association result

Return type:

Dict

Example

>>> from geobox.aio import AsyncGeoboxClient
>>> async with AsyncGeoboxClient() as client:
>>>     relationship = await client.get_relationship(uuid="12345678-1234-5678-1234-567812345678")
>>>     result = await relationship.associate_records(
...         source_id=1,
...         target_ids=[1, 2, 3],
...         q="name LIKE '%_school'",
...     )

async disassociate_records(source_id, *, target_ids=None, q=None)[source]

[async] Remove relationships between the source record and target records

Parameters:

source_id (int) – the id of feature/row in the source layer/table
target_ids (List[int], optional) – a list of target record ids to be disassociated with the current record
q (str, optional) – query filter on target layer or table to select which target features or rows that are going to be related to the current record

Returns:

the record disassociation result

Return type:

Dict

Example

>>> from geobox.aio import AsyncGeoboxClient
>>> async with AsyncGeoboxClient() as client:
>>>     relationship = await client.get_relationship(uuid="12345678-1234-5678-1234-567812345678")
>>>     result = await relationship.disassociate_records(
...         source_id=1,
...         target_ids=[1, 2, 3],
...         q="name LIKE '%_school'",
...     )