Relationship

The Relationship module provides functionality for working with relationships.

class RelationshipEndpoint(table, field, fk_field=None)

Bases: object

Represents one endpoint (source or target) of a relationship

Parameters:

• table (Table | VectorLayer) – The source or target table or vector layer

• field (TableField | Field | str) – The field name or object on the source/target entity

• fk_field (TableField | Field | str, optional) – The foreign key field name or object on the relation table. (Required for Many-to-Many relationships)

table: Table | VectorLayer

field: TableField | Field | str

fk_field: TableField | Field | str | None = None

class Relationship(api, uuid, data={})

Bases: Base

Parameters:

• api (GeoboxClient)

• uuid (str)

• data (Dict | None)

BASE_ENDPOINT = 'relationships/'

__init__(api, uuid, data={})

Initialize a relationship instance.

Parameters:

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

• uuid (str) – The unique identifier for the relationship.

• data (Dict) – The response data of the table.

__repr__()

Return a string representation of the Relationship.

Returns:

The string representation of the Relationship.

Return type:

str

property cardinality: RelationshipCardinality

Return: RelationshipCardinality: the relationship cardinality

classmethod get_relationships(api, **kwargs)

Get a list of relationships with optional filtering and pagination.

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: 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[Relationship] | int

Example

>>> from geobox import GeoboxClient
>>> from geobox.table import Relatinship
>>> client = GeoboxClient()
>>> relationships = client.get_relationships(q="name LIKE '%My relationship%'")
or
>>> relationships = Table.get_relationships(client, q="name LIKE '%My relationship%'")

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

Create a new Relationship

Parameters:

• api (GeoboxClient) – 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 (Table | 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 (Table, 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:

Relationship

Example

>>> from geobox import GeoboxClient
>>> from geobox.table import Relationship, RelationshipEndpoint, RelationshipCardinality
>>> client = GeoboxClient()
>>> 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 = client.create_relationship(
...     name="owner_parcel",
...     cardinality=RelationshipCardinality.ManytoMany,
...     source=source,
...     target=target,
...     relation_table=client.get_table_by_name('owner_parcel'),
... )
or
>>> relationship = Relationsh.create_relationship(
...     client,
...     name="owner_parcel",
...     cardinality=RelationshipCardinality.ManytoMany,
...     source=source,
...     target=target,
...     relation_table=client.get_table_by_name('owner_parcel'),
... )

classmethod get_relationship(api, uuid, user_id=None)

Get a relationship by UUID.

Parameters:

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

• uuid (str) – The UUID of the relationship to get.

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

Returns:

The Relationship object.

Return type:

Relationship

Raises:

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

Example

>>> from geobox import GeoboxClient
>>> from geobox.table import Relationship
>>> client = GeoboxClient()
>>> relationship = client.get_relationship(uuid="12345678-1234-5678-1234-567812345678")
or
>>> relationship = Relationship.get_relationship(client, uuid="12345678-1234-5678-1234-567812345678")

classmethod get_relationship_by_name(api, name, user_id=None)

Get a relationship by name

Parameters:

• api (GeoboxClient) – 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:

Relationship | None

Example

>>> from geobox import GeoboxClient
>>> from geobox.relationship import Relationship
>>> client = GeoboxClient()
>>> relationship = client.get_relationship_by_name(name='test')
or
>>> relationship = Relationship.get_relationship_by_name(client, name='test')

update(*, name=None, cardinality=None, source=None, target=None, relation_table=None, display_name=None, description=None)

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 (Table, 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 (Table | None)

• display_name (str | None)

• description (str | None)

Example

>>> from geobox import GeoboxClient
>>> from geobox.table import Relationship
>>> client = GeoboxClient()
>>> relationship = Relationship.get_relationship(client, uuid="12345678-1234-5678-1234-567812345678")
>>> relationship.update(display_name="New Display Name")

delete()

Delete the Relationship

Returns:

None

Return type:

None

Example

>>> from geobox import GeoboxClient
>>> from geobox.table import Relationship
>>> client = GeoboxClient()
>>> relationship = Relationship.get_relationship(client, uuid="12345678-1234-5678-1234-567812345678")
>>> relationship.delete()

get_source()

Get the source table or layer

Returns:

the source table or layer

Return type:

Table | VectorLayer

Raises:

NotFoundError – if the table or layer has been deleted

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> relationship = client.get_relationship(uuid="12345678-1234-5678-1234-567812345678")
>>> source = relationship.get_source()

get_target()

Get the target table or layer

Returns:

the target table or layer

Return type:

Table | VectorLayer

Raises:

NotFoundError – if the table or layer has been deleted

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> relationship = client.get_relationship(uuid="12345678-1234-5678-1234-567812345678")
>>> target_table = relationship.get_target()

get_relation_table()

Get the relation table

Returns:

the relation table

Return type:

Table

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 import GeoboxClient
>>> client = GeoboxClient()
>>> relationship = client.get_relationship(uuid="12345678-1234-5678-1234-567812345678")
>>> relation_table = relationship.get_relation_table()

associate_records(source_id, *, target_ids=None, q=None)

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 import GeoboxClient
>>> client = GeoboxClient()
>>> relationship = client.get_relationship(uuid="12345678-1234-5678-1234-567812345678")
>>> result = relationship.associate_records(
...     source_id=1,
...     target_ids=[1, 2, 3],
...     q="name LIKE '%_school'",
... )

disassociate_records(source_id, *, target_ids=None, q=None)

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 import GeoboxClient
>>> client = GeoboxClient()
>>> relationship = client.get_relationship(uuid="12345678-1234-5678-1234-567812345678")
>>> result = relationship.disassociate_records(
...     source_id=1,
...     target_ids=[1, 2, 3],
...     q="name LIKE '%_school'",
... )