QSqlQuery Class

Documentación de funciones miembro

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

Construye un objeto QSqlQuery que utiliza QSqlResult result para comunicarse con una base de datos.

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

Construye un objeto QSqlQuery utilizando la base de datos db. Si db no es válida, se utilizará la base de datos por defecto de la aplicación.

Véase también QSqlDatabase.

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

Construye un objeto QSqlQuery utilizando el SQL query y la base de datos db. Si db no se especifica, o no es válido, se utiliza la base de datos por defecto 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)

Move-construye una 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 la vinculación posicional de valores. El orden de las llamadas a addBindValue() determina a qué marcador de posición se vinculará 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 después de la llamada a exec().

Para vincular un valor NULL, utilice un valor nulo QVariant; por ejemplo, utilice QVariant(QMetaType::fromType<QString>()) si está vinculando 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 está 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)

Establezca el marcador de posición placeholder para que se vincule al valor val en la sentencia preparada. Tenga en cuenta que la marca del marcador de posición (por ejemplo, :) debe incluirse 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 después de la llamada a exec(). En este caso, debe preasignarse espacio suficiente para almacenar el resultado.

Para vincular un valor NULL, utilice un valor nulo QVariant; por ejemplo, utilice QVariant(QMetaType::fromType<QString>()) si está vinculando 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)

Establezca el marcador de posición en la posición pos para que se vincule al valor val en la sentencia preparada. La numeración de 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 después de la llamada a exec().

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

Devuelve el valor de placeholder.

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

QVariant QSqlQuery::boundValue(int pos) const

Devuelve el valor del marcador de posición 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 es el orden de vinculación, independientemente de si se utiliza la vinculación por nombre o posicional.

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 es el orden de vinculación, independientemente de si se utiliza la vinculación por nombre o posicional.

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 es el orden de vinculación, independientemente de si se utiliza la 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 retenidos por la consulta. Establece el estado de la consulta como inactivo. Rara vez o nunca debería necesitar 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 previamente preparada. Devuelve true si la consulta se ejecutó correctamente; en caso contrario devuelve false.

Tenga en cuenta que el último error de esta consulta se restablece cuando se llama a exec().

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

bool QSqlQuery::exec(const QString &query)

Ejecuta el SQL en 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 consultada (por ejemplo, SQL estándar).

Una vez ejecutada la consulta, ésta se posiciona en un registro no válido y debe navegarse hasta un registro válido antes de poder recuperar los valores de los datos (por ejemplo, utilizando next()).

Tenga en cuenta que el último error de esta consulta se restablece cuando se llama a exec().

En SQLite, la cadena de consulta sólo puede contener una sentencia cada vez. Si se proporciona más de una sentencia, 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 por lotes una consulta SQL previamente preparada. Todos los parámetros vinculados deben ser listas de variantes. Si la base de datos no admite ejecuciones por lotes, el controlador lo simulará utilizando llamadas convencionales a exec().

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

Ejemplo:

QSqlQuery q; q.prepare("insertar en miTabla valores (?, ?)");QVariantList ints; ints<< 1<< 2<< 3<< 4; q.addBindValue(ints);QVariantList names; names<< "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, debe añadirse un QVariant nulo del tipo correspondiente al QVariantList vinculado; por ejemplo, debe utilizarse QVariant(QMetaType::fromType<QString>()) si se utilizan cadenas.

El parámetro mode indica cómo se interpretará el campo QVariantList. Si mode es ValuesAsRows, cada variante dentro de 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 dentro de QVariantList se interpretará como valor de matriz para un valor IN o OUT dentro de un procedimiento almacenado. Tenga en cuenta que esto sólo funcionará si el valor IN o OUT es de tipo tabla y consta de una sola columna de 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 ejecutada 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 lo soporta, se emula la preparación de esta consulta. Los marcadores de posición de la consulta original se sustituyen por sus valores ligados para formar una nueva consulta. Esta función devuelve la consulta modificada. Es útil sobre todo para depurar errores.

Véase también lastQuery().

void QSqlQuery::finish()

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

Pone la consulta en 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 posiciona la consulta en el registro recuperado. Tenga en cuenta que el resultado debe estar en el estado active y isSelect() debe devolver true antes de llamar a esta función o no hará nada y devolverá false. Devuelve true si tiene éxito. Si no tiene éxito, la posición de consulta se establece en una posición no válida y se devuelve false.

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

bool QSqlQuery::isActive() const

Devuelve true si la consulta está activa. Una QSqlQuery activa es aquella que ha sido exec()'d con éxito pero con la que aún no se ha terminado. Cuando haya terminado con una consulta activa, puede desactivarla llamando a finish() o clear(), o puede borrar la instancia QSqlQuery.

Véase también isSelect().

bool QSqlQuery::isForwardOnly() const

Devuelve forwardOnly.

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

bool QSqlQuery::isNull(int field) const

Devuelve true si la consulta no es active, la consulta no está posicionada en un registro válido, no existe tal field, o el field es nulo; en caso contrario false. Tenga en cuenta que para algunos controladores, isNull() no devolverá información precisa hasta después de que se haya intentado recuperar los datos.

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

bool QSqlQuery::isNull(QAnyStringView name) const

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

Esta sobrecarga es menos eficiente que isNull()

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

Devuelve 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 sentencia SELECT; en caso contrario devuelve false.

bool QSqlQuery::isValid() const

Devuelve true si la consulta está posicionada actualmente en un registro válido; en caso contrario devuelve false.

bool QSqlQuery::last()

Recupera el último registro del resultado, si está disponible, y posiciona la consulta en el registro recuperado. Tenga en cuenta que el resultado debe estar en el estado active y isSelect() debe devolver true antes de llamar a esta función o no hará nada y devolverá false. Devuelve true si tiene éxito. Si no tiene éxito, la posición de 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 hubo) que se produjo 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 reciente si la base de datos lo admite. Se devolverá un QVariant inválido si la consulta no insertó 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.

Para bases de datos MySQL se devolverá el campo de autoincremento de la fila.

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 texto de consulta actual.

Véase también executedQuery().

bool QSqlQuery::next()

Recupera el siguiente registro en el resultado, si está disponible, y posiciona la consulta en el registro recuperado. Tenga en cuenta que el resultado debe estar en el estado active y isSelect() debe devolver true antes de llamar a esta función o 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 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 sitúa 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 navega al siguiente si está disponible.

Algunas bases de datos son capaces de devolver múltiples conjuntos de resultados para procedimientos almacenados o lotes SQL (una cadena de consulta que contiene múltiples sentencias). Si hay varios conjuntos de resultados disponibles después de ejecutar una consulta, esta función puede utilizarse para navegar al siguiente conjunto 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 se deberá navegar hasta un registro válido antes de poder recuperar los valores de los datos. Si no hay disponible un nuevo conjunto de resultados, la función devuelve false y la consulta se establece como inactiva. En cualquier caso, se descartará el antiguo conjunto de resultados.

Cuando una de las sentencias es una sentencia no select, puede estar disponible 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 algunas bases de datos pueden tener restricciones sobre qué sentencias pueden utilizarse 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 sentencia SQL del resultado, o -1 si no se puede determinar. Tenga en cuenta que para las sentencias SELECT, el valor es indefinido; utilice size() en su lugar. Si la consulta no es active, se devuelve -1.

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

QSql::NumericalPrecisionPolicy QSqlQuery::numericalPrecisionPolicy() const

Devuelve la 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 ha preparado 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 de dos puntos estilo Oracle (por ejemplo, :surname), como los de estilo ODBC (?); pero no pueden mezclarse en la misma consulta. Véanse ejemplos en Detailed Description.

Notas sobre portabilidad: Algunas bases de datos deciden 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 tiene éxito, pero todas las exec() consecutivas fallarán. Cuando la base de datos no admite marcadores de posición con nombre directamente, el marcador de posición sólo puede contener caracteres del rango [a-zA-Z0-9_].

En SQLite, la cadena de consulta sólo puede contener una sentencia cada vez. Si se proporciona más de una sentencia, 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 en el resultado, si está disponible, y posiciona la consulta en el registro recuperado. Tenga en cuenta que el resultado debe estar en el estado active y isSelect() debe devolver true antes de llamar a esta función o no hará nada y devolverá false.

Se aplican las siguientes reglas:

• Si el resultado se encuentra antes del primer registro, no se produce ningún cambio y se devuelve false.
• Si el resultado se encuentra 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 QSqlRecord que contiene la información de campo de la consulta actual. Si la consulta apunta a una fila válida (isValid() devuelve true), el registro se rellena con los valores de la fila. Se devuelve un registro vacío cuando no hay ninguna consulta activa (isActive() devuelve false).

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

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

QSqlQuery q("select * from empleados");QSqlRecord rec = q.record();
qDebug() << "Number of columns: " << rec.count();

int nombreCol = rec.indexOf("nombre"); // índice del campo "nombre"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 en la posición index, si está disponible, y posiciona la consulta en el registro recuperado. El primer registro está en la posición 0. Tenga en cuenta que la consulta debe estar en un estado active y isSelect() debe devolver true antes de llamar a esta función.

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

• Si index es negativo, el resultado se posiciona antes del primer registro y se devuelve false.
• En caso contrario, se intenta pasar al registro en la posición index. Si no se ha podido recuperar el registro en la posición index, el resultado se posiciona después del último registro y se devuelve false. Si el registro se recupera correctamente, se devuelve true.

Si relative es verdadero, se aplican las siguientes reglas:

• Si el resultado está situado antes del primer registro y :
  • index es negativo o cero, no hay cambio y se devuelve false.
  • index es positivo, se intenta posicionar el resultado en la posición absoluta index - 1, siguiendo la misma regla para la búsqueda no relativa, arriba.
• Si el resultado se encuentra después del último registro y :
  • index es positivo o cero, no hay cambio y se devuelve false.
  • index es negativo, se intenta posicionar el resultado en index + 1 posición relativa desde el último registro, siguiendo la siguiente regla.
• Si el resultado se encuentra actualmente en algún lugar en el medio, y el desplazamiento relativo index mueve el resultado por debajo de cero, el resultado se posiciona antes del primer registro y se devuelve false.
• En caso contrario, se intenta mover al registro index registros por delante del registro actual (o index registros por detrás del registro actual si index es negativo). Si no se pudo recuperar el registro en el desplazamiento index, el resultado se posiciona 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éase también next(), previous(), first(), last(), at(), isActive() y isValid().

void QSqlQuery::setForwardOnly(bool forward)

Establece forwardOnly en forward.

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

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

Establece numericalPrecisionPolicy en precisionPolicy.

Véase también numericalPrecisionPolicy().

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

Establece positionalBindingEnabled en enable.

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 información sobre el tamaño de las consultas. Tenga en cuenta que para sentencias que no seanSELECT (isSelect() devuelve false), 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 sentencia que no seaSELECT, utilice numRowsAffected().

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

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

Intercambia esta consulta con 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 en el registro actual.

Los campos se numeran de izquierda a derecha utilizando el texto de la declaració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 * porque el orden de los campos en la consulta es indefinido.

Se devuelve un QVariant no válido si el campo index no existe, si la consulta está inactiva o si la consulta se sitúa 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 llamado 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()

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

Mover-asigna other a este objeto.

Esta función se introdujo en Qt 6.2.