En esta página

QSqlResult Class

La clase QSqlResult proporciona una interfaz abstracta para acceder a datos de bases de datos SQL específicas. Más información...

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

Funciones públicas

virtual ~QSqlResult()
virtual QVariant handle() const

Tipos protegidos

enum BindingSyntax { PositionalBinding, NamedBinding }

Funciones protegidas

QSqlResult(const QSqlDriver *db)
void addBindValue(const QVariant &val, QSql::ParamType paramType)
int at() const
virtual void bindValue(int index, const QVariant &val, QSql::ParamType paramType)
virtual void bindValue(const QString &placeholder, const QVariant &val, QSql::ParamType paramType)
QSql::ParamType bindValueType(int index) const
QSql::ParamType bindValueType(const QString &placeholder) const
QSqlResult::BindingSyntax bindingSyntax() const
QVariant boundValue(int index) const
QVariant boundValue(const QString &placeholder) const
int boundValueCount() const
QString boundValueName(int index) const
QStringList boundValueNames() const
QVariantList boundValues() const
QVariantList &boundValues()
void clear()
virtual QVariant data(int index) = 0
const QSqlDriver *driver() const
virtual bool exec()
QString executedQuery() const
virtual bool fetch(int index) = 0
virtual bool fetchFirst() = 0
virtual bool fetchLast() = 0
virtual bool fetchNext()
virtual bool fetchPrevious()
bool hasOutValues() const
bool isActive() const
bool isForwardOnly() const
virtual bool isNull(int index) = 0
bool isSelect() const
bool isValid() const
QSqlError lastError() const
virtual QVariant lastInsertId() const
QString lastQuery() const
virtual int numRowsAffected() = 0
virtual bool prepare(const QString &query)
virtual QSqlRecord record() const
virtual bool reset(const QString &query) = 0
void resetBindCount()
virtual bool savePrepare(const QString &query)
virtual void setActive(bool active)
virtual void setAt(int index)
virtual void setForwardOnly(bool forward)
virtual void setLastError(const QSqlError &error)
virtual void setQuery(const QString &query)
virtual void setSelect(bool select)
virtual int size() = 0

Descripción detallada

Normalmente, se utilizaría ` QSqlQuery ` en lugar de `QSqlResult`, ya que ` QSqlQuery ` proporciona un envoltorio genérico para las implementaciones específicas de cada base de datos de `QSqlResult`.

Si está implementando su propio controlador SQL (mediante la creación de una subclase de ` QSqlDriver`), deberá proporcionar su propia subclase de `QSqlResult` que implemente todas las funciones virtuales puras y otras funciones virtuales que necesite.

Véase también QSqlDriver.

Documentación sobre los tipos de miembro

enum QSqlResult::BindingSyntax

Este tipo de enumeración especifica las diferentes sintaxis para indicar marcadores de posición en consultas preparadas.

ConstanteValorDescripción
QSqlResult::PositionalBinding0Utiliza la sintaxis posicional al estilo ODBC, con «?» como marcadores de posición.
QSqlResult::NamedBinding1Utiliza la sintaxis al estilo de Oracle con marcadores de posición con nombre (p. ej., «:id»)

Véase también bindingSyntax().

Documentación de funciones de miembro

[explicit protected] QSqlResult::QSqlResult(const QSqlDriver *db)

Crea un objeto `QSqlResult` utilizando el controlador de base de datos ` db`. El objeto se inicializa en estado inactivo.

Véase también isActive() y driver().

[virtual noexcept] QSqlResult::~QSqlResult()

Destruye el objeto y libera los recursos asignados.

[protected] void QSqlResult::addBindValue(const QVariant &val, QSql::ParamType paramType)

Asigna el valor val, de tipo paramType, a la siguiente posición disponible en el registro (fila) actual.

Véase también bindValue().

[protected] int QSqlResult::at() const

Devuelve la posición actual (a partir de cero) de la fila en el resultado. Puede devolver los valores especiales « QSql::BeforeFirstRow » o « QSql::AfterLastRow ».

Véase también setAt() y isValid().

[virtual protected] void QSqlResult::bindValue(int index, const QVariant &val, QSql::ParamType paramType)

Asigna el valor val, de tipo paramType, a la posición index del registro actual (fila).

Véase también addBindValue().

[virtual protected] void QSqlResult::bindValue(const QString &placeholder, const QVariant &val, QSql::ParamType paramType)

Asigna el valor val, de tipo paramType, al nombre placeholder en el registro (fila) actual.

Nota: La asignación de un marcador de posición no definido dará lugar a un comportamiento indefinido.

Esta es una función sobrecargada.

Véase también QSqlQuery::bindValue().

[protected] QSql::ParamType QSqlResult::bindValueType(int index) const

Devuelve el tipo del parámetro correspondiente al valor asociado a la posición index.

Véase también ` boundValue()`.

[protected] QSql::ParamType QSqlResult::bindValueType(const QString &placeholder) const

Devuelve el tipo del parámetro correspondiente al valor asociado al nombre de « placeholder » indicado.

Esta es una función sobrecargada.

[protected] QSqlResult::BindingSyntax QSqlResult::bindingSyntax() const

Devuelve la sintaxis de enlace utilizada por las consultas preparadas.

[protected] QVariant QSqlResult::boundValue(int index) const

Devuelve el valor asociado a la posición « index » en el registro (fila) actual.

Véase también bindValue() y boundValues().

[protected] QVariant QSqlResult::boundValue(const QString &placeholder) const

Devuelve el valor asociado al nombre « placeholder » indicado en el registro (fila) actual.

Esta es una función sobrecargada.

Véase también bindValueType().

[protected] int QSqlResult::boundValueCount() const

Devuelve el número de valores vinculados en el resultado.

Véase también boundValues().

[protected] QString QSqlResult::boundValueName(int index) const

Devuelve el nombre del valor vinculado en la posición index del registro (fila) actual.

Véase también ` boundValue()` y ` boundValueNames()`.

[protected] QStringList QSqlResult::boundValueNames() const

Devuelve los nombres de todos los valores vinculados.

Véase también boundValue() y boundValueName().

[protected] QVariantList QSqlResult::boundValues() const

Devuelve una lista de los valores vinculados del resultado correspondientes al registro (fila) actual.

Véase también boundValueCount().

[protected] QVariantList &QSqlResult::boundValues()

Devuelve una referencia mutable a la lista de valores asociados del resultado para el registro (fila) actual.

Esta es una función sobrecargada.

Véase también ` boundValueCount()`.

[protected] void QSqlResult::clear()

Borra todo el conjunto de resultados y libera los recursos asociados.

[pure virtual protected] QVariant QSqlResult::data(int index)

Devuelve los datos del campo index de la fila actual como un objeto de tipo ` QVariant`. Esta función solo se invoca si el resultado se encuentra en estado activo, está situado en un registro válido y index es un valor no negativo. Las clases derivadas deben reimplementar esta función y devolver el valor del campo index, o bien `QVariant()` si no se puede determinar.

[protected] const QSqlDriver *QSqlResult::driver() const

Devuelve el controlador asociado al resultado. Se trata del objeto que se pasó al constructor.

[virtual protected] bool QSqlResult::exec()

Ejecuta la consulta y devuelve «true» si se realiza correctamente; en caso contrario, devuelve «false».

Véase también prepare().

[protected] QString QSqlResult::executedQuery() const

Devuelve la consulta que se ha ejecutado realmente. Esta puede diferir de la consulta que se pasó, por ejemplo, si se utilizaron valores vinculados con una consulta preparada y la base de datos subyacente no admite consultas preparadas.

Véase también exec() y setQuery().

[pure virtual protected] bool QSqlResult::fetch(int index)

Coloca el resultado en una fila arbitraria (contando desde cero) index.

Esta función solo se invoca si el resultado se encuentra en estado activo. Las clases derivadas deben reimplementar esta función y colocar el resultado en la fila index, además de llamar a setAt() con un valor adecuado. Devuelve «true» para indicar éxito o «false» para indicar fallo.

Véase también isActive(), fetchFirst(), fetchLast(), fetchNext() y fetchPrevious().

[pure virtual protected] bool QSqlResult::fetchFirst()

Coloca el resultado en el primer registro (fila 0) de los resultados.

Esta función solo se invoca si el resultado se encuentra en estado activo. Las clases derivadas deben reimplementar esta función, situar el resultado en el primer registro e invocar setAt() con un valor adecuado. Devuelve «true» para indicar que la operación se ha realizado correctamente, o «false» para indicar que ha fallado.

Véanse también fetch() y fetchLast().

[pure virtual protected] bool QSqlResult::fetchLast()

Coloca el resultado en el último registro (última fila) de los resultados.

Esta función solo se invoca si el resultado se encuentra en estado activo. Las clases derivadas deben reimplementar esta función y situar el resultado en el último registro, además de llamar a setAt() con un valor adecuado. Devuelve «true» para indicar que la operación se ha realizado con éxito, o «false» para indicar que ha fallado.

Véanse también ` fetch()` y ` fetchFirst()`.

[virtual protected] bool QSqlResult::fetchNext()

Coloca el resultado en el siguiente registro (fila) disponible del conjunto de resultados.

Esta función solo se invoca si el resultado se encuentra en estado activo. La implementación por defecto invoca a ` fetch()` con el índice siguiente. Las clases derivadas pueden reimplementar esta función y situar el resultado en el siguiente registro de otra forma, e invocar a ` setAt()` con un valor adecuado. Devuelve `true` para indicar éxito, o `false` para indicar fallo.

Véanse también fetch() y fetchPrevious().

[virtual protected] bool QSqlResult::fetchPrevious()

Coloca el resultado en el registro (fila) anterior del conjunto de resultados.

Esta función solo se invoca si el resultado se encuentra en estado activo. La implementación por defecto invoca a ` fetch()` con el índice anterior. Las clases derivadas pueden reimplementar esta función y situar el resultado en el registro siguiente de otra forma, e invocar a ` setAt()` con un valor adecuado. Devuelve `true` para indicar que la operación se ha realizado con éxito, o `false` para indicar que ha fallado.

[virtual] QVariant QSqlResult::handle() const

Devuelve el identificador de base de datos de bajo nivel para este conjunto de resultados, envuelto en un objeto ` QVariant ` o, si no existe ningún identificador, en un objeto ` QVariant ` no válido.

Advertencia: Utiliza esto con mucho cuidado y solo si sabes lo que estás haciendo.

Advertencia: El identificador devuelto aquí puede convertirse en un puntero obsoleto si se modifica el resultado (por ejemplo, si lo borras).

Advertencia: El identificador puede ser NULL si el resultado aún no se ha ejecutado.

Advertencia: PostgreSQL : en modo «solo avance», el identificador de QSqlResult puede cambiar tras llamar a fetch(), fetchFirst(), fetchLast(), fetchNext(), fetchPrevious() o nextResult().

El identificador devuelto aquí depende de la base de datos; debes consultar el nombre del tipo de la variante antes de acceder a ella.

Este ejemplo recupera el identificador de un resultado de SQLite:

QSqlDatabase db = QSqlDatabase::database("sales");
QSqlQuery query("SELECT NAME, DOB FROM EMPLOYEES", db);

QVariant v = query.result()->handle();
if (v.isValid() && qstrcmp(v.typeName(), "sqlite3_stmt*") == 0) {
    // v.data() returns a pointer to the handle
    sqlite3_stmt *handle = *static_cast<sqlite3_stmt **>(v.data());
    if (handle) {
        // ...
    }
}

Este fragmento de código devuelve el identificador para PostgreSQL o MySQL:

if (qstrcmp(v.typeName(), "PGresult*") == 0) {
    PGresult *handle = *static_cast<PGresult **>(v.data());
    if (handle) {
        // ...
        }
}

if (qstrcmp(v.typeName(), "MYSQL_STMT*") == 0) {
    MYSQL_STMT *handle = *static_cast<MYSQL_STMT **>(v.data());
    if (handle) {
        // ...
        }
    }

Véase también QSqlDriver::handle().

[protected] bool QSqlResult::hasOutValues() const

Devuelve ` true ` si al menos uno de los valores vinculados de la consulta es ` QSql::Out ` o ` QSql::InOut`; en caso contrario, devuelve ` false`.

Véase también bindValueType().

[protected] bool QSqlResult::isActive() const

Devuelve « true » si el resultado contiene registros que recuperar; en caso contrario, devuelve « false ».

[protected] bool QSqlResult::isForwardOnly() const

Devuelve « true » si solo se puede desplazar hacia adelante por el conjunto de resultados; en caso contrario, devuelve « false ».

Véase también setForwardOnly().

[pure virtual protected] bool QSqlResult::isNull(int index)

Devuelve « true » si el campo situado en la posición « index » de la fila actual es nulo; en caso contrario, devuelve « false ».

[protected] bool QSqlResult::isSelect() const

Devuelve ` true ` si el resultado actual procede de una instrucción ` SELECT `; en caso contrario, devuelve ` false`.

Véase también setSelect().

[protected] bool QSqlResult::isValid() const

Devuelve ` true ` si el resultado se encuentra en un registro válido (es decir, el resultado no se encuentra antes del primer registro ni después del último); en caso contrario, devuelve ` false`.

Véase también at().

[protected] QSqlError QSqlResult::lastError() const

Devuelve el último error asociado al resultado.

Véase también ` setLastError()`.

[virtual protected] QVariant QSqlResult::lastInsertId() const

Devuelve el ID del objeto de la fila insertada más recientemente, si la base de datos lo admite. Se devolverá un objeto ` QVariant ` no válido si la consulta no ha insertado ningún valor o si la base de datos no devuelve el ID. Si la inserción ha afectado a más de una fila, el comportamiento es indefinido.

Ten en cuenta que, en el caso de las bases de datos Oracle, se devolverá el ROWID de la fila, mientras que en las bases de datos MySQL se devolverá el campo de autoincremento de la fila.

Véase también QSqlDriver::hasFeature().

[protected] QString QSqlResult::lastQuery() const

Devuelve el texto de la consulta SQL actual o una cadena vacía si no hay ninguna.

Véase también setQuery().

[pure virtual protected] int QSqlResult::numRowsAffected()

Devuelve el número de filas afectadas por la última consulta ejecutada, o -1 si no se puede determinar o si la consulta es una instrucción « SELECT ».

Véase también ` size()`.

[virtual protected] bool QSqlResult::prepare(const QString &query)

Prepara la consulta « query » dada para su ejecución; normalmente, la consulta utilizará marcadores de posición para que pueda ejecutarse repetidamente. Devuelve «true» si la consulta se prepara correctamente; en caso contrario, devuelve « false ».

Véase también exec().

[virtual protected] QSqlRecord QSqlResult::record() const

Devuelve el registro actual si la consulta está activa; en caso contrario, devuelve un QSqlRecord vacío.

La implementación por defecto siempre devuelve un ` QSqlRecord` vacío.

Véase también isActive().

[pure virtual protected] bool QSqlResult::reset(const QString &query)

Establece el resultado para que utilice la instrucción SQL « query » en las recuperaciones de datos posteriores.

Las clases derivadas deben reimplementar esta función y aplicar la instrucción ` query ` a la base de datos. Esta función solo se invoca después de que el resultado se haya establecido en un estado inactivo y se haya situado antes del primer registro del nuevo resultado. Las clases derivadas deben devolver `true` si la consulta se ha realizado correctamente y está lista para su uso, o `false` en caso contrario.

Véase también setQuery().

[protected] void QSqlResult::resetBindCount()

Restablece el número de parámetros de enlace.

[virtual protected] bool QSqlResult::savePrepare(const QString &query)

Prepara la consulta « query » indicada, utilizando la funcionalidad de la base de datos subyacente siempre que sea posible. Devuelve « true » si la consulta se prepara correctamente; en caso contrario, devuelve « false ».

Nota: Este método debería haberse llamado «safePrepare()».

Véase también prepare().

[virtual protected] void QSqlResult::setActive(bool active)

Esta función se proporciona para que las clases derivadas puedan establecer el estado activo interno en « active ».

Véase también ` isActive()`.

[virtual protected] void QSqlResult::setAt(int index)

Esta función se proporciona para que las clases derivadas puedan establecer la posición interna (contada a partir de cero) de la fila en index.

Véase también ` at()`.

[virtual protected] void QSqlResult::setForwardOnly(bool forward)

Establece el modo «solo avance» en forward. Si forward es verdadero, solo se permite fetchNext() para navegar por los resultados. El modo «solo avance» requiere mucha menos memoria, ya que no es necesario almacenar los resultados en caché. Por defecto, esta función está desactivada.

Establecer «forward only» en «false» es una sugerencia para el motor de la base de datos, que es quien tiene la última palabra sobre si un conjunto de resultados es de avance único o se puede desplazar. isForwardOnly() siempre devolverá el estado correcto del conjunto de resultados.

Nota: Llamar a `setForwardOnly` tras la ejecución de la consulta dará lugar, en el mejor de los casos, a resultados inesperados y, en el peor, a fallos del sistema.

Nota: Para asegurarse de que la consulta de «solo avance» se ha completado correctamente, la aplicación debe comprobar si hay algún error en lastError() no solo tras ejecutar la consulta, sino también tras navegar por los resultados de la misma.

Advertencia: PostgreSQL : Mientras se navega por los resultados de la consulta en modo «solo hacia adelante», no se debe ejecutar ningún otro comando SQL en la misma conexión a la base de datos. Esto provocará la pérdida de los resultados de la consulta.

Véase también isForwardOnly(), fetchNext() y QSqlQuery::setForwardOnly().

[virtual protected] void QSqlResult::setLastError(const QSqlError &error)

Esta función se proporciona para que las clases derivadas puedan establecer el último error en error.

Véase también ` lastError()`.

[virtual protected] void QSqlResult::setQuery(const QString &query)

Establece la consulta actual para el resultado en query. Debes llamar a reset() para ejecutar la consulta en la base de datos.

Véase también ` reset()` y ` lastQuery()`.

[virtual protected] void QSqlResult::setSelect(bool select)

Esta función se proporciona a las clases derivadas para indicar si la instrucción actual es o no una instrucción SQL de tipo « SELECT ». El parámetro ` select ` debe ser `true` si la instrucción es de tipo « SELECT »; en caso contrario, debe ser `false`.

Véase también isSelect().

[pure virtual protected] int QSqlResult::size()

Devuelve el tamaño del resultado de « SELECT », o -1 si no se puede determinar o si la consulta no es una instrucción « SELECT ».

Véase también numRowsAffected().

© 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.