Represents a relationship between two vector layers. More...

#include <qgsrelation.h>

Classes
class	FieldPair
	Defines a relation between matching fields of the two involved tables of a relation. More...

Public Member Functions
	QgsRelation ()
	Default constructor.
	QgsRelation (const QgsRelation &other)
	Copies a relation.
	QgsRelation (const QgsRelationContext &context)
	Constructor with context.
	QgsRelation (QgsRelation &&other)
	~QgsRelation ()
void	addFieldPair (const FieldPair &fieldPair)
	Add a field pair which is part of this relation The first element of each pair are the field names of the foreign key.
Q_INVOKABLE void	addFieldPair (const QString &referencingField, const QString &referencedField)
	Add a field pair which is part of this relation The first element of each pair are the field names of the foreign key.
QList< QgsRelation::FieldPair >	fieldPairs () const
	Returns the field pairs which form this relation The first element of each pair are the field names of the foreign key.
void	generateId ()
	Generate a (project-wide) unique id for this relation.
Q_INVOKABLE QgsFeature	getReferencedFeature (const QgsFeature &feature) const
	Creates a request to return the feature on the referenced (parent) layer which is referenced by the provided feature.
QgsFeatureRequest	getReferencedFeatureRequest (const QgsAttributes &attributes) const
	Creates a request to return the feature on the referenced (parent) layer which is referenced by the provided feature.
QgsFeatureRequest	getReferencedFeatureRequest (const QgsFeature &feature) const
	Creates a request to return the feature on the referenced (parent) layer which is referenced by the provided feature.
QgsFeatureIterator	getRelatedFeatures (const QgsFeature &feature) const
	Creates an iterator which returns all the features on the referencing (child) layer which have a foreign key pointing to the provided feature.
Q_INVOKABLE QString	getRelatedFeaturesFilter (const QgsFeature &feature) const
	Returns a filter expression which returns all the features on the referencing (child) layer which have a foreign key pointing to the provided feature.
QgsFeatureRequest	getRelatedFeaturesRequest (const QgsFeature &feature) const
	Creates a request to return all the features on the referencing (child) layer which have a foreign key pointing to the provided feature.
bool	hasEqualDefinition (const QgsRelation &other) const
	Compares the two QgsRelation, ignoring the name and the ID.
QString	id () const
	A (project-wide) unique id for this relation.
bool	isValid () const
	Returns the validity of this relation.
QString	name () const
	Returns a human readable name for this relation.
QgsRelation &	operator= (const QgsRelation &other)
	Copies a relation.
QgsRelation &	operator= (QgsRelation &&other)
QgsPolymorphicRelation	polymorphicRelation () const
	Returns the parent polymorphic relation.
QString	polymorphicRelationId () const
	Returns the parent polymorphic relation id.
QgsAttributeList	referencedFields () const
	Returns a list of attributes used to form the referenced fields (most likely primary key) on the referenced (parent) layer.
QgsVectorLayer *	referencedLayer () const
	Access the referenced (parent) layer.
QString	referencedLayerId () const
	Access the referenced (parent) layer's id.
QgsAttributeList	referencingFields () const
	Returns a list of attributes used to form the referencing fields (foreign key) on the referencing (child) layer.
bool	referencingFieldsAllowNull () const
	Returns `true` if none of the referencing fields has a NOT NULL constraint.
QgsVectorLayer *	referencingLayer () const
	Access the referencing (child) layer This is the layer which has the field(s) which point to another layer.
QString	referencingLayerId () const
	Access the referencing (child) layer's id This is the layer which has the field(s) which point to another layer.
Q_INVOKABLE QString	resolveReferencedField (const QString &referencingField) const
	Gets the referenced field counterpart given a referencing field.
Q_INVOKABLE QString	resolveReferencingField (const QString &referencedField) const
	Gets the referencing field counterpart given a referenced field.
void	setId (const QString &id)
	Set an id for this relation.
void	setName (const QString &name)
	Set a name for this relation.
void	setPolymorphicRelationId (const QString &polymorphicRelationId)
	Sets the parent polymorphic relation id.
void	setReferencedLayer (const QString &id)
	Set the referenced (parent) layer id.
void	setReferencingLayer (const QString &id)
	Set the referencing (child) layer id.
void	setStrength (Qgis::RelationshipStrength strength)
	Set a strength for this relation.
Qgis::RelationshipStrength	strength () const
	Returns the relation strength as a string.
Qgis::RelationshipType	type () const
	Returns the type of the relation.
void	updateRelationStatus ()
	Updates the validity status of this relation.
QString	validationError () const
	Returns a user-friendly explanation for why the relationship is invalid.
void	writeXml (QDomNode &node, QDomDocument &doc) const
	Writes a relation to an XML structure.

Static Public Member Functions
static QString	cardinalityToDisplayString (Qgis::RelationshipCardinality cardinality)
	Returns a user-friendly translated string representing a relationship cardinality.
static Q_DECL_DEPRECATED QgsRelation	createFromXml (const QDomNode &node, QgsReadWriteContext &context)
	Creates a relation from an XML structure.
static QgsRelation	createFromXml (const QDomNode &node, QgsReadWriteContext &context, const QgsRelationContext &relationContext)
	Creates a relation from an XML structure.
static QString	strengthToDisplayString (Qgis::RelationshipStrength strength)
	Returns a user-friendly translated string representing a relationship strength.

Properties
QString	id
bool	isValid
QString	name
QgsPolymorphicRelation	polymorphicRelation
QString	polymorphicRelationId
QList< int >	referencedFields
QgsVectorLayer *	referencedLayer
QString	referencedLayerId
QList< int >	referencingFields
QgsVectorLayer *	referencingLayer
QString	referencingLayerId
Qgis::RelationshipStrength	strength

Detailed Description

Represents a relationship between two vector layers.

Definition at line 41 of file qgsrelation.h.

Constructor & Destructor Documentation

◆ QgsRelation() [1/4]

QgsRelation::QgsRelation ( )

Default constructor.

Creates an invalid relation.

Definition at line 33 of file qgsrelation.cpp.

◆ ~QgsRelation()

QgsRelation::~QgsRelation ( )

default

◆ QgsRelation() [2/4]

QgsRelation::QgsRelation ( const QgsRelationContext & context )

Constructor with context.

Creates an invalid relation.

Definition at line 38 of file qgsrelation.cpp.

◆ QgsRelation() [3/4]

QgsRelation::QgsRelation ( const QgsRelation & other )

Copies a relation.

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

Definition at line 45 of file qgsrelation.cpp.

◆ QgsRelation() [4/4]

QgsRelation::QgsRelation ( QgsRelation && other )

Definition at line 50 of file qgsrelation.cpp.

Member Function Documentation

◆ addFieldPair() [1/2]

void QgsRelation::addFieldPair ( const FieldPair & fieldPair )

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

fieldPair A pair of two strings

Note: not available in Python bindings

Definition at line 209 of file qgsrelation.cpp.

◆ addFieldPair() [2/2]

void QgsRelation::addFieldPair	(	const QString &	referencingField,
		const QString &	referencedField )

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	The field name on the referencing (child) layer (FK)
referencedField	The field name on the referenced (parent) layer (PK)

Definition at line 202 of file qgsrelation.cpp.

◆ cardinalityToDisplayString()

QString QgsRelation::cardinalityToDisplayString ( Qgis::RelationshipCardinality cardinality )

static

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

Since: QGIS 3.28

Definition at line 548 of file qgsrelation.cpp.

◆ createFromXml() [1/2]

QgsRelation QgsRelation::createFromXml	(	const QDomNode &	node,
		QgsReadWriteContext &	context )

static

Creates a relation from an XML structure.

Used for reading .qgs projects.

Parameters

node	The dom node containing the relation information
context	to pass project translator

Returns: A relation

Deprecated: QGIS 4.4. Use createFromXml( const QDomNode &node, QgsReadWriteContext &context, const QgsRelationContext &relationContext ) instead.

Definition at line 76 of file qgsrelation.cpp.

◆ createFromXml() [2/2]

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

static

Creates a relation from an XML structure.

Used for reading .qgs projects.

Parameters

node	The dom node containing the relation information
context	to pass project translator
relationContext	a relation context

Returns: A relation

Definition at line 81 of file qgsrelation.cpp.

◆ fieldPairs()

QList< QgsRelation::FieldPair > QgsRelation::fieldPairs ( ) const

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.

Returns: The fields forming the relation

Definition at line 354 of file qgsrelation.cpp.

◆ generateId()

void QgsRelation::generateId ( )

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

Definition at line 324 of file qgsrelation.cpp.

◆ getReferencedFeature()

QgsFeature QgsRelation::getReferencedFeature ( const QgsFeature & feature ) const

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

Returns: The referenced (parent) feature, or an invalid feature if no matching feature was found

Definition at line 300 of file qgsrelation.cpp.

◆ getReferencedFeatureRequest() [1/2]

QgsFeatureRequest QgsRelation::getReferencedFeatureRequest ( const QgsAttributes & attributes ) const

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

Parameters

attributes An attribute vector containing the foreign key

Returns: A request the referenced feature

Definition at line 267 of file qgsrelation.cpp.

◆ getReferencedFeatureRequest() [2/2]

QgsFeatureRequest QgsRelation::getReferencedFeatureRequest ( const QgsFeature & feature ) const

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

Returns: A request the referenced feature

Definition at line 295 of file qgsrelation.cpp.

◆ getRelatedFeatures()

QgsFeatureIterator QgsRelation::getRelatedFeatures ( const QgsFeature & feature ) const

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 A feature from the referenced (parent) layer

Returns: An iterator with all the referenced features

See also: getRelatedFeaturesRequest(); getRelatedFeaturesFilter()

Definition at line 216 of file qgsrelation.cpp.

◆ getRelatedFeaturesFilter()

QString QgsRelation::getRelatedFeaturesFilter ( const QgsFeature & feature ) const

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 A feature from the referenced (parent) layer

Returns: expression filter string for all the referencing features

See also: getRelatedFeatures(); getRelatedFeaturesRequest()

Definition at line 231 of file qgsrelation.cpp.

◆ getRelatedFeaturesRequest()

QgsFeatureRequest QgsRelation::getRelatedFeaturesRequest ( const QgsFeature & feature ) const

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 A feature from the referenced (parent) layer

Returns: A request for all the referencing features

See also: getRelatedFeatures(); getRelatedFeaturesFilter()

Definition at line 221 of file qgsrelation.cpp.

◆ hasEqualDefinition()

bool QgsRelation::hasEqualDefinition ( const QgsRelation & other ) const

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

Parameters

other The other relation

Returns: true if they are similar

Definition at line 437 of file qgsrelation.cpp.

◆ id()

QString QgsRelation::id ( ) const

A (project-wide) unique id for this relation.

Returns: The id

Definition at line 319 of file qgsrelation.cpp.

◆ isValid()

bool QgsRelation::isValid ( ) const

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.

Returns: true if the relation is valid

See also: validationError()

Definition at line 405 of file qgsrelation.cpp.

◆ name()

QString QgsRelation::name ( ) const

Returns a human readable name for this relation.

Mostly used as title for the children.

See also: id()

Returns: A name

Definition at line 309 of file qgsrelation.cpp.

◆ operator=() [1/2]

QgsRelation & QgsRelation::operator= ( const QgsRelation & other )

Copies a relation.

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

Definition at line 55 of file qgsrelation.cpp.

◆ operator=() [2/2]

QgsRelation & QgsRelation::operator= ( QgsRelation && other )

Definition at line 65 of file qgsrelation.cpp.

◆ polymorphicRelation()

QgsPolymorphicRelation QgsRelation::polymorphicRelation ( ) const

Returns the parent polymorphic relation.

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

Since: QGIS 3.18

Definition at line 532 of file qgsrelation.cpp.

◆ polymorphicRelationId()

QString QgsRelation::polymorphicRelationId ( ) const

Returns the parent polymorphic relation id.

If the relation is a normal relation, a null string is returned.

Since: QGIS 3.18

Definition at line 527 of file qgsrelation.cpp.

◆ referencedFields()

QgsAttributeList QgsRelation::referencedFields ( ) const

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

Returns: A list of attributes

Definition at line 359 of file qgsrelation.cpp.

◆ referencedLayer()

QgsVectorLayer * QgsRelation::referencedLayer ( ) const

Access the referenced (parent) layer.

Returns: referenced layer

Definition at line 349 of file qgsrelation.cpp.

◆ referencedLayerId()

QString QgsRelation::referencedLayerId ( ) const

Access the referenced (parent) layer's id.

Returns: The id of the referenced layer

Definition at line 344 of file qgsrelation.cpp.

◆ referencingFields()

QgsAttributeList QgsRelation::referencingFields ( ) const

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

Returns: A list of attributes

Definition at line 370 of file qgsrelation.cpp.

◆ referencingFieldsAllowNull()

bool QgsRelation::referencingFieldsAllowNull ( ) const

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

Since: QGIS 3.28

Definition at line 381 of file qgsrelation.cpp.

◆ referencingLayer()

QgsVectorLayer * QgsRelation::referencingLayer ( ) const

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

Returns: The referencing layer

Definition at line 339 of file qgsrelation.cpp.

◆ referencingLayerId()

QString QgsRelation::referencingLayerId ( ) const

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

Returns: The id of the referencing layer

Definition at line 334 of file qgsrelation.cpp.

◆ resolveReferencedField()

QString QgsRelation::resolveReferencedField ( const QString & referencingField ) const

Gets the referenced field counterpart given a referencing field.

Definition at line 442 of file qgsrelation.cpp.

◆ resolveReferencingField()

QString QgsRelation::resolveReferencingField ( const QString & referencedField ) const

Gets the referencing field counterpart given a referenced field.

Definition at line 452 of file qgsrelation.cpp.

◆ setId()

void QgsRelation::setId ( const QString & id )

Set an id for this relation.

Definition at line 165 of file qgsrelation.cpp.

◆ setName()

void QgsRelation::setName ( const QString & name )

Set a name for this relation.

Definition at line 173 of file qgsrelation.cpp.

◆ setPolymorphicRelationId()

void QgsRelation::setPolymorphicRelationId ( const QString & polymorphicRelationId )

Sets the parent polymorphic relation id.

Since: QGIS 3.18

Definition at line 521 of file qgsrelation.cpp.

◆ setReferencedLayer()

void QgsRelation::setReferencedLayer ( const QString & id )

Set the referenced (parent) layer id.

This layer will be searched in the registry.

Definition at line 194 of file qgsrelation.cpp.

◆ setReferencingLayer()

void QgsRelation::setReferencingLayer ( const QString & id )

Set the referencing (child) layer id.

This layer will be searched in the registry.

Definition at line 186 of file qgsrelation.cpp.

◆ setStrength()

void QgsRelation::setStrength ( Qgis::RelationshipStrength strength )

Set a strength for this relation.

Definition at line 180 of file qgsrelation.cpp.

◆ strength()

Qgis::RelationshipStrength QgsRelation::strength ( ) const

Returns the relation strength as a string.

Returns: strength

Definition at line 314 of file qgsrelation.cpp.

◆ strengthToDisplayString()

QString QgsRelation::strengthToDisplayString ( Qgis::RelationshipStrength strength )

static

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

Since: QGIS 3.28

Definition at line 564 of file qgsrelation.cpp.

◆ type()

Qgis::RelationshipType QgsRelation::type ( ) const

Returns the type of the relation.

Since: QGIS 3.18

Definition at line 540 of file qgsrelation.cpp.

◆ updateRelationStatus()

void QgsRelation::updateRelationStatus ( )

Updates the validity status of this relation.

Will be called internally whenever a member is changed.

Since: QGIS 3.6

Definition at line 462 of file qgsrelation.cpp.

◆ validationError()

QString QgsRelation::validationError ( ) const

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

Returns an empty string if the relationship isValid().

See also: isValid()

Since: QGIS 3.28

Definition at line 410 of file qgsrelation.cpp.

◆ writeXml()

void QgsRelation::writeXml	(	QDomNode &	node,
		QDomDocument &	doc ) const

Writes a relation to an XML structure.

Used for saving .qgs projects

Parameters

node	The parent node in which the relation will be created
doc	The document in which the relation will be saved

readwrite

Definition at line 54 of file qgsrelation.h.

The documentation for this class was generated from the following files:

/build/qgis-4.3.0+git20260913+389d690bb77+99sid/src/core/qgsrelation.h
/build/qgis-4.3.0+git20260913+389d690bb77+99sid/src/core/qgsrelation.cpp

Classes

Public Member Functions

Static Public Member Functions

Properties

Detailed Description

Constructor & Destructor Documentation

◆ QgsRelation() [1/4]

◆ ~QgsRelation()

◆ QgsRelation() [2/4]

◆ QgsRelation() [3/4]

◆ QgsRelation() [4/4]

Member Function Documentation

◆ addFieldPair() [1/2]

◆ addFieldPair() [2/2]

◆ cardinalityToDisplayString()

◆ createFromXml() [1/2]

◆ createFromXml() [2/2]

◆ fieldPairs()

◆ generateId()

◆ getReferencedFeature()

◆ getReferencedFeatureRequest() [1/2]

◆ getReferencedFeatureRequest() [2/2]

◆ getRelatedFeatures()

◆ getRelatedFeaturesFilter()

◆ getRelatedFeaturesRequest()

◆ hasEqualDefinition()

◆ id()

◆ isValid()

◆ name()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ polymorphicRelation()

◆ polymorphicRelationId()

◆ referencedFields()

◆ referencedLayer()

◆ referencedLayerId()

◆ referencingFields()

◆ referencingFieldsAllowNull()

◆ referencingLayer()

◆ referencingLayerId()

◆ resolveReferencedField()

◆ resolveReferencingField()

◆ setId()

◆ setName()

◆ setPolymorphicRelationId()

◆ setReferencedLayer()

◆ setReferencingLayer()

◆ setStrength()

◆ strength()

◆ strengthToDisplayString()

◆ type()

◆ updateRelationStatus()

◆ validationError()

◆ writeXml()

Property Documentation

◆ id

◆ isValid

◆ name

◆ polymorphicRelation

◆ polymorphicRelationId

◆ referencedFields

◆ referencedLayer

◆ referencedLayerId

◆ referencingFields

◆ referencingLayer

◆ referencingLayerId

◆ strength