En esta página

QSqlRelationalTableModel Class

La clase QSqlRelationalTableModel proporciona un modelo de datos editable para una única tabla de base de datos, con compatibilidad con claves externas. Más información...

Encabezado: #include <QSqlRelationalTableModel>
CMake: find_package(Qt6 REQUIRED COMPONENTS Sql)
target_link_libraries(mytarget PRIVATE Qt6::Sql)
qmake: QT += sql
Heredan: QSqlTableModel

Tipos públicos

enum JoinMode { InnerJoin, LeftJoin }

Funciones públicas

QSqlRelationalTableModel(QObject *parent = nullptr, const QSqlDatabase &db = QSqlDatabase())
virtual ~QSqlRelationalTableModel()
QSqlRelation relation(int column) const
virtual QSqlTableModel *relationModel(int column) const
void setJoinMode(QSqlRelationalTableModel::JoinMode joinMode)
virtual void setRelation(int column, const QSqlRelation &relation)

Funciones públicas reimplementadas

virtual void clear() override
virtual QVariant data(const QModelIndex &index, int role = Qt::DisplayRole) const override
virtual bool removeColumns(int column, int count, const QModelIndex &parent = QModelIndex()) override
virtual bool select() override
virtual bool setData(const QModelIndex &index, const QVariant &value, int role = Qt::EditRole) override
virtual void setTable(const QString &table) override

Ranuras públicas

virtual void revertRow(int row) override

Funciones protegidas reimplementadas

virtual bool insertRowIntoTable(const QSqlRecord &values) override
virtual QString orderByClause() const override
virtual QString selectStatement() const override
virtual bool updateRowInTable(int row, const QSqlRecord &values) override

Descripción detallada

QSqlRelationalTableModel funciona igual qu QSqlTableModel, pero permite establecer columnas como claves externas en otras tablas de la base de datos.

Tabla que muestra la ciudad y el país como valores numéricos de clave externaTabla en la que se muestran las ciudades y los países convertidos en cadenas de texto

La captura de pantalla de la izquierda muestra un QSqlTableModel sencillo en un QTableView. Las claves externas (city y country) no se resuelven en valores legibles para el usuario. La captura de pantalla de la derecha muestra un QSqlRelationalTableModel, con las claves externas resueltas en cadenas de texto legibles para el usuario.

El siguiente fragmento de código muestra cómo se configuró el QSqlRelationalTableModel:

    model->setTable("employee");

    model->setRelation(2, QSqlRelation("city", "id", "name"));
    model->setRelation(3, QSqlRelation("country", "id", "name"));

Las llamadas a la función ` setRelation()` establecen una relación entre dos tablas. La primera llamada especifica que la columna 2 de la tabla ` employee ` es una clave foránea que se asigna al campo ` id ` de la tabla ` city`, y que la vista debe mostrar al usuario el campo ` name ` de ` city`. La segunda llamada hace algo similar con la columna 3.

Si utilizas un QSqlRelationalTableModel de lectura y escritura, probablemente te interese utilizar QSqlRelationalDelegate en la vista. A diferencia del delegado predeterminado, QSqlRelationalDelegate proporciona un cuadro combinado para los campos que son claves externas en otras tablas. Para utilizar la clase, basta con llamar a QAbstractItemView::setItemDelegate() en la vista con una instancia de QSqlRelationalDelegate:

    std::unique_ptr<QTableView> view{new QTableView};
    view->setModel(model);
    view->setItemDelegate(new QSqlRelationalDelegate(view.get()));

El ejemplo «relationaltablemodel» ilustra cómo utilizar QSqlRelationalTableModel junto con QSqlRelationalDelegate para dotar a las tablas de compatibilidad con claves foráneas.

El usuario puede modificar una clave externa en una tabla relacional

Notas:

  • La tabla debe tener declarada una clave primaria.
  • La clave principal de la tabla no puede contener una referencia a otra tabla.
  • Si una tabla relacional contiene claves que hacen referencia a filas inexistentes en la tabla a la que se hace referencia, las filas que contengan las claves no válidas no se mostrarán a través del modelo. El usuario o la base de datos son responsables de mantener la integridad referencial.
  • Si el nombre de la columna de visualización de una relación también se utiliza como nombre de columna en la tabla relacional, o si se utiliza como nombre de columna de visualización en más de una relación, se le asignará un alias. El alias está formado por el nombre de la tabla de la relación, el nombre de la columna de visualización y un identificador único, unidos por un guión bajo (por ejemplo, nombre_tabla_nombre_columna_id). La función ` QSqlRecord::fieldName()` devolverá el nombre de la columna con alias. Todas las apariciones del nombre de columna de visualización duplicado reciben un alias cuando se detecta la duplicación, pero no se aplica ningún alias a los nombres de columna de la tabla principal. La asignación de alias no afecta a ` QSqlRelation`, por lo que ` QSqlRelation::displayColumn()` devolverá el nombre de columna de visualización original.
  • El nombre de la tabla de referencia recibe un alias. El alias es la palabra «relTblAl» seguida del índice de la columna relacionada, unidos por un guión bajo (por ejemplo, relTblAl_2). El alias se puede utilizar para filtrar la tabla (por ejemplo, setFilter("relTblAl_2='Oslo' OR relTblAl_3='USA'")).
  • Al utilizar setData(), el rol debe ser siempre Qt::EditRole, y al utilizar data(), el rol debe ser siempre Qt::DisplayRole.

Véase también QSqlRelation, QSqlRelationalDelegate y Ejemplo de modelo de tabla relacional.

Documentación sobre los tipos de miembro

enum QSqlRelationalTableModel::JoinMode

ConstanteValorDescripción
QSqlRelationalTableModel::InnerJoin0- Modo de unión interna: devuelve filas cuando hay al menos una coincidencia en ambas tablas.
QSqlRelationalTableModel::LeftJoin1- Modo de unión a la izquierda: devuelve todas las filas de la tabla de la izquierda (table_name1), incluso si no hay coincidencias en la tabla de la derecha (table_name2).

Véase también QSqlRelationalTableModel::setJoinMode().

Documentación de funciones de miembro

[explicit] QSqlRelationalTableModel::QSqlRelationalTableModel(QObject *parent = nullptr, const QSqlDatabase &db = QSqlDatabase())

Crea un objeto QSqlRelationalTableModel vacío y establece como elemento padre parent y como conexión a la base de datos db. Si db no es válido, se utilizará la conexión a la base de datos predeterminada.

[virtual noexcept] QSqlRelationalTableModel::~QSqlRelationalTableModel()

Destruye el objeto y libera los recursos asignados.

[override virtual] void QSqlRelationalTableModel::clear()

Reimplementa: QSqlTableModel::clear().

[override virtual] QVariant QSqlRelationalTableModel::data(const QModelIndex &index, int role = Qt::DisplayRole) const

Reimplementa: QSqlTableModel::data(const QModelIndex &index, int role) const.

Véase también setData().

[override virtual protected] bool QSqlRelationalTableModel::insertRowIntoTable(const QSqlRecord &values)

Reimplementa: ` QSqlTableModel::insertRowIntoTable(const QSqlRecord &values)`.

[override virtual protected] QString QSqlRelationalTableModel::orderByClause() const

Reimplementa: ` QSqlTableModel::orderByClause()` const.

QSqlRelation QSqlRelationalTableModel::relation(int column) const

Devuelve la relación de la columna « column », o una relación no válida si no se ha establecido ninguna.

Véase también setRelation() y QSqlRelation::isValid().

[virtual] QSqlTableModel *QSqlRelationalTableModel::relationModel(int column) const

Devuelve un objeto ` QSqlTableModel ` para acceder a la tabla para la que ` column ` es una clave externa, o ` nullptr ` si no existe ninguna relación para el ` column` indicado.

El objeto devuelto es propiedad de ` QSqlRelationalTableModel`.

Véase también setRelation() y relation().

[override virtual] bool QSqlRelationalTableModel::removeColumns(int column, int count, const QModelIndex &parent = QModelIndex())

Reimplementa: ` QSqlTableModel::removeColumns` (int column, int count, const QModelIndex &parent).

[override virtual slot] void QSqlRelationalTableModel::revertRow(int row)

Reimplementa: QSqlTableModel::revertRow(int row).

[override virtual] bool QSqlRelationalTableModel::select()

Reimplementa: QSqlTableModel::select().

[override virtual protected] QString QSqlRelationalTableModel::selectStatement() const

Reimplementa: ` QSqlTableModel::selectStatement()` const.

[override virtual] bool QSqlRelationalTableModel::setData(const QModelIndex &index, const QVariant &value, int role = Qt::EditRole)

Reimplementa: ` QSqlTableModel::setData` (const QModelIndex &index, const QVariant &value, int role).

Establece los datos del campo « role » en el elemento con el « index » especificado en el « value » proporcionado. Dependiendo de la estrategia de edición, el valor puede aplicarse a la base de datos de inmediato o almacenarse en la caché del modelo.

Devuelve ` true ` si se ha podido establecer el valor, o `false` en caso de error (por ejemplo, si ` index ` está fuera de límites).

Para las columnas relacionales, value debe ser el índice, no el valor de visualización. Si se proporciona un índice, este también debe existir en la tabla a la que se hace referencia; de lo contrario, la función devuelve false. Si se pasa un QVariant() en lugar de un índice, el índice se borra.

Véanse también editStrategy(), data(), submit() y revertRow().

void QSqlRelationalTableModel::setJoinMode(QSqlRelationalTableModel::JoinMode joinMode)

Establece la opción SQL « joinMode » para mostrar u ocultar las filas con claves foráneas NULL. En el modo « InnerJoin » (el predeterminado), estas filas no se mostrarán; utiliza el modo « LeftJoin » si deseas mostrarlas.

Véase también « QSqlRelationalTableModel::JoinMode ».

[virtual] void QSqlRelationalTableModel::setRelation(int column, const QSqlRelation &relation)

Supongamos que el índice « column » es un índice externo definido mediante « relation ».

Ejemplo:

    model->setTable("employee");

    model->setRelation(2, QSqlRelation("city", "id", "name"));

La llamada a setRelation() especifica que la columna 2 de la tabla employee es una clave externa que se asigna al campo id de la tabla city, y que la vista debe mostrar al usuario el campo name de city.

Nota: La clave primaria de la tabla no puede contener una relación con otra tabla.

Véase también relation().

[override virtual] void QSqlRelationalTableModel::setTable(const QString &table)

Reimplementa: ` QSqlTableModel::setTable(const QString &tableName)`.

[override virtual protected] bool QSqlRelationalTableModel::updateRowInTable(int row, const QSqlRecord &values)

Reimplementa: QSqlTableModel::updateRowInTable(int row, const QSqlRecord &values).

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.