Class: QgsWeakRelation

Represent a QgsRelation with possibly unresolved layers or unmatched fields.

This class is used to store relation information attached to a layer style, a method to attempt relation resolution is also implemented and can be used to create a QgsRelation after the dependent layers are loaded and available.

In contrast to QgsRelation, QgsWeakRelation can be used to encapsulate information about a relationship which does not currently exist in a QGIS project. E.g. it can be used to represent a relationship which exists in a database backend (but not within a QGIS project). Accordingly, some properties available in QgsWeakRelation are included for informational purposes only, and cannot be translated to QgsRelations or respected in QGIS relationships.

Added in version 3.12.

Methods

backwardPathLabel

Returns the label of the backward path for the relationship.

cardinality

Returns the relationship's cardinality.

forwardPathLabel

Returns the label of the forward path for the relationship.

id

Returns the relationship's ID.

mappingReferencedLayerFields

Returns the list of fields from the mappingTable() involved in the relationship.

mappingReferencingLayerFields

Returns the list of fields from the mappingTable() involved in the relationship.

mappingTableName

Returns the layer name of the mapping table, which forms the middle table in many-to-many relationships.

mappingTableProvider

Returns the provider ID for the mapping table, which forms the middle table in many-to-many relationships.

mappingTableSource

Returns the source URI for the mapping table, which forms the middle table in many-to-many relationships.

name

Returns the relationship's name.

referencedLayerFields

Returns the list of fields from the referencedLayer() involved in the relationship.

referencedLayerName

Returns the layer name of the referenced (or "parent" / "left") layer.

referencedLayerProvider

Returns the provider ID for the referenced (or "parent" / "left") layer.

referencedLayerSource

Returns the source URI for the referenced (or "parent" / "left") layer.

referencingLayerFields

Returns the list of fields from the referencingLayer() involved in the relationship.

referencingLayerName

Returns the layer name of the referencing (or "child" / "right") layer.

referencingLayerProvider

Returns the provider ID for the referencing (or "child" / "right") layer.

referencingLayerSource

Returns the source URI for the referencing (or "child" / "right") layer.

relatedTableType

Returns the type string of the related table.

resolvedRelations

Resolves a weak relation in the given project returning a list of possibly invalid QgsRelations and without performing any kind of validity check.

setBackwardPathLabel

Sets the label of the backward path for the relationship.

setCardinality

Sets the relationship's cardinality.

setForwardPathLabel

Sets the label of the forward path for the relationship.

setMappingReferencedLayerFields

Sets the list of fields from the mappingTable() involved in the relationship.

setMappingReferencingLayerFields

Sets the list of fields from the mappingTable() involved in the relationship.

setMappingTable

Sets the source for the mapping table, which forms the middle table in many-to-many relationships, by sourceUri and provider ID.

setReferencedLayer

Sets the source for the referenced (or "parent" / "left") layer, by sourceUri and provider ID.

setReferencedLayerFields

Sets the list of fields from the referencedLayer() involved in the relationship.

setReferencingLayer

Sets the source for the referencing (or "child" / "right") layer, by sourceUri and provider ID.

setReferencingLayerFields

Sets the list of fields from the referencingLayer() involved in the relationship.

setRelatedTableType

Sets the type string of the related table.

strength

Returns the strength of the relation.

Static Methods

readXml

Returns a weak relation for the given layer.

writeXml

Writes a weak relation infoto an XML structure.

Attributes

Referenced

Referencing

class qgis.core.QgsWeakRelation[source]

Bases: object

__init__()

Default constructor for an invalid relation.

__init__(relationId: str | None, relationName: str | None, strength: Qgis.RelationshipStrength, referencingLayerId: str | None, referencingLayerName: str | None, referencingLayerSource: str | None, referencingLayerProviderKey: str | None, referencedLayerId: str | None, referencedLayerName: str | None, referencedLayerSource: str | None, referencedLayerProviderKey: str | None)

Creates a QgsWeakRelation.

Added in version 3.30.

Parameters:
  • relationId (Optional[str])

  • relationName (Optional[str])

  • strength (Qgis.RelationshipStrength)

  • referencingLayerId (Optional[str])

  • referencingLayerName (Optional[str])

  • referencingLayerSource (Optional[str])

  • referencingLayerProviderKey (Optional[str])

  • referencedLayerId (Optional[str])

  • referencedLayerName (Optional[str])

  • referencedLayerSource (Optional[str])

  • referencedLayerProviderKey (Optional[str])

__init__(a0: QgsWeakRelation)
Parameters:

a0 (QgsWeakRelation)

Referenced = 1
Referencing = 0
class WeakRelationType

Bases: int

backwardPathLabel(self) str[source]

Returns the label of the backward path for the relationship.

The forward and backward path labels are free-form, user-friendly strings which can be used to generate descriptions of the relationship between features from the right and left tables.

E.g. when the left table contains buildings and the right table contains furniture, the forward path label could be “contains” and the backward path label could be “is located within”. A client could then generate a user friendly description string such as “fire hose 1234 is located within building 15a”.

Added in version 3.28.

Return type:

str

cardinality(self) Qgis.RelationshipCardinality[source]

Returns the relationship’s cardinality.

See also

setCardinality()

Added in version 3.28.

Return type:

Qgis.RelationshipCardinality

forwardPathLabel(self) str[source]

Returns the label of the forward path for the relationship.

The forward and backward path labels are free-form, user-friendly strings which can be used to generate descriptions of the relationship between features from the right and left tables.

E.g. when the left table contains buildings and the right table contains furniture, the forward path label could be “contains” and the backward path label could be “is located within”. A client could then generate a user friendly description string such as “fire hose 1234 is located within building 15a”.

Added in version 3.28.

Return type:

str

id(self) str[source]

Returns the relationship’s ID.

Added in version 3.28.

Return type:

str

mappingReferencedLayerFields(self) List[str][source]

Returns the list of fields from the mappingTable() involved in the relationship.

These fields will be matched to the referencedLayerFields() in many-to-many joins.

Added in version 3.28.

Return type:

List[str]

mappingReferencingLayerFields(self) List[str][source]

Returns the list of fields from the mappingTable() involved in the relationship.

These fields will be matched to the referencingLayerFields() in many-to-many joins.

Added in version 3.28.

Return type:

List[str]

mappingTableName(self) str[source]

Returns the layer name of the mapping table, which forms the middle table in many-to-many relationships.

Note

the layer name refers to the layer name used in the datasource, not in any associated QgsVectorLayer.

Added in version 3.28.

Return type:

str

mappingTableProvider(self) str[source]

Returns the provider ID for the mapping table, which forms the middle table in many-to-many relationships.

Added in version 3.28.

Return type:

str

mappingTableSource(self) str[source]

Returns the source URI for the mapping table, which forms the middle table in many-to-many relationships.

Added in version 3.28.

Return type:

str

name(self) str[source]

Returns the relationship’s name.

Added in version 3.28.

Return type:

str

static readXml(layer: QgsVectorLayer | None, type: QgsWeakRelation.WeakRelationType, node: QDomNode, resolver: QgsPathResolver) QgsWeakRelation[source]

Returns a weak relation for the given layer.

Parameters:

Added in version 3.16.

Return type:

QgsWeakRelation

referencedLayerFields(self) List[str][source]

Returns the list of fields from the referencedLayer() involved in the relationship.

Added in version 3.28.

Return type:

List[str]

referencedLayerName(self) str[source]

Returns the layer name of the referenced (or “parent” / “left”) layer.

Note

the layer name refers to the layer name used in the datasource, not in any associated QgsVectorLayer.

Added in version 3.28.

Return type:

str

referencedLayerProvider(self) str[source]

Returns the provider ID for the referenced (or “parent” / “left”) layer.

Added in version 3.28.

Return type:

str

referencedLayerSource(self) str[source]

Returns the source URI for the referenced (or “parent” / “left”) layer.

Added in version 3.28.

Return type:

str

referencingLayerFields(self) List[str][source]

Returns the list of fields from the referencingLayer() involved in the relationship.

Added in version 3.28.

Return type:

List[str]

referencingLayerName(self) str[source]

Returns the layer name of the referencing (or “child” / “right”) layer.

Note

the layer name refers to the layer name used in the datasource, not in any associated QgsVectorLayer.

Added in version 3.28.

Return type:

str

referencingLayerProvider(self) str[source]

Returns the provider ID for the referencing (or “child” / “right”) layer.

Added in version 3.28.

Return type:

str

referencingLayerSource(self) str[source]

Returns the source URI for the referencing (or “child” / “right”) layer.

Added in version 3.28.

Return type:

str

relatedTableType(self) str[source]

Returns the type string of the related table.

This a free-form string representing the type of related features, where the exact interpretation is format dependent. For instance, table types from GeoPackage relationships will directly reflect the categories from the GeoPackage related tables extension (i.e. “media”, “simple attributes”, “features”, “attributes” and “tiles”).

Added in version 3.28.

Return type:

str

resolvedRelations(self, project: QgsProject | None) List[QgsRelation]

Resolves a weak relation in the given project returning a list of possibly invalid QgsRelations and without performing any kind of validity check.

Note

Client code should never assume that the returned relations are valid and the layer components are not NULL.

Parameters:

project (Optional[QgsProject])

Return type:

List[QgsRelation]

setBackwardPathLabel(self, label: str | None)[source]

Sets the label of the backward path for the relationship.

The forward and backward path labels are free-form, user-friendly strings which can be used to generate descriptions of the relationship between features from the right and left tables.

E.g. when the left table contains buildings and the right table contains furniture, the forward path label could be “contains” and the backward path label could be “is located within”. A client could then generate a user friendly description string such as “fire hose 1234 is located within building 15a”.

Added in version 3.28.

Parameters:

label (Optional[str])

setCardinality(self, cardinality: Qgis.RelationshipCardinality)[source]

Sets the relationship’s cardinality.

See also

cardinality()

Added in version 3.28.

Parameters:

cardinality (Qgis.RelationshipCardinality)

setForwardPathLabel(self, label: str | None)[source]

Sets the label of the forward path for the relationship.

The forward and backward path labels are free-form, user-friendly strings which can be used to generate descriptions of the relationship between features from the right and left tables.

E.g. when the left table contains buildings and the right table contains furniture, the forward path label could be “contains” and the backward path label could be “is located within”. A client could then generate a user friendly description string such as “fire hose 1234 is located within building 15a”.

Added in version 3.28.

Parameters:

label (Optional[str])

setMappingReferencedLayerFields(self, fields: Iterable[str | None])[source]

Sets the list of fields from the mappingTable() involved in the relationship.

These fields will be matched to the referencedLayerFields() in many-to-many joins.

Added in version 3.28.

Parameters:

fields (Iterable[Optional[str]])

setMappingReferencingLayerFields(self, fields: Iterable[str | None])[source]

Sets the list of fields from the mappingTable() involved in the relationship.

These fields will be matched to the referencingLayerFields() in many-to-many joins.

Added in version 3.28.

Parameters:

fields (Iterable[Optional[str]])

setMappingTable(self, sourceUri: str | None, provider: str | None)[source]

Sets the source for the mapping table, which forms the middle table in many-to-many relationships, by sourceUri and provider ID.

Added in version 3.36.

Parameters:
  • sourceUri (Optional[str])

  • provider (Optional[str])

setReferencedLayer(self, sourceUri: str | None, provider: str | None)[source]

Sets the source for the referenced (or “parent” / “left”) layer, by sourceUri and provider ID.

Added in version 3.36.

Parameters:
  • sourceUri (Optional[str])

  • provider (Optional[str])

setReferencedLayerFields(self, fields: Iterable[str | None])[source]

Sets the list of fields from the referencedLayer() involved in the relationship.

Added in version 3.28.

Parameters:

fields (Iterable[Optional[str]])

setReferencingLayer(self, sourceUri: str | None, provider: str | None)[source]

Sets the source for the referencing (or “child” / “right”) layer, by sourceUri and provider ID.

Added in version 3.36.

Parameters:
  • sourceUri (Optional[str])

  • provider (Optional[str])

setReferencingLayerFields(self, fields: Iterable[str | None])[source]

Sets the list of fields from the referencingLayer() involved in the relationship.

Added in version 3.28.

Parameters:

fields (Iterable[Optional[str]])

setRelatedTableType(self, type: str | None)[source]

Sets the type string of the related table.

This a free-form string representing the type of related features, where the exact interpretation is format dependent. For instance, table types from GeoPackage relationships will directly reflect the categories from the GeoPackage related tables extension (i.e. “media”, “simple attributes”, “features”, “attributes” and “tiles”).

Added in version 3.28.

Parameters:

type (Optional[str])

strength(self) Qgis.RelationshipStrength[source]

Returns the strength of the relation.

Return type:

Qgis.RelationshipStrength

static writeXml(layer: QgsVectorLayer | None, type: QgsWeakRelation.WeakRelationType, relation: QgsRelation, node: QDomNode, doc: QDomDocument)[source]

Writes a weak relation infoto an XML structure. Used for saving .qgs projects

Parameters:
  • layer (Optional[QgsVectorLayer]) – the layer which we save the weak relation for

  • type (QgsWeakRelation.WeakRelationType) – determines if the layer is referencing or referenced

  • relation (QgsRelation) – the relation to save as a weak relation

  • node (QDomNode) – The parent node in which the relation will be created

  • doc (QDomDocument) – The document in which the relation will be saved

Added in version 3.16.