Class: QgsRelation

class qgis.core.QgsRelation

Bases: sip.wrapper

Default constructor. Creates an invalid relation.

QgsRelation(context: QgsRelationContext) Constructor with context. Creates an invalid relation.

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

Enums

RelationStrength

alias of RelationshipStrength

RelationType

alias of RelationshipType

Methods

addFieldPair

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

cardinalityToDisplayString

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

createFromXml

Creates a relation from an XML structure.

fieldPairs

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

generateId

Generate a (project-wide) unique id for this relation

getReferencedFeature

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

getReferencedFeatureRequest

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

getRelatedFeatures

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

getRelatedFeaturesFilter

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

getRelatedFeaturesRequest

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

hasEqualDefinition

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

id

A (project-wide) unique id for this relation

isValid

Returns the validity of this relation.

name

Returns a human readable name for this relation.

polymorphicRelation

Returns the parent polymorphic relation.

polymorphicRelationId

Returns the parent polymorphic relation id.

referencedFields

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

referencedLayer

Access the referenced (parent) layer

referencedLayerId

Access the referenced (parent) layer's id

referencingFields

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

referencingLayer

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

referencingLayerId

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

resolveReferencedField

Gets the referenced field counterpart given a referencing field.

resolveReferencingField

Gets the referencing field counterpart given a referenced field.

setId

Set an id for this relation

setName

Set a name for this relation

setPolymorphicRelationId

Sets the parent polymorphic relation id.

setReferencedLayer

Set the referenced (parent) layer id.

setReferencingLayer

Set the referencing (child) layer id.

setStrength

Set a strength for this relation

strength

Returns the relation strength as a string

strengthToDisplayString

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

type

Returns the type of the relation

updateRelationStatus

Updates the validity status of this relation.

validationError

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

writeXml

Writes a relation to an XML structure.

Attributes

staticMetaObject

RelationStrength

alias of RelationshipStrength

RelationType

alias of RelationshipType

addFieldPair(self, referencingField: str | None, referencedField: str | None)

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)

cardinalityToDisplayString(cardinality: Qgis.RelationshipCardinality) str

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

Added in version 3.28.

Parameters:

cardinality (Qgis.RelationshipCardinality)

Return type:

str

createFromXml(node: QDomNode, context: QgsReadWriteContext, relationContext: QgsRelationContext = QgsRelationContext()) QgsRelation

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)

Generate a (project-wide) unique id for this relation

getReferencedFeature(self, feature: QgsFeature) QgsFeature

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:

A request the referenced feature

getReferencedFeatureRequest(self, attributes: Any) QgsFeatureRequest

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

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

getRelatedFeaturesFilter(self, feature: QgsFeature) str

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

getRelatedFeaturesRequest(self, feature: QgsFeature) QgsFeatureRequest

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

hasEqualDefinition(self, other: QgsRelation) bool

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

A (project-wide) unique id for this relation

Return type:

str

Returns:

The id

isValid(self) bool

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

name(self) str

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

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

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]

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

Access the referenced (parent) layer

Return type:

Optional[QgsVectorLayer]

Returns:

referenced layer

referencedLayerId(self) str

Access the referenced (parent) layer’s id

Return type:

str

Returns:

The id of the referenced layer

referencingFields(self) List[int]

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

referencingLayer(self) QgsVectorLayer | None

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

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

Gets the referenced field counterpart given a referencing field.

Parameters:

referencingField (Optional[str])

Return type:

str

resolveReferencingField(self, referencedField: str | None) str

Gets the referencing field counterpart given a referenced field.

Parameters:

referencedField (Optional[str])

Return type:

str

setId(self, id: str | None)

Set an id for this relation

Parameters:

id (Optional[str])

setName(self, name: str | None)

Set a name for this relation

Parameters:

name (Optional[str])

setPolymorphicRelationId(self, polymorphicRelationId: str | None)

Sets the parent polymorphic relation id.

Added in version 3.18.

Parameters:

polymorphicRelationId (Optional[str])

setReferencedLayer(self, id: str | None)

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

Parameters:

id (Optional[str])

setReferencingLayer(self, id: str | None)

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

Parameters:

id (Optional[str])

setStrength(self, strength: Qgis.RelationshipStrength)

Set a strength for this relation

Parameters:

strength (Qgis.RelationshipStrength)

staticMetaObject = <PyQt5.QtCore.QMetaObject object>
strength(self) Qgis.RelationshipStrength

Returns the relation strength as a string

Return type:

Qgis.RelationshipStrength

Returns:

strength

strengthToDisplayString(strength: Qgis.RelationshipStrength) str

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

Returns the type of the relation

Added in version 3.18.

Return type:

Qgis.RelationshipType

updateRelationStatus(self)

Updates the validity status of this relation. Will be called internally whenever a member is changed.

Added in version 3.6.

validationError(self) str

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)

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