QSqlQuery Class

Documentation des fonctions membres

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

Construit un objet QSqlQuery qui utilise QSqlResult result pour communiquer avec une base de données.

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

Construit un objet QSqlQuery en utilisant la base de données db. Si db n'est pas valide, la base de données par défaut de l'application sera utilisée.

Voir aussi QSqlDatabase.

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

Construit un objet QSqlQuery en utilisant le code SQL query et la base de données db. Si db n'est pas spécifié ou est invalide, la base de données par défaut de l'application est utilisée. Si query n'est pas une chaîne vide, il sera exécuté.

Voir aussi QSqlDatabase.

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

Move-construit un QSqlQuery à partir de other.

Cette fonction a été introduite dans Qt 6.2.

[noexcept] QSqlQuery::~QSqlQuery()

Détruit l'objet et libère les ressources allouées.

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

Ajoute la valeur val à la liste des valeurs lors de l'utilisation de la liaison de valeur positionnelle. L'ordre des appels à addBindValue() détermine à quel espace réservé une valeur sera liée dans la requête préparée. Si paramType est QSql::Out ou QSql::InOut, l'espace réservé sera remplacé par des données provenant de la base de données après l'appel à exec().

Pour lier une valeur NULL, utilisez une valeur null QVariant; par exemple, utilisez QVariant(QMetaType::fromType<QString>()) si vous liez une chaîne de caractères.

Voir aussi bindValue(), prepare(), exec(), boundValue() et boundValues().

int QSqlQuery::at() const

Renvoie la position interne actuelle de la requête. Le premier enregistrement se trouve à la position zéro. Si la position n'est pas valide, la fonction renvoie QSql::BeforeFirstRow ou QSql::AfterLastRow, qui sont des valeurs négatives spéciales.

Voir aussi previous(), next(), first(), last(), seek(), isActive() et isValid().

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

Définir le caractère générique placeholder pour qu'il soit lié à la valeur val dans l'instruction préparée. Notez que la marque du placeholder (par exemple :) doit être incluse lors de la spécification du nom du placeholder. Si paramType est QSql::Out ou QSql::InOut, l'espace réservé sera remplacé par des données provenant de la base de données après l'appel à exec(). Dans ce cas, un espace suffisant doit être alloué à l'avance pour y stocker le résultat.

Pour lier une valeur NULL, utilisez une valeur null QVariant; par exemple, utilisez QVariant(QMetaType::fromType<QString>()) si vous liez une chaîne de caractères.

Voir aussi addBindValue(), prepare(), exec(), boundValue() et boundValues().

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

Définir le caractère générique en position pos pour qu'il soit lié à la valeur val dans l'instruction préparée. La numérotation des champs commence à 0. Si paramType est QSql::Out ou QSql::InOut, l'espace réservé sera remplacé par des données provenant de la base de données après l'appel à exec().

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

Renvoie la valeur de la variable placeholder.

Voir aussi boundValues(), bindValue(), et addBindValue().

QVariant QSqlQuery::boundValue(int pos) const

Renvoie la valeur de l'espace réservé à la position pos.

Voir également boundValues().

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

Renvoie le nom de la valeur liée à la position pos.

L'ordre de la liste est l'ordre de liaison, indépendamment de l'utilisation de la liaison nommée ou positionnelle.

Cette fonction a été introduite dans Qt 6.6.

Voir également boundValueNames().

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

Renvoie les noms de toutes les valeurs liées.

L'ordre de la liste est l'ordre de liaison, que la liaison soit nommée ou positionnelle.

Cette fonction a été introduite dans Qt 6.6.

Voir aussi boundValues() et boundValueName().

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

Renvoie une liste de valeurs liées.

L'ordre de la liste est l'ordre de liaison, que la liaison soit nommée ou positionnelle.

Les valeurs liées peuvent être examinées de la manière suivante :

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

Cette fonction a été introduite dans Qt 6.0.

Voir aussi boundValue(), bindValue(), addBindValue(), et boundValueNames().

void QSqlQuery::clear()

Efface l'ensemble des résultats et libère toutes les ressources détenues par la requête. Définit l'état de la requête comme inactive. Vous ne devriez que rarement, voire jamais, avoir besoin d'appeler cette fonction.

const QSqlDriver *QSqlQuery::driver() const

Renvoie le pilote de base de données associé à la requête.

bool QSqlQuery::exec()

Exécute une requête SQL préparée au préalable. Renvoie true si la requête s'est exécutée avec succès ; sinon, renvoie false.

Notez que la dernière erreur pour cette requête est réinitialisée lorsque exec() est appelé.

Voir aussi prepare(), bindValue(), addBindValue(), boundValue() et boundValues().

bool QSqlQuery::exec(const QString &query)

Exécute le code SQL dans query. Renvoie true et définit l'état de la requête à active si la requête a réussi ; sinon, il renvoie false. La chaîne query doit utiliser une syntaxe adaptée à la base de données SQL interrogée (par exemple, SQL standard).

Après l'exécution de la requête, celle-ci est positionnée sur un enregistrement non valide et doit être déplacée vers un enregistrement valide avant que les valeurs des données puissent être récupérées (par exemple, en utilisant next()).

Notez que la dernière erreur pour cette requête est réinitialisée lorsque exec() est appelé.

Pour SQLite, la chaîne de requête ne peut contenir qu'une seule instruction à la fois. Si plus d'une instruction est donnée, la fonction renvoie false.

Exemple :

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

Voir également isActive(), isValid(), next(), previous(), first(), last() et seek().

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

Exécute une requête SQL préalablement préparée dans un lot. Tous les paramètres liés doivent être des listes de variantes. Si la base de données ne prend pas en charge les exécutions par lots, le pilote les simulera en utilisant les appels conventionnels exec().

Renvoie true si la requête est exécutée avec succès ; sinon, renvoie false.

Exemple :

QSqlQuery q ; q.prepare("insert into myTable values ( ?, ?)") ;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();

L'exemple ci-dessus insère quatre nouvelles lignes dans myTable:

1  Harald
2  Boris
3  Trond
4  NULL

Pour lier des valeurs NULL, un null QVariant du type approprié doit être ajouté au bound QVariantList; par exemple, QVariant(QMetaType::fromType<QString>()) doit être utilisé si vous utilisez des chaînes de caractères.

Le paramètre mode indique comment le lien QVariantList sera interprété. Si mode est ValuesAsRows, chaque variante à l'intérieur de QVariantList sera interprétée comme une valeur pour une nouvelle ligne. ValuesAsColumns est un cas spécial pour le pilote Oracle. Dans ce mode, chaque entrée dans QVariantList sera interprétée comme une valeur de tableau pour une valeur IN ou OUT dans une procédure stockée. Notez que cela ne fonctionnera que si la valeur IN ou OUT est un type de tableau composé d'une seule colonne d'un type de base, par exemple TYPE myType IS TABLE OF VARCHAR(64) INDEX BY BINARY_INTEGER;

Voir également prepare(), bindValue() et addBindValue().

QString QSqlQuery::executedQuery() const

Renvoie la dernière requête exécutée avec succès.

Dans la plupart des cas, cette fonction renvoie la même chaîne que lastQuery(). Si une requête préparée avec des espaces réservés est exécutée sur un SGBD qui ne la prend pas en charge, la préparation de cette requête est émulée. Les espaces réservés de la requête originale sont remplacés par leurs valeurs liées pour former une nouvelle requête. Cette fonction renvoie la requête modifiée. Elle est surtout utile à des fins de débogage.

Voir aussi lastQuery().

void QSqlQuery::finish()

Indique au pilote de la base de données que plus aucune donnée ne sera extraite de cette requête jusqu'à ce qu'elle soit réexécutée. Il n'est normalement pas nécessaire d'appeler cette fonction, mais elle peut être utile pour libérer des ressources telles que des verrous ou des curseurs si vous avez l'intention de réutiliser la requête ultérieurement.

Met la requête en mode inactif. Les valeurs liées conservent leur valeur.

Voir aussi prepare(), exec() et isActive().

bool QSqlQuery::first()

Récupère le premier enregistrement du résultat, s'il est disponible, et positionne la requête sur l'enregistrement récupéré. Notez que le résultat doit être dans l'état active et que isSelect() doit renvoyer true avant d'appeler cette fonction, sinon elle ne fera rien et renverra false. Renvoie true en cas de succès. En cas d'échec, la position de la requête est définie comme invalide et false est renvoyé.

Voir aussi next(), previous(), last(), seek(), at(), isActive() et isValid().

bool QSqlQuery::isActive() const

Renvoie true si la requête est active. Une requête active QSqlQuery est une requête qui a été exec() avec succès mais qui n'est pas encore terminée. Lorsque vous avez terminé une requête active, vous pouvez la rendre inactive en appelant finish() ou clear(), ou vous pouvez supprimer l'instance QSqlQuery.

Voir également isSelect().

bool QSqlQuery::isForwardOnly() const

Retourne forwardOnly.

Voir aussi forwardOnly, next(), et seek().

bool QSqlQuery::isNull(int field) const

Renvoie true si la requête n'est pas active, si la requête n'est pas positionnée sur un enregistrement valide, s'il n'y a pas de field, ou si le field est nul ; sinon false. Notez que pour certains pilotes, isNull() ne renvoie des informations précises qu'après une tentative de récupération des données.

Voir également isActive(), isValid() et value().

bool QSqlQuery::isNull(QAnyStringView name) const

Renvoie true s'il n'y a pas de champ avec ce name; sinon renvoie isNull(int index) pour l'index du champ correspondant.

Cette surcharge est moins efficace que isNull()

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

Retourne positionalBindingEnabled.

Cette fonction a été introduite dans Qt 6.7.

Voir aussi positionalBindingEnabled.

bool QSqlQuery::isSelect() const

Renvoie true si la requête en cours est une déclaration SELECT; sinon, renvoie false.

bool QSqlQuery::isValid() const

Renvoie true si la requête est actuellement positionnée sur un enregistrement valide ; sinon, renvoie false.

bool QSqlQuery::last()

Récupère le dernier enregistrement du résultat, s'il est disponible, et positionne la requête sur l'enregistrement récupéré. Notez que le résultat doit être dans l'état active et que isSelect() doit renvoyer true avant d'appeler cette fonction, sinon elle ne fera rien et renverra false. Renvoie true en cas de succès. En cas d'échec, la position de la requête est définie comme invalide et false est renvoyé.

Voir aussi next(), previous(), first(), seek(), at(), isActive() et isValid().

QSqlError QSqlQuery::lastError() const

Renvoie des informations sur la dernière erreur (le cas échéant) qui s'est produite avec cette requête.

Voir aussi QSqlError et QSqlDatabase::lastError().

QVariant QSqlQuery::lastInsertId() const

Renvoie l'ID de l'objet de la dernière ligne insérée si la base de données le permet. Une adresse invalide QVariant sera renvoyée si la requête n'a pas inséré de valeur ou si la base de données ne renvoie pas l'identifiant. Si plus d'une ligne a été touchée par l'insertion, le comportement est indéfini.

Pour les bases de données MySQL, le champ d'auto-incrémentation de la ligne sera renvoyé.

Voir aussi QSqlDriver::hasFeature().

QString QSqlQuery::lastQuery() const

Renvoie le texte de la requête en cours d'utilisation, ou une chaîne vide s'il n'y a pas de texte de requête en cours.

Voir aussi executedQuery().

bool QSqlQuery::next()

Récupère l'enregistrement suivant dans le résultat, s'il est disponible, et positionne la requête sur l'enregistrement récupéré. Notez que le résultat doit être dans l'état active et que isSelect() doit renvoyer true avant d'appeler cette fonction, sinon elle ne fera rien et renverra false.

Les règles suivantes s'appliquent :

• Si le résultat se trouve actuellement avant le premier enregistrement, par exemple immédiatement après l'exécution d'une requête, une tentative est faite pour récupérer le premier enregistrement.
• Si le résultat se trouve actuellement après le dernier enregistrement, il n'y a pas de changement et le système renvoie false.
• Si le résultat se trouve quelque part au milieu, on tente de récupérer l'enregistrement suivant.

Si l'enregistrement n'a pas pu être récupéré, le résultat est placé après le dernier enregistrement et le message false est renvoyé. Si l'enregistrement est récupéré avec succès, true est renvoyé.

Voir aussi previous(), first(), last(), seek(), at(), isActive() et isValid().

bool QSqlQuery::nextResult()

Rejette l'ensemble de résultats actuel et passe au suivant s'il est disponible.

Certaines bases de données sont capables de renvoyer plusieurs ensembles de résultats pour les procédures stockées ou les lots SQL (une chaîne de requête contenant plusieurs instructions). Si plusieurs ensembles de résultats sont disponibles après l'exécution d'une requête, cette fonction peut être utilisée pour passer à l'ensemble de résultats suivant.

Si un nouvel ensemble de résultats est disponible, cette fonction renvoie la valeur "true". La requête sera repositionnée sur un enregistrement invalide dans le nouvel ensemble de résultats et devra être déplacée vers un enregistrement valide avant que les valeurs des données puissent être récupérées. Si un nouvel ensemble de résultats n'est pas disponible, la fonction renvoie false et la requête est désactivée. Dans tous les cas, l'ancien ensemble de résultats est supprimé.

Lorsque l'une des instructions est une instruction non sélective, un nombre de lignes affectées peut être disponible au lieu d'un ensemble de résultats.

Notez que certaines bases de données, par exemple Microsoft SQL Server, requièrent des curseurs non défilables lorsque vous travaillez avec plusieurs ensembles de résultats. Certaines bases de données peuvent exécuter toutes les instructions en même temps, tandis que d'autres peuvent retarder l'exécution jusqu'à ce que l'ensemble de résultats soit effectivement consulté, et certaines bases de données peuvent avoir des restrictions sur les instructions autorisées à être utilisées dans un lot SQL.

Voir également QSqlDriver::hasFeature(), forwardOnly, next(), isSelect(), numRowsAffected(), isActive() et lastError().

int QSqlQuery::numRowsAffected() const

Renvoie le nombre de lignes affectées par l'instruction SQL du résultat, ou -1 s'il ne peut être déterminé. Notez que pour les instructions SELECT, la valeur est indéfinie ; utilisez size() à la place. Si la requête n'est pas active, -1 est renvoyé.

Voir aussi size() et QSqlDriver::hasFeature().

QSql::NumericalPrecisionPolicy QSqlQuery::numericalPrecisionPolicy() const

Renvoie la politique de précision numérique.

Voir également setNumericalPrecisionPolicy().

bool QSqlQuery::prepare(const QString &query)

Prépare la requête SQL query pour l'exécution. Renvoie true si la requête est préparée avec succès ; sinon, renvoie false.

La requête peut contenir des espaces réservés pour les valeurs de liaison. Les espaces réservés de style Oracle (par exemple, :surname) et de style ODBC (?) sont tous deux pris en charge, mais ils ne peuvent pas être mélangés dans la même requête. Voir Detailed Description pour des exemples.

Notes sur la portabilité : Certaines bases de données choisissent de retarder la préparation d'une requête jusqu'à ce qu'elle soit exécutée pour la première fois. Dans ce cas, la préparation d'une requête syntaxiquement incorrecte réussit, mais tous les exec() consécutifs échouent. Lorsque la base de données ne prend pas directement en charge les caractères génériques, ceux-ci ne peuvent contenir que des caractères de la plage [a-zA-Z0-9_].

Pour SQLite, la chaîne de requête ne peut contenir qu'une seule instruction à la fois. Si plusieurs instructions sont fournies, la fonction renvoie false.

Exemple :

    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();

Voir également exec(), bindValue() et addBindValue().

bool QSqlQuery::previous()

Récupère l'enregistrement précédent dans le résultat, s'il est disponible, et positionne la requête sur l'enregistrement récupéré. Notez que le résultat doit être dans l'état active et que isSelect() doit renvoyer true avant d'appeler cette fonction, sinon elle ne fera rien et renverra false.

Les règles suivantes s'appliquent :

• Si le résultat se trouve actuellement avant le premier enregistrement, il n'y a pas de changement et la fonction renvoie false.
• Si le résultat se trouve actuellement après le dernier enregistrement, une tentative est faite pour récupérer le dernier enregistrement.
• Si le résultat se situe entre les deux, on tente de récupérer l'enregistrement précédent.

Si l'enregistrement n'a pas pu être récupéré, le résultat est placé avant le premier enregistrement et le message false est renvoyé. Si l'enregistrement est récupéré avec succès, true est renvoyé.

Voir aussi next(), first(), last(), seek(), at(), isActive() et isValid().

QSqlRecord QSqlQuery::record() const

Renvoie une adresse QSqlRecord contenant les informations sur les champs de la requête en cours. Si la requête pointe vers une ligne valide (isValid() renvoie vrai), l'enregistrement est rempli avec les valeurs de la ligne. Un enregistrement vide est renvoyé lorsqu'il n'y a pas de requête active (isActive() renvoie false).

Pour récupérer les valeurs d'une requête, il est préférable d'utiliser value(), car sa recherche basée sur un index est plus rapide.

Dans l'exemple suivant, une requête SELECT * FROM est exécutée. L'ordre des colonnes n'étant pas défini, QSqlRecord::indexOf() est utilisé pour obtenir l'index d'une colonne.

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

int nameCol = rec.indexOf("name") ; // index du champ "name"while (q.next())    qDebug() << q.value(nameCol).toString(); // output all names

Voir aussi value().

const QSqlResult *QSqlQuery::result() const

Renvoie le résultat associé à la requête.

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

Récupère l'enregistrement à la position index, s'il est disponible, et positionne la requête sur l'enregistrement récupéré. Le premier enregistrement est à la position 0. Notez que la requête doit être dans l'état active et que isSelect() doit retourner vrai avant d'appeler cette fonction.

Si relative est faux (par défaut), les règles suivantes s'appliquent :

• Si index est négatif, le résultat est positionné avant le premier enregistrement et false est renvoyé.
• Dans le cas contraire, on tente de passer à l'enregistrement situé à la position index. Si l'enregistrement à la position index n'a pas pu être récupéré, le résultat est placé après le dernier enregistrement et le message false est renvoyé. Si l'enregistrement est récupéré avec succès, true est renvoyé.

Si relative est vrai, les règles suivantes s'appliquent :

• Si le résultat est actuellement positionné avant le premier enregistrement et que :
  • index est négatif ou nul, il n'y a pas de changement et false est renvoyé.
  • index est positif, une tentative est faite pour positionner le résultat à la position absolue index - 1, en suivant la même règle que pour la recherche non relative, ci-dessus.
• Si le résultat est actuellement positionné après le dernier enregistrement et que :
  • index est positif ou nul, il n'y a pas de changement et false est renvoyé.
  • index est négatif, une tentative est faite pour positionner le résultat à la position relative index + 1 par rapport au dernier enregistrement, en suivant la règle ci-dessous.
• Si le résultat est actuellement situé quelque part au milieu et que le décalage relatif index le fait passer en dessous de zéro, le résultat est positionné avant le premier enregistrement et le message false est renvoyé.
• Dans le cas contraire, une tentative est faite pour se déplacer vers l'enregistrement index avant l'enregistrement actuel (ou index après l'enregistrement actuel si index est négatif). Si l'enregistrement situé à l'emplacement index n'a pas pu être récupéré, le résultat est placé après le dernier enregistrement si index >= 0 (ou avant le premier enregistrement si index est négatif), et le message false est renvoyé. Si l'enregistrement est récupéré avec succès, true est renvoyé.

Voir aussi next(), previous(), first(), last(), at(), isActive() et isValid().

void QSqlQuery::setForwardOnly(bool forward)

Remplace forwardOnly par forward.

Voir aussi isForwardOnly(), forwardOnly, next() et seek().

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

Remplace numericalPrecisionPolicy par precisionPolicy.

Voir aussi numericalPrecisionPolicy().

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

Remplace positionalBindingEnabled par enable.

Cette fonction a été introduite dans Qt 6.7.

Voir aussi isPositionalBindingEnabled() et positionalBindingEnabled.

int QSqlQuery::size() const

Renvoie la taille du résultat (nombre de lignes renvoyées), ou -1 si la taille ne peut pas être déterminée ou si la base de données ne prend pas en charge la communication d'informations sur la taille des requêtes. Notez que pour les déclarations nonSELECT (isSelect() renvoie false), size() renvoie -1. Si la requête n'est pas active (isActive() renvoie false), -1 est renvoyé.

Pour déterminer le nombre de lignes affectées par une instruction nonSELECT, utilisez numRowsAffected().

Voir également isActive(), numRowsAffected() et QSqlDriver::hasFeature().

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

Remplace cette requête par other. Cette opération est très rapide et n'échoue jamais.

Cette fonction a été introduite dans Qt 6.2.

QVariant QSqlQuery::value(int index) const

Renvoie la valeur du champ index dans l'enregistrement en cours.

Les champs sont numérotés de gauche à droite en utilisant le texte de la déclaration SELECT, par exemple dans

SELECT forename, surname FROM people;

le champ 0 est forename et le champ 1 est surname. L'utilisation de SELECT * n'est pas recommandée car l'ordre des champs dans la requête n'est pas défini.

Une adresse QVariant non valide est renvoyée si la rubrique index n'existe pas, si la requête est inactive ou si la requête est positionnée sur un enregistrement non valide.

Voir aussi previous(), next(), first(), last(), seek(), isActive() et isValid().

QVariant QSqlQuery::value(QAnyStringView name) const

Renvoie la valeur du champ appelé name dans l'enregistrement en cours. Si le champ name n'existe pas, une variante invalide est renvoyée.

Cette surcharge est moins efficace que value()

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

Move-assigne other à cet objet.

Cette fonction a été introduite dans Qt 6.2.