En esta página

QSqlQuery Class

La clase QSqlQuery permite ejecutar y manipular sentencias SQL. Más información ...

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

Tipos públicos

enum BatchExecutionMode { ValuesAsRows, ValuesAsColumns }

Propiedades

Funciones públicas

QSqlQuery(QSqlResult *result)
QSqlQuery(const QSqlDatabase &db)
QSqlQuery(const QString &query = QString(), const QSqlDatabase &db = QSqlDatabase())
(since 6.2) QSqlQuery(QSqlQuery &&other)
~QSqlQuery()
void addBindValue(const QVariant &val, QSql::ParamType paramType = QSql::In)
int at() const
void bindValue(const QString &placeholder, const QVariant &val, QSql::ParamType paramType = QSql::In)
void bindValue(int pos, const QVariant &val, QSql::ParamType paramType = QSql::In)
QVariant boundValue(const QString &placeholder) const
QVariant boundValue(int pos) const
(since 6.6) QString boundValueName(int pos) const
(since 6.6) QStringList boundValueNames() const
(since 6.0) QVariantList boundValues() const
void clear()
const QSqlDriver *driver() const
bool exec()
bool exec(const QString &query)
bool execBatch(QSqlQuery::BatchExecutionMode mode = ValuesAsRows)
QString executedQuery() const
void finish()
bool first()
bool isActive() const
bool isForwardOnly() const
bool isNull(int field) const
bool isNull(QAnyStringView name) const
(since 6.7) bool isPositionalBindingEnabled() const
bool isSelect() const
bool isValid() const
bool last()
QSqlError lastError() const
QVariant lastInsertId() const
QString lastQuery() const
bool next()
bool nextResult()
int numRowsAffected() const
QSql::NumericalPrecisionPolicy numericalPrecisionPolicy() const
bool prepare(const QString &query)
bool previous()
QSqlRecord record() const
const QSqlResult *result() const
bool seek(int index, bool relative = false)
void setForwardOnly(bool forward)
void setNumericalPrecisionPolicy(QSql::NumericalPrecisionPolicy precisionPolicy)
(since 6.7) void setPositionalBindingEnabled(bool enable)
int size() const
(since 6.2) void swap(QSqlQuery &other)
QVariant value(int index) const
QVariant value(QAnyStringView name) const
(since 6.2) QSqlQuery &operator=(QSqlQuery &&other)

Descripción detallada

QSqlQuery encapsula la funcionalidad necesaria para crear, navegar y recuperar datos de consultas SQL que se ejecutan en un QSqlDatabase. Se puede utilizar para ejecutar sentencias DML (lenguaje de manipulación de datos), como « SELECT », « INSERT », « UPDATE » y « DELETE », así como sentencias DDL (lenguaje de definición de datos), como « CREATE » y « TABLE ». También se puede utilizar para ejecutar comandos específicos de la base de datos que no forman parte del SQL estándar (por ejemplo, « SET DATESTYLE=ISO » para PostgreSQL).

Las sentencias SQL ejecutadas con éxito establecen el estado de la consulta en «activo», de modo que isActive() devuelve true. De lo contrario, el estado de la consulta se establece en «inactivo». En cualquier caso, al ejecutar una nueva sentencia SQL, la consulta se sitúa en un registro no válido. Es necesario navegar por una consulta activa hasta un registro válido (de modo que isValid() devuelva true) antes de poder recuperar valores.

En algunas bases de datos, si existe una consulta activa que sea una instrucción « SELECT » al llamar a ` commit()` o ` rollback()`, la confirmación o la reversión fallarán. Consulte ` isActive()` para obtener más detalles.

La navegación por los registros se realiza con las siguientes funciones:

Estas funciones permiten al programador desplazarse hacia delante, hacia atrás o de forma arbitraria por los registros devueltos por la consulta. Si solo necesitas desplazarte hacia delante por los resultados (por ejemplo, utilizando ` next()`), puedes utilizar ` setForwardOnly()`, lo que ahorrará una cantidad significativa de sobrecarga de memoria y mejorará el rendimiento en algunas bases de datos. Una vez que una consulta activa se ha situado en un registro válido, los datos se pueden recuperar utilizando value(). Todos los datos se transfieren desde el backend SQL mediante QVariants.

Por ejemplo:

    QSqlQuery query("SELECT country FROM artist");
    while (query.next()) {
        QString country = query.value(0).toString();
        doSomething(country);
    }

Para acceder a los datos devueltos por una consulta, utiliza `value(int)`. Se accede a cada campo de los datos devueltos por una instrucción ` SELECT ` pasando la posición del campo en la instrucción, empezando por 0. Por este motivo, no se recomienda utilizar consultas ` SELECT * `, ya que el orden de los campos devueltos es indeterminado.

En aras de la eficiencia, no existen funciones para acceder a un campo por su nombre (a menos que se utilicen consultas preparadas con nombres, tal y como se explica a continuación). Para convertir un nombre de campo en un índice, utiliza ` record()`. Por ejemplo, `indexOf()`, como se muestra a continuación:

    QSqlQuery query("SELECT * FROM artist");
    int fieldNo = query.record().indexOf("country");
    while (query.next()) {
        QString country = query.value(fieldNo).toString();
        doSomething(country);
    }

QSqlQuery admite la ejecución de consultas preparadas y la vinculación de valores de parámetros a marcadores de posición. Algunas bases de datos no admiten estas características, por lo que, en esos casos, Qt emula la funcionalidad necesaria. Por ejemplo, los controladores de Oracle y ODBC cuentan con soporte adecuado para consultas preparadas, y Qt lo utiliza; pero para las bases de datos que no disponen de este soporte, Qt implementa la característica por sí mismo, por ejemplo, sustituyendo los marcadores de posición por valores reales cuando se ejecuta una consulta. Utiliza ` numRowsAffected()` para averiguar cuántas filas se vieron afectadas por una consulta no `SELECT `, y ` size()` para averiguar cuántas se recuperaron mediante una consulta ` SELECT`.

Las bases de datos Oracle identifican los marcadores de posición utilizando una sintaxis de dos puntos y nombre, p. ej., :name. ODBC utiliza simplemente caracteres ?. Qt admite ambas sintaxis, con la restricción de que no se pueden mezclar en la misma consulta.

Se pueden recuperar los valores de todos los campos en una sola variable utilizando ` boundValues()`.

Nota: No todas las operaciones SQL admiten la vinculación de valores. Consulta la documentación de tu sistema de base de datos para comprobar su disponibilidad.

Enfoques para la vinculación de valores

A continuación presentamos el mismo ejemplo utilizando cada uno de los cuatro métodos diferentes de enlace de valores, así como un ejemplo de enlace de valores a un procedimiento almacenado.

Enlace con nombre mediante marcadores de posición con nombre:

    QSqlQuery query;
    query.prepare("INSERT INTO person (id, forename, surname) "
                  "VALUES (:id, :forename, :surname)");
    query.bindValue(":id", 1001);
    query.bindValue(":forename", "Bart");
    query.bindValue(":surname", "Simpson");
    query.exec();

Enlace posicional con marcadores de posición con nombre:

    QSqlQuery query;
    query.prepare("INSERT INTO person (id, forename, surname) "
                  "VALUES (:id, :forename, :surname)");
    query.bindValue(0, 1001);
    query.bindValue(1, "Bart");
    query.bindValue(2, "Simpson");
    query.exec();

Asignación de valores mediante marcadores de posición posicionales (versión 1):

    QSqlQuery query;
    query.prepare("INSERT INTO person (id, forename, surname) "
                  "VALUES (?, ?, ?)");
    query.bindValue(0, 1001);
    query.bindValue(1, "Bart");
    query.bindValue(2, "Simpson");
    query.exec();

Asignación de valores mediante marcadores de posición (versión 2):

    QSqlQuery query;
    query.prepare("INSERT INTO person (id, forename, surname) "
                  "VALUES (?, ?, ?)");
    query.addBindValue(1001);
    query.addBindValue("Bart");
    query.addBindValue("Simpson");
    query.exec();

Asignación de valores a un procedimiento almacenado:

Este código llama a un procedimiento almacenado llamado « AsciiToInt() », le pasa un carácter a través de su parámetro «in» y recoge el resultado en el parámetro «out».

    QSqlQuery query;
    query.prepare("CALL AsciiToInt(?, ?)");
    query.bindValue(0, "A");
    query.bindValue(1, 0, QSql::Out);
    query.exec();
    int i = query.boundValue(1).toInt(); // i is 65

Ten en cuenta que los parámetros no vinculados conservarán sus valores.

Los procedimientos almacenados que utilizan la instrucción «return» para devolver valores, o que devuelven varios conjuntos de resultados, no son totalmente compatibles. Para obtener más detalles, consulte «Controladores de bases de datos SQL».

Advertencia: Debe cargar el controlador SQL y abrir la conexión antes de crear un objeto `QSqlQuery`. Además, la conexión debe permanecer abierta mientras exista la consulta; de lo contrario, el comportamiento de `QSqlQuery` es indefinido.

Véase también QSqlDatabase, QSqlQueryModel, QSqlTableModel y QVariant.

Documentación sobre los tipos de miembros

enum QSqlQuery::BatchExecutionMode

ConstanteValorDescripción
QSqlQuery::ValuesAsRows0- Actualiza varias filas. Trata cada entrada de un ` QVariantList ` como un valor para actualizar la siguiente fila.
QSqlQuery::ValuesAsColumns1- Actualiza una sola fila. Trata cada entrada de un ` QVariantList ` como un único valor de tipo matriz.

Documentación de la propiedad

[since 6.8] forwardOnly : bool

Esta propiedad establece el modo «solo avance». Si « forward » es «true», solo se permiten « next()» y « seek()» con valores positivos para navegar por los resultados.

El modo «solo hacia adelante» puede resultar (dependiendo del controlador) más eficiente en cuanto al uso de la memoria, ya que no es necesario almacenar los resultados en caché. También mejorará el rendimiento en algunas bases de datos. Para que esto sea así, debes llamar a ` setForwardOnly() ` antes de que se prepare o se ejecute la consulta. Ten en cuenta que el constructor que toma una consulta y una base de datos puede ejecutar la consulta.

El modo «solo avance» está desactivado por defecto.

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

Nota: Llamar a setForwardOnly después de 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ía la pérdida de los resultados de la consulta.

Esta enumeración se introdujo en Qt 6.8.

Funciones de acceso:

bool isForwardOnly() const
void setForwardOnly(bool forward)

Véase también ` next()` y ` seek()`.

[since 6.8] numericalPrecisionPolicy : QSql::NumericalPrecisionPolicy

Indica al controlador de la base de datos que devuelva valores numéricos con la precisión especificada por ` precisionPolicy`.

El controlador de Oracle, por ejemplo, puede recuperar valores numéricos como cadenas para evitar la pérdida de precisión. Si la alta precisión no es importante, utiliza este método para aumentar la velocidad de ejecución al evitar las conversiones a cadenas.

Nota: Los controladores que no admitan la obtención de valores numéricos con baja precisión ignorarán la política de precisión. Puede utilizar QSqlDriver::hasFeature() para averiguar si un controlador admite esta característica.

Nota: Establecer la política de precisión no afecta a la consulta actualmente activa. Llame a exec(QString) o a prepare() para activar la política.

Esta enumeración se introdujo en Qt 6.8.

Funciones de acceso:

QSql::NumericalPrecisionPolicy numericalPrecisionPolicy() const
void setNumericalPrecisionPolicy(QSql::NumericalPrecisionPolicy precisionPolicy)

Véase también QSql::NumericalPrecisionPolicy, QSqlDriver::numericalPrecisionPolicy y QSqlDatabase::numericalPrecisionPolicy.

[since 6.8] positionalBindingEnabled : bool

Esta propiedad activa o desactiva el enlace posicional binding para esta consulta, en función de enable (el valor por defecto es true). Desactivar los enlaces posicionales resulta útil si la propia consulta contiene un «?» que no debe tratarse como un parámetro de enlace posicional, sino, por ejemplo, como un operador JSON para una base de datos PostgreSQL.

Esta propiedad no tendrá ningún efecto cuando la base de datos admita de forma nativa los parámetros de enlace posicional con signos de interrogación (véase también QSqlDriver::PositionalPlaceholders).

Esta enumeración se introdujo en Qt 6.8.

Funciones de acceso:

Documentación de las funciones miembro

[explicit] QSqlQuery::QSqlQuery(QSqlResult *result)

Crea un objeto QSqlQuery que utiliza el controlador de base de datos « QSqlResult » ( result ) para comunicarse con una base de datos.

[explicit] QSqlQuery::QSqlQuery(const QSqlDatabase &db)

Crea un objeto QSqlQuery utilizando la base de datos db. Si db no es válido, se utilizará la base de datos predeterminada de la aplicación.

Véase también QSqlDatabase.

[explicit] QSqlQuery::QSqlQuery(const QString &query = QString(), const QSqlDatabase &db = QSqlDatabase())

Crea un objeto QSqlQuery utilizando la consulta SQL query y la base de datos db. Si no se especifica db, o si este no es válido, se utilizará la base de datos predeterminada de la aplicación. Si query no es una cadena vacía, se ejecutará.

Véase también QSqlDatabase.

[noexcept, since 6.2] QSqlQuery::QSqlQuery(QSqlQuery &&other)

Crea un objeto `QSqlQuery` a partir de ` other`.

Esta función se introdujo en Qt 6.2.

[noexcept] QSqlQuery::~QSqlQuery()

Destruye el objeto y libera los recursos asignados.

void QSqlQuery::addBindValue(const QVariant &val, QSql::ParamType paramType = QSql::In)

Añade el valor val a la lista de valores cuando se utiliza el enlace posicional de valores. El orden de las llamadas a addBindValue() determina a qué marcador de posición se enlazará un valor en la consulta preparada. Si paramType es QSql::Out o QSql::InOut, el marcador de posición se sobrescribirá con datos de la base de datos tras la llamada a exec().

Para vincular un valor NULL, utiliza un marcador de posición nulo QVariant; por ejemplo, utiliza QVariant(QMetaType::fromType<QString>()) si vas a vincular una cadena.

Véase también bindValue(), prepare(), exec(), boundValue() y boundValues().

int QSqlQuery::at() const

Devuelve la posición interna actual de la consulta. El primer registro se encuentra en la posición cero. Si la posición no es válida, la función devuelve « QSql::BeforeFirstRow » o « QSql::AfterLastRow », que son valores negativos especiales.

Véase también previous(), next(), first(), last(), seek(), isActive() y isValid().

void QSqlQuery::bindValue(const QString &placeholder, const QVariant &val, QSql::ParamType paramType = QSql::In)

Configura el marcador de posición placeholder para que se vincule al valor val en la instrucción preparada. Ten en cuenta que debe incluirse el marcador del marcador de posición (por ejemplo, :) al especificar el nombre del marcador de posición. Si paramType es QSql::Out o QSql::InOut, el marcador de posición se sobrescribirá con datos de la base de datos tras la llamada a exec(). En este caso, debe preasignarse espacio suficiente para almacenar el resultado.

Para vincular un valor NULL, utiliza un valor nulo QVariant; por ejemplo, utiliza QVariant(QMetaType::fromType<QString>()) si vas a vincular una cadena.

Véase también addBindValue(), prepare(), exec(), boundValue() y boundValues().

void QSqlQuery::bindValue(int pos, const QVariant &val, QSql::ParamType paramType = QSql::In)

Establece el marcador de posición en la posición pos para que se vincule al valor val en la instrucción preparada. La numeración de los campos comienza en 0. Si paramType es QSql::Out o QSql::InOut, el marcador de posición se sobrescribirá con datos de la base de datos tras la llamada a exec().

QVariant QSqlQuery::boundValue(const QString &placeholder) const

Devuelve el valor correspondiente a placeholder.

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

QVariant QSqlQuery::boundValue(int pos) const

Devuelve el valor correspondiente al marcador de posición situado en la posición pos.

Véase también boundValues().

[since 6.6] QString QSqlQuery::boundValueName(int pos) const

Devuelve el nombre del valor vinculado en la posición pos.

El orden de la lista corresponde al orden de enlace, independientemente de si se utiliza un enlace por nombre o por posición.

Esta función se introdujo en Qt 6.6.

Véase también boundValueNames().

[since 6.6] QStringList QSqlQuery::boundValueNames() const

Devuelve los nombres de todos los valores vinculados.

El orden de la lista sigue el orden de enlace, independientemente de si se utiliza un enlace por nombre o por posición.

Esta función se introdujo en Qt 6.6.

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

[since 6.0] QVariantList QSqlQuery::boundValues() const

Devuelve una lista de valores vinculados.

El orden de la lista corresponde al orden de vinculación, independientemente de si se utiliza vinculación por nombre o por posición.

Los valores vinculados pueden examinarse de la siguiente manera:

   const QVariantList list = query.boundValues();
    for (qsizetype i = 0; i < list.size();++i)
        qDebug() << i << ":" << list.at(i).toString();

Esta función se introdujo en Qt 6.0.

Véase también boundValue(), bindValue(), addBindValue() y boundValueNames().

void QSqlQuery::clear()

Borra el conjunto de resultados y libera los recursos que haya ocupado la consulta. Establece el estado de la consulta como inactivo. Es poco probable, por no decir imposible, que tengas que llamar a esta función.

const QSqlDriver *QSqlQuery::driver() const

Devuelve el controlador de base de datos asociado a la consulta.

bool QSqlQuery::exec()

Ejecuta una consulta SQL preparada previamente. Devuelve ` true ` si la consulta se ha ejecutado correctamente; en caso contrario, devuelve ` false`.

Ten en cuenta que el último error de esta consulta se restablece al llamar a exec().

Véase también prepare(), bindValue(), addBindValue(), boundValue() y boundValues().

bool QSqlQuery::exec(const QString &query)

Ejecuta la instrucción SQL de query. Devuelve true y establece el estado de la consulta en active si la consulta se ha realizado correctamente; en caso contrario, devuelve false. La cadena query debe utilizar la sintaxis adecuada para la base de datos SQL que se está consultando (por ejemplo, SQL estándar).

Una vez ejecutada la consulta, el cursor se sitúa en un registro no válido y es necesario desplazarse hasta un registro válido antes de poder recuperar los valores de los datos (por ejemplo, utilizando next()).

Ten en cuenta que el último error de esta consulta se restablece al llamar a exec().

En el caso de SQLite, la cadena de consulta solo puede contener una instrucción cada vez. Si se proporciona más de una instrucción, la función devuelve ` false`.

Ejemplo:

    QSqlQuery query;
    query.exec("INSERT INTO employee (id, name, salary) "
               "VALUES (1001, 'Thad Beaumont', 65000)");

Véase también isActive(), isValid(), next(), previous(), first(), last() y seek().

bool QSqlQuery::execBatch(QSqlQuery::BatchExecutionMode mode = ValuesAsRows)

Ejecuta una consulta SQL preparada previamente en un lote. Todos los parámetros vinculados deben ser listas de variantes. Si la base de datos no admite ejecuciones por lotes, el controlador las simulará mediante llamadas convencionales a ` exec()`.

Devuelve ` true ` si la consulta se ejecuta correctamente; en caso contrario, devuelve ` false`.

Ejemplo:

QSqlQuery q;
q.prepare("insert into myTable values (?, ?)");

QVariantList ints;
ints << 1 << 2 << 3 << 4;
q.addBindValue(ints);

QVariantList nombres;
nombres << "Harald" << "Boris" << "Trond" << QVariant(QMetaType::fromType<QString>());
q.addBindValue(names);

if (!q.execBatch())
    qDebug() << q.lastError();

El ejemplo anterior inserta cuatro nuevas filas en myTable:

1  Harald
2  Boris
3  Trond
4  NULL

Para vincular valores NULL, hay que añadir un ` QVariant ` nulo del tipo correspondiente al ` QVariantList` vinculado; por ejemplo, si se utilizan cadenas, se debe utilizar ` QVariant(QMetaType::fromType<QString>()) `.

Nota: Cada ` QVariantList ` vinculada debe contener el mismo número de variantes.

Nota: El tipo de las QVariants de una lista no debe cambiar. Por ejemplo, no se pueden mezclar variantes de tipo entero y de tipo cadena dentro de un ` QVariantList`.

El parámetro ` mode ` indica cómo se interpretará el ` QVariantList ` vinculado. Si ` mode ` es ` ValuesAsRows`, cada variante del ` QVariantList ` se interpretará como un valor para una nueva fila. ` ValuesAsColumns ` es un caso especial para el controlador de Oracle. En este modo, cada entrada del ` QVariantList ` se interpretará como un valor de matriz para un valor `IN` o `OUT` dentro de un procedimiento almacenado. Ten en cuenta que esto solo funcionará si el valor IN u OUT es un tipo de tabla que consta únicamente de una columna de un tipo básico, por ejemplo TYPE myType IS TABLE OF VARCHAR(64) INDEX BY BINARY_INTEGER;

Véase también prepare(), bindValue() y addBindValue().

QString QSqlQuery::executedQuery() const

Devuelve la última consulta que se ha ejecutado correctamente.

En la mayoría de los casos, esta función devuelve la misma cadena que « lastQuery()». Si se ejecuta una consulta preparada con marcadores de posición en un SGBD que no los admite, se emula la preparación de dicha consulta. Los marcadores de posición de la consulta original se sustituyen por sus valores vinculados para formar una nueva consulta. Esta función devuelve la consulta modificada. Resulta especialmente útil con fines de depuración.

Véase también lastQuery().

void QSqlQuery::finish()

Indica al controlador de la base de datos que no se recuperarán más datos de esta consulta hasta que se vuelva a ejecutar. Normalmente no es necesario llamar a esta función, pero puede resultar útil para liberar recursos, como bloqueos o cursores, si se tiene intención de reutilizar la consulta más adelante.

Establece la consulta como inactiva. Los valores vinculados conservan sus valores.

Véase también prepare(), exec() y isActive().

bool QSqlQuery::first()

Recupera el primer registro del resultado, si está disponible, y sitúa la posición de la consulta en dicho registro. Ten en cuenta que el resultado debe encontrarse en el estado « active » y que la función « isSelect()» debe devolver «true» antes de llamar a esta función; de lo contrario, no realizará ninguna acción y devolverá «false». Devuelve « true » si se realiza correctamente. Si no se realiza correctamente, la posición de la consulta se establece en una posición no válida y se devuelve «false».

Véanse también next(), previous(), last(), seek(), at(), isActive() y isValid().

bool QSqlQuery::isActive() const

Devuelve ` true ` si la consulta está activa. Una consulta ` QSqlQuery ` activa es aquella que se ha ejecutado correctamente mediante ` exec()` pero que aún no ha finalizado. Cuando hayas terminado con una consulta activa, puedes desactivarla llamando a ` finish()` o ` clear()`, o bien puedes eliminar la instancia de ` QSqlQuery `.

Nota: Reviste especial interés una consulta activa que sea una instrucción ` SELECT `. En algunas bases de datos que admiten transacciones, una consulta activa que sea una instrucción ` SELECT ` puede provocar que fallen las funciones ` commit()` o ` rollback()`, por lo que, antes de confirmar o revertir, debes desactivar tu consulta activa de tipo ` SELECT ` utilizando uno de los métodos indicados anteriormente.

Véase también isSelect().

bool QSqlQuery::isForwardOnly() const

Devuelve ` forwardOnly`.

Nota: Funcióngetter para la propiedad forwardOnly.

Véase también forwardOnly, next() y seek().

bool QSqlQuery::isNull(int field) const

Devuelve « true » si la consulta no es « active », si la consulta no está situada en un registro válido, si no existe « field » o si « field » es nulo; en caso contrario, devuelve « false ». Ten en cuenta que, en algunos controladores, «isNull()» no devolverá información precisa hasta que se haya intentado recuperar datos.

Véase también isActive(), isValid() y value().

bool QSqlQuery::isNull(QAnyStringView name) const

Devuelve ` true ` si no existe ningún campo con este ` name`; en caso contrario, devuelve `isNull(int index)` para el índice del campo correspondiente.

Esta sobrecarga es menos eficiente que ` isNull()`

Nota: En las versiones de Qt anteriores a la 6.8, esta función aceptaba QString, no QAnyStringView.

Esta es una función sobrecargada.

[since 6.7] bool QSqlQuery::isPositionalBindingEnabled() const

Devuelve ` positionalBindingEnabled`.

Nota: Funcióngetter para la propiedad positionalBindingEnabled.

Esta función se introdujo en Qt 6.7.

Véase también positionalBindingEnabled.

bool QSqlQuery::isSelect() const

Devuelve « true » si la consulta actual es una instrucción « SELECT »; en caso contrario, devuelve « false ».

bool QSqlQuery::isValid() const

Devuelve « true » si la consulta se encuentra actualmente en un registro válido; en caso contrario, devuelve « false ».

bool QSqlQuery::last()

Recupera el último registro del resultado, si está disponible, y sitúa la posición de la consulta en dicho registro. Ten en cuenta que el resultado debe encontrarse en el estado « active » y que la función « isSelect()» debe devolver «true» antes de llamar a esta función; de lo contrario, no realizará ninguna acción y devolverá «false». Devuelve « true » si la operación se realiza con éxito. Si falla, la posición de la consulta se establece en una posición no válida y se devuelve «false».

Véase también next(), previous(), first(), seek(), at(), isActive() y isValid().

QSqlError QSqlQuery::lastError() const

Devuelve información sobre el último error (si lo hubiera) que se ha producido con esta consulta.

Véase también QSqlError y QSqlDatabase::lastError().

QVariant QSqlQuery::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.

En el caso de las bases de datos MySQL, se devolverá el campo de autoincremento de la fila.

Nota: Para que esta función funcione en PSQL, la tabla debe contener OID, que pueden no haberse creado de forma predeterminada. Comprueba la variable de configuración default_with_oids para asegurarte.

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

QString QSqlQuery::lastQuery() const

Devuelve el texto de la consulta actual que se está utilizando, o una cadena vacía si no hay ningún texto de consulta actual.

Véase también executedQuery().

bool QSqlQuery::next()

Recupera el siguiente registro del resultado, si está disponible, y sitúa la consulta en el registro recuperado. Ten en cuenta que el resultado debe estar en el estado « active » y que la función ` isSelect()` debe devolver «true» antes de llamar a esta función; de lo contrario, no hará nada y devolverá «false».

Se aplican las siguientes reglas:

  • Si el resultado se encuentra actualmente antes del primer registro, por ejemplo, inmediatamente después de ejecutar una consulta, se intenta recuperar el primer registro.
  • Si el resultado se encuentra actualmente después del último registro, no se produce ningún cambio y se devuelve false.
  • Si el resultado se encuentra en algún punto intermedio, se intenta recuperar el siguiente registro.

Si no se ha podido recuperar el registro, el resultado se coloca después del último registro y se devuelve «false». Si el registro se recupera correctamente, se devuelve «true».

Véase también previous(), first(), last(), seek(), at(), isActive() y isValid().

bool QSqlQuery::nextResult()

Descarta el conjunto de resultados actual y pasa al siguiente, si hay alguno disponible.

Algunas bases de datos pueden devolver varios conjuntos de resultados para procedimientos almacenados o lotes SQL (una cadena de consulta que contiene varias sentencias). Si hay varios conjuntos de resultados disponibles tras ejecutar una consulta, esta función se puede utilizar para pasar al siguiente conjunto o conjuntos de resultados.

Si hay un nuevo conjunto de resultados disponible, esta función devolverá «true». La consulta se reposicionará en un registro no válido del nuevo conjunto de resultados y será necesario navegar hasta un registro válido antes de poder recuperar los valores de los datos. Si no hay ningún nuevo conjunto de resultados disponible, la función devuelve « false » y la consulta pasa a estar inactiva. En cualquier caso, se descartará el conjunto de resultados anterior.

Cuando una de las sentencias no es de selección, es posible que se obtenga un recuento de filas afectadas en lugar de un conjunto de resultados.

Tenga en cuenta que algunas bases de datos, como Microsoft SQL Server, requieren cursores no desplazables cuando se trabaja con varios conjuntos de resultados. Algunas bases de datos pueden ejecutar todas las sentencias a la vez, mientras que otras pueden retrasar la ejecución hasta que se acceda realmente al conjunto de resultados, y otras pueden tener restricciones sobre qué sentencias se permiten utilizar en un lote SQL.

Véase también QSqlDriver::hasFeature(), forwardOnly, next(), isSelect(), numRowsAffected(), isActive() y lastError().

int QSqlQuery::numRowsAffected() const

Devuelve el número de filas afectadas por la instrucción SQL del resultado, o -1 si no se puede determinar. Ten en cuenta que, para las instrucciones « SELECT », el valor no está definido; utiliza en su lugar « size()». Si la consulta no es « active », se devuelve -1.

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

QSql::NumericalPrecisionPolicy QSqlQuery::numericalPrecisionPolicy() const

Devuelve la propiedad `numericalPrecisionPolicy`.

Nota: Funcióngetter para la propiedad «numericalPrecisionPolicy».

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

bool QSqlQuery::prepare(const QString &query)

Prepara la consulta SQL « query » para su ejecución. Devuelve « true » si la consulta se prepara correctamente; en caso contrario, devuelve « false ».

La consulta puede contener marcadores de posición para valores de enlace. Se admiten tanto los marcadores de posición al estilo Oracle con dos puntos y nombre (p. ej., :surname) como los de estilo ODBC (?), pero no se pueden mezclar en la misma consulta. Consulte Detailed Description para ver ejemplos.

Notas sobre portabilidad: algunas bases de datos optan por retrasar la preparación de una consulta hasta que se ejecuta por primera vez. En este caso, la preparación de una consulta sintácticamente incorrecta se realiza con éxito, pero cada llamada consecutiva a exec() fallará. Cuando la base de datos no admite directamente los marcadores de posición con nombre, el marcador de posición solo puede contener caracteres del rango [a-zA-Z0-9_].

En el caso de SQLite, la cadena de consulta solo puede contener una instrucción a la vez. Si se proporciona más de una instrucción, la función devuelve false.

Ejemplo:

    QSqlQuery query;
    query.prepare("INSERT INTO person (id, forename, surname) "
                  "VALUES (:id, :forename, :surname)");
    query.bindValue(":id", 1001);
    query.bindValue(":forename", "Bart");
    query.bindValue(":surname", "Simpson");
    query.exec();

Véase también exec(), bindValue() y addBindValue().

bool QSqlQuery::previous()

Recupera el registro anterior del resultado, si está disponible, y sitúa la consulta en el registro recuperado. Ten en cuenta que el resultado debe estar en el estado « active » y que la función ` isSelect()` debe devolver «true» antes de llamar a esta función; de lo contrario, no hará nada y devolverá «false».

Se aplican las siguientes reglas:

  • Si el resultado se encuentra actualmente antes del primer registro, no se produce ningún cambio y se devuelve «false».
  • Si el resultado se encuentra actualmente después del último registro, se intenta recuperar el último registro.
  • Si el resultado se encuentra en algún punto intermedio, se intenta recuperar el registro anterior.

Si no se ha podido recuperar el registro, el resultado se sitúa antes del primer registro y se devuelve «false». Si el registro se recupera correctamente, se devuelve «true».

Véase también next(), first(), last(), seek(), at(), isActive() y isValid().

QSqlRecord QSqlQuery::record() const

Devuelve un objeto ` QSqlRecord ` que contiene la información de los campos de la consulta actual. Si la consulta apunta a una fila válida (la función `isValid()` devuelve «true»), el registro se rellena con los valores de dicha fila. Se devuelve un registro vacío cuando no hay ninguna consulta activa (la función `isActive()` devuelve «false»).

Para recuperar valores de una consulta, se debe utilizar ` value()` ya que su búsqueda basada en índices es más rápida.

En el siguiente ejemplo, se ejecuta una consulta SELECT * FROM. Dado que el orden de las columnas no está definido, se utiliza QSqlRecord::indexOf() para obtener el índice de una columna.

QSqlQuery q("select * from employees");
QSqlRecord rec = q.record();

qDebug() << "Number of columns: " << rec.count();

int nameCol = rec.indexOf("name"); // índice del campo «name»
while (q.next())
    qDebug() << q.value(nameCol).toString(); // output all names

Véase también value().

const QSqlResult *QSqlQuery::result() const

Devuelve el resultado asociado a la consulta.

bool QSqlQuery::seek(int index, bool relative = false)

Recupera el registro situado en la posición index, si está disponible, y sitúa la consulta en el registro recuperado. El primer registro se encuentra en la posición 0. Ten en cuenta que la consulta debe estar en estado « active » y que isSelect() debe devolver «true» antes de llamar a esta función.

Si relative es false (valor por defecto), se aplican las siguientes reglas:

  • Si index es negativo, el resultado se sitúa antes del primer registro y se devuelve false.
  • En caso contrario, se intenta desplazarse hasta el registro situado en la posición index. Si no se ha podido recuperar el registro situado en la posición index, el resultado se sitúa después del último registro y se devuelve «false». Si el registro se recupera correctamente, se devuelve «true».

Si relative es «true», se aplican las siguientes reglas:

  • Si el resultado se encuentra actualmente situado antes del primer registro y:
    • index es negativo o cero, no se produce ningún cambio y se devuelve «false».
    • index es positivo, se intenta situar el resultado en la posición absoluta index - 1, siguiendo la misma regla que para la búsqueda no relativa, descrita anteriormente.
  • Si el resultado se encuentra actualmente situado después del último registro y:
    • index es positivo o cero, no se produce ningún cambio y se devuelve «false».
    • index es negativo, se intenta situar el resultado en la posición relativa index + 1 respecto al último registro, siguiendo la regla que se indica a continuación.
  • Si el resultado se encuentra actualmente en algún punto intermedio y el desplazamiento relativo index sitúa el resultado por debajo de cero, el resultado se coloca antes del primer registro y se devuelve «false».
  • De lo contrario, se intenta desplazarse al registro situado « index » registros por delante del registro actual (o « index » registros por detrás del registro actual si « index » es negativo). Si no se ha podido recuperar el registro en la posición index, el resultado se sitúa después del último registro si index >= 0 (o antes del primer registro si index es negativo), y se devuelve «false». Si el registro se recupera correctamente, se devuelve «true».

Véanse también next(), previous(), first(), last(), at(), isActive() y isValid().

void QSqlQuery::setForwardOnly(bool forward)

Establece el valor de « forwardOnly » en « forward ».

Nota: Funciónde asignación para la propiedad forwardOnly.

Véase también isForwardOnly(), forwardOnly, next() y seek().

void QSqlQuery::setNumericalPrecisionPolicy(QSql::NumericalPrecisionPolicy precisionPolicy)

Establece el valor de « numericalPrecisionPolicy » en « precisionPolicy ».

Nota: Funciónde asignación para la propiedad numericalPrecisionPolicy.

Véase también numericalPrecisionPolicy().

[since 6.7] void QSqlQuery::setPositionalBindingEnabled(bool enable)

Establece el valor de « positionalBindingEnabled » en « enable ».

Nota: Funciónde asignación para la propiedad positionalBindingEnabled.

Esta función se introdujo en Qt 6.7.

Véase también isPositionalBindingEnabled() y positionalBindingEnabled.

int QSqlQuery::size() const

Devuelve el tamaño del resultado (número de filas devueltas) o -1 si no se puede determinar el tamaño o si la base de datos no admite la información sobre el tamaño de las consultas. Ten en cuenta que, para las sentencias que no sean de tipo «SELECT » (isSelect() devuelve false), la función size() devolverá -1. Si la consulta no está activa (isActive() devuelve false), se devuelve -1.

Para determinar el número de filas afectadas por una instrucción que no sea «SELECT », utiliza « numRowsAffected()».

Véase también isActive(), numRowsAffected() y QSqlDriver::hasFeature().

[noexcept, since 6.2] void QSqlQuery::swap(QSqlQuery &other)

Sustituye esta consulta por other. Esta operación es muy rápida y nunca falla.

Esta función se introdujo en Qt 6.2.

QVariant QSqlQuery::value(int index) const

Devuelve el valor del campo « index » del registro actual.

Los campos se numeran de izquierda a derecha utilizando el texto de la instrucción « SELECT »; por ejemplo, en

SELECT forename, surname FROM people;

el campo 0 es forename y el campo 1 es surname. No se recomienda utilizar SELECT *, ya que el orden de los campos en la consulta no está definido.

Se devuelve un QVariant no válido si el campo index no existe, si la consulta está inactiva o si la consulta se encuentra en un registro no válido.

Véase también previous(), next(), first(), last(), seek(), isActive() y isValid().

QVariant QSqlQuery::value(QAnyStringView name) const

Devuelve el valor del campo denominado « name » en el registro actual. Si el campo « name » no existe, se devuelve una variante no válida.

Esta sobrecarga es menos eficiente que value()

Nota: En las versiones de Qt anteriores a la 6.8, esta función aceptaba QString, no QAnyStringView.

Esta es una función sobrecargada.

[noexcept, since 6.2] QSqlQuery &QSqlQuery::operator=(QSqlQuery &&other)

La función «move-assigns» asigna « other » a este objeto.

Esta función se introdujo en Qt 6.2.

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