Class: QgsRelation¶

Represents a relationship between two vector layers.

class qgis.core.QgsRelation[source]¶

Bases: object

__init__(): Default constructor. Creates an invalid relation.

__init__(context: QgsRelationContext)

Constructor with context. Creates an invalid relation.

Parameters:: context (QgsRelationContext)

__init__(other: QgsRelation)

Copies a relation. This makes a shallow copy, relations are implicitly shared and only duplicated when the copy is changed.

Parameters:: other (QgsRelation)

RelationStrength¶: alias of RelationshipStrength

RelationType¶: alias of RelationshipType

addFieldPair(self, referencingField: str | None, referencedField: str | None)[source]¶

Add a field pair which is part of this relation The first element of each pair are the field names of the foreign key. The second element of each pair are the field names of the matching primary key.

Parameters:

referencingField (Optional[str]) – The field name on the referencing (child) layer (FK)
referencedField (Optional[str]) – The field name on the referenced (parent) layer (PK)

static cardinalityToDisplayString(cardinality: Qgis.RelationshipCardinality) → str[source]¶

Returns a user-friendly translated string representing a relationship cardinality.

Added in version 3.28.

Parameters:: cardinality (Qgis.RelationshipCardinality)
Return type:: str

static createFromXml(node: QDomNode, context: QgsReadWriteContext, relationContext: QgsRelationContext = QgsRelationContext()) → QgsRelation[source]¶

Creates a relation from an XML structure. Used for reading .qgs projects.

Parameters:

node (QDomNode) – The dom node containing the relation information
context (QgsReadWriteContext) – to pass project translator
relationContext (QgsRelationContext = QgsRelationContext()) – a relation context

Return type:

QgsRelation

Returns:

A relation

fieldPairs(self) → Dict[str, str]¶

Returns the field pairs which form this relation The first element of each pair are the field names of the foreign key. The second element of each pair are the field names of the matching primary key.

Return type:: Dict[str, str]
Returns:: The fields forming the relation

generateId(self)[source]¶: Generate a (project-wide) unique id for this relation

getReferencedFeature(self, feature: QgsFeature) → QgsFeature[source]¶

Creates a request to return the feature on the referenced (parent) layer which is referenced by the provided feature.

Parameters:: feature (QgsFeature) – A feature from the referencing (child) layer
Return type:: QgsFeature
Returns:: The referenced (parent) feature, or an invalid feature if no matching feature was found

getReferencedFeatureRequest(self, attributes: Any) → QgsFeatureRequest[source]¶

Creates a request to return the feature on the referenced (parent) layer which is referenced by the provided feature.

Parameters:: attributes (Any) – An attribute vector containing the foreign key
Returns:: A request the referenced feature

getReferencedFeatureRequest(self, feature: QgsFeature) -> QgsFeatureRequest Creates a request to return the feature on the referenced (parent) layer which is referenced by the provided feature.

Parameters:: feature – A feature from the referencing (child) layer
Return type:: QgsFeatureRequest
Returns:: A request the referenced feature

getRelatedFeatures(self, feature: QgsFeature) → QgsFeatureIterator[source]¶

Creates an iterator which returns all the features on the referencing (child) layer which have a foreign key pointing to the provided feature.

Parameters:: feature (QgsFeature) – A feature from the referenced (parent) layer
Return type:: QgsFeatureIterator
Returns:: An iterator with all the referenced features

See also

getRelatedFeaturesRequest()

See also

getRelatedFeaturesFilter()

getRelatedFeaturesFilter(self, feature: QgsFeature) → str[source]¶

Returns a filter expression which returns all the features on the referencing (child) layer which have a foreign key pointing to the provided feature.

Parameters:: feature (QgsFeature) – A feature from the referenced (parent) layer
Return type:: str
Returns:: expression filter string for all the referencing features

See also

getRelatedFeatures()

See also

getRelatedFeaturesRequest()

getRelatedFeaturesRequest(self, feature: QgsFeature) → QgsFeatureRequest[source]¶

Creates a request to return all the features on the referencing (child) layer which have a foreign key pointing to the provided feature.

Parameters:: feature (QgsFeature) – A feature from the referenced (parent) layer
Return type:: QgsFeatureRequest
Returns:: A request for all the referencing features

See also

getRelatedFeatures()

See also

getRelatedFeaturesFilter()

hasEqualDefinition(self, other: QgsRelation) → bool[source]¶

Compares the two QgsRelation, ignoring the name and the ID.

Parameters:: other (QgsRelation) – The other relation
Return type:: bool
Returns:: True if they are similar

id(self) → str[source]¶

A (project-wide) unique id for this relation

Return type:: str
Returns:: The id

isValid(self) → bool[source]¶

Returns the validity of this relation. Don’t use the information if it’s not valid. A relation is considered valid if both referenced and referencig layers are valid.

Return type:: bool
Returns:: True if the relation is valid

See also

validationError()

name(self) → str[source]¶

Returns a human readable name for this relation. Mostly used as title for the children.

See also

id()

Return type:: str
Returns:: A name

polymorphicRelation(self) → QgsPolymorphicRelation[source]¶

Returns the parent polymorphic relation. If the relation is a normal relation, an invalid polymorphic relation is returned.

Added in version 3.18.

Return type:: QgsPolymorphicRelation

polymorphicRelationId(self) → str[source]¶

Returns the parent polymorphic relation id. If the relation is a normal relation, a null string is returned.

Added in version 3.18.

Return type:: str

referencedFields(self) → List[int][source]¶

Returns a list of attributes used to form the referenced fields (most likely primary key) on the referenced (parent) layer.

Return type:: List[int]
Returns:: A list of attributes

referencedLayer(self) → QgsVectorLayer | None[source]¶

Access the referenced (parent) layer

Return type:: Optional[QgsVectorLayer]
Returns:: referenced layer

referencedLayerId(self) → str[source]¶

Access the referenced (parent) layer’s id

Return type:: str
Returns:: The id of the referenced layer

referencingFields(self) → List[int][source]¶

Returns a list of attributes used to form the referencing fields (foreign key) on the referencing (child) layer.

Return type:: List[int]
Returns:: A list of attributes

referencingFieldsAllowNull(self) → bool[source]¶

Returns True if none of the referencing fields has a NOT NULL constraint.

Added in version 3.28.

Return type:: bool

referencingLayer(self) → QgsVectorLayer | None[source]¶

Access the referencing (child) layer This is the layer which has the field(s) which point to another layer

Return type:: Optional[QgsVectorLayer]
Returns:: The referencing layer

referencingLayerId(self) → str[source]¶

Access the referencing (child) layer’s id This is the layer which has the field(s) which point to another layer

Return type:: str
Returns:: The id of the referencing layer

resolveReferencedField(self, referencingField: str | None) → str[source]¶

Gets the referenced field counterpart given a referencing field.

Parameters:: referencingField (Optional[str])
Return type:: str

resolveReferencingField(self, referencedField: str | None) → str[source]¶

Gets the referencing field counterpart given a referenced field.

Parameters:: referencedField (Optional[str])
Return type:: str

setId(self, id: str | None)[source]¶

Set an id for this relation

Parameters:: id (Optional[str])

setName(self, name: str | None)[source]¶

Set a name for this relation

Parameters:: name (Optional[str])

setPolymorphicRelationId(self, polymorphicRelationId: str | None)[source]¶

Sets the parent polymorphic relation id.

Added in version 3.18.

Parameters:: polymorphicRelationId (Optional[str])

setReferencedLayer(self, id: str | None)[source]¶

Set the referenced (parent) layer id. This layer will be searched in the registry.

Parameters:: id (Optional[str])

setReferencingLayer(self, id: str | None)[source]¶

Set the referencing (child) layer id. This layer will be searched in the registry.

Parameters:: id (Optional[str])

setStrength(self, strength: Qgis.RelationshipStrength)[source]¶

Set a strength for this relation

Parameters:: strength (Qgis.RelationshipStrength)

strength(self) → Qgis.RelationshipStrength[source]¶

Returns the relation strength as a string

Return type:: Qgis.RelationshipStrength
Returns:: strength

static strengthToDisplayString(strength: Qgis.RelationshipStrength) → str[source]¶

Returns a user-friendly translated string representing a relationship strength.

Added in version 3.28.

Parameters:: strength (Qgis.RelationshipStrength)
Return type:: str

type(self) → Qgis.RelationshipType[source]¶

Returns the type of the relation

Added in version 3.18.

Return type:: Qgis.RelationshipType

updateRelationStatus(self)[source]¶: Updates the validity status of this relation. Will be called internally whenever a member is changed.

Added in version 3.6.

validationError(self) → str[source]¶

Returns a user-friendly explanation for why the relationship is invalid.

Returns an empty string if the relationship isValid().

See also

isValid()

Added in version 3.28.

Return type:: str

writeXml(self, node: QDomNode, doc: QDomDocument)[source]¶

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

Parameters:

node (QDomNode) – The parent node in which the relation will be created
doc (QDomDocument) – The document in which the relation will be saved