Sur cette page

QSqlQuery Class

La classe QSqlQuery permet d'exécuter et de manipuler des instructions SQL. En savoir plus...

En-tête : #include <QSqlQuery>
CMake : find_package(Qt6 REQUIRED COMPONENTS Sql)
target_link_libraries(mytarget PRIVATE Qt6::Sql)
qmake : QT += sql

Types publics

enum BatchExecutionMode { ValuesAsRows, ValuesAsColumns }

Propriétés

Fonctions publiques

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)

Description détaillée

QSqlQuery encapsule les fonctionnalités liées à la création, à la navigation et à la récupération de données à partir de requêtes SQL exécutées sur une QSqlDatabase. Il peut être utilisé pour exécuter des instructions DML (langage de manipulation de données), telles que « SELECT », « INSERT », « UPDATE » et « DELETE », ainsi que des instructions DDL (langage de définition de données), telles que « CREATE » et « TABLE ». Il peut également être utilisé pour exécuter des commandes spécifiques à une base de données qui ne font pas partie du SQL standard (par exemple, « SET DATESTYLE=ISO » pour PostgreSQL).

Les instructions SQL exécutées avec succès définissent l’état de la requête sur « actif », de sorte que la fonction ` isActive()` renvoie ` true`. Dans le cas contraire, l’état de la requête est défini sur « inactif ». Dans les deux cas, lors de l’exécution d’une nouvelle instruction SQL, la requête est positionnée sur un enregistrement non valide. Une requête active doit être orientée vers un enregistrement valide (de sorte que isValid() renvoie true) avant que les valeurs puissent être récupérées.

Pour certaines bases de données, si une requête active de type « SELECT » existe au moment où vous appelez ` commit()` ou ` rollback()`, la validation (commit) ou l'annulation (rollback) échouera. Voir ` isActive()` pour plus de détails.

La navigation entre les enregistrements s’effectue à l’aide des fonctions suivantes :

Ces fonctions permettent au programmeur de se déplacer vers l’avant, vers l’arrière ou de manière arbitraire parmi les enregistrements renvoyés par la requête. Si vous avez uniquement besoin de vous déplacer vers l’avant dans les résultats (par exemple, en utilisant next()), vous pouvez utiliser setForwardOnly(), ce qui permettra d’économiser une quantité importante de mémoire et d’améliorer les performances sur certaines bases de données. Une fois qu’une requête active est positionnée sur un enregistrement valide, les données peuvent être récupérées à l’aide de value(). Toutes les données sont transférées depuis le backend SQL à l’aide de QVariants.

Par exemple :

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

Pour accéder aux données renvoyées par une requête, utilisez `value(int)`. L'accès à chaque champ des données renvoyées par une instruction ` SELECT ` s'effectue en passant la position du champ dans l'instruction, en partant de 0. Il est donc déconseillé d'utiliser des requêtes de type ` SELECT * `, car l'ordre des champs renvoyés est indéterminé.

Pour des raisons d'efficacité, il n'existe aucune fonction permettant d'accéder à un champ par son nom (à moins d'utiliser des requêtes préparées avec des noms, comme expliqué ci-dessous). Pour convertir un nom de champ en index, utilisez ` record()`. `indexOf()`, par exemple :

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

QSqlQuery prend en charge l’exécution de requêtes préparées et la liaison de valeurs de paramètres à des espaces réservés. Certaines bases de données ne prennent pas en charge ces fonctionnalités ; dans ce cas, Qt émule les fonctionnalités requises. Par exemple, les pilotes Oracle et ODBC prennent correctement en charge les requêtes préparées, et Qt en tire parti ; mais pour les bases de données qui ne disposent pas de cette prise en charge, Qt implémente lui-même cette fonctionnalité, par exemple en remplaçant les espaces réservés par des valeurs réelles lors de l’exécution d’une requête. Utilisez ` numRowsAffected()` pour connaître le nombre de lignes concernées par une requête non préparée (`non-SELECT `), et ` size()` pour connaître le nombre de lignes récupérées par une requête préparée (` SELECT`).

Les bases de données Oracle identifient les espaces réservés à l’aide d’une syntaxe « deux-points-nom », par exemple :name. ODBC utilise simplement les caractères ?. Qt prend en charge les deux syntaxes, à condition de ne pas les mélanger dans une même requête.

Vous pouvez récupérer les valeurs de tous les champs dans une seule variable à l’aide de ` boundValues()`.

Remarque : toutes les opérations SQLne prennentpas en charge la liaison de valeurs. Reportez-vous à la documentation de votre système de base de données pour vérifier leur disponibilité.

Approches de la liaison de valeurs

Nous présentons ci-dessous le même exemple en utilisant chacune des quatre approches de liaison différentes, ainsi qu'un exemple de liaison de valeurs à une procédure stockée.

Liaison nommée à l'aide de placeholders nommés :

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

Liaison par position à l'aide de placeholders nommés :

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

Liaison de valeurs à l’aide de placeholders positionnels (version 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();

Liaison de valeurs à l'aide d'espaces réservés positionnels (version 2) :

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

Liaison de valeurs à une procédure stockée :

Ce code appelle une procédure stockée nommée AsciiToInt(), en lui transmettant un caractère via son paramètre « in » et en récupérant son résultat dans le paramètre « 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

Notez que les paramètres non liés conserveront leurs valeurs.

Les procédures stockées qui utilisent l'instruction `RETURN` pour renvoyer des valeurs, ou qui renvoient plusieurs ensembles de résultats, ne sont pas entièrement prises en charge. Pour plus de détails, consultez la section « Pilotes de base de données SQL ».

Avertissement : vous devez charger le pilote SQL et ouvrir la connexion avant de créer un objet QSqlQuery. De plus, la connexion doit rester ouverte tant que la requête existe ; sinon, le comportement de QSqlQuery est indéfini.

Voir également QSqlDatabase, QSqlQueryModel, QSqlTableModel et QVariant.

Documentation sur les types de membres

enum QSqlQuery::BatchExecutionMode

ConstanteValeurDescription
QSqlQuery::ValuesAsRows0- Met à jour plusieurs lignes. Considère chaque entrée d’une « QVariantList » comme une valeur permettant de mettre à jour la ligne suivante.
QSqlQuery::ValuesAsColumns1- Met à jour une seule ligne. Traite chaque entrée d'une « QVariantList » comme une valeur unique de type tableau.

Documentation sur les propriétés

[since 6.8] forwardOnly : bool

Cette propriété définit le mode « forward only ». Si la valeur de « forward » est « true », seules les méthodes ` next()` et ` seek()` avec des valeurs positives sont autorisées pour parcourir les résultats.

Le mode « forward only » peut (selon le pilote) permettre une meilleure gestion de la mémoire, car les résultats n’ont pas besoin d’être mis en cache. Il améliore également les performances sur certaines bases de données. Pour que cela soit effectif, vous devez appeler ` setForwardOnly() ` avant que la requête ne soit préparée ou exécutée. Notez que le constructeur qui prend en paramètre une requête et une base de données peut exécuter la requête.

Le mode « forward only » est désactivé par défaut.

Définir `forward only` sur `false` constitue une suggestion à l'intention du moteur de base de données, qui a le dernier mot quant à savoir si un jeu de résultats est en mode « forward only » ou si le défilement est autorisé. La fonction ` isForwardOnly()` renverra toujours le statut correct du jeu de résultats.

Remarque : l'appel de ` setForwardOnly ` après l'exécution de la requête entraînera, au mieux, des résultats inattendus et, au pire, des plantages.

Remarque : pour s’assurer que la requête en mode « forward-only » s’est terminée avec succès, l’application doit vérifier si lastError() renvoie une erreur non seulement après l’exécution de la requête, mais également après avoir parcouru les résultats de la requête.

Avertissement : PostgreSQL : lors de la navigation dans les résultats de la requête en mode « forward-only », n’exécutez aucune autre commande SQL sur la même connexion à la base de données. Cela entraînerait la perte des résultats de la requête.

Cette énumération a été introduite dans Qt 6.8.

Fonctions d’accès :

bool isForwardOnly() const
void setForwardOnly(bool forward)

Voir également ` next()` et ` seek()`.

[since 6.8] numericalPrecisionPolicy : QSql::NumericalPrecisionPolicy

Configurez le pilote de base de données pour qu'il renvoie les valeurs numériques avec une précision définie par ` precisionPolicy`.

Le pilote Oracle, par exemple, peut récupérer des valeurs numériques sous forme de chaînes de caractères afin d’éviter toute perte de précision. Si une précision élevée n’est pas nécessaire, utilisez cette méthode pour augmenter la vitesse d’exécution en contournant les conversions en chaînes de caractères.

Remarque : les pilotes qui ne prennent pas en charge la récupération de valeurs numériques avec une faible précision ignoreront la politique de précision. Vous pouvez utiliser ` QSqlDriver::hasFeature()` pour vérifier si un pilote prend en charge cette fonctionnalité.

Remarque : la configuration de la politique de précision n’affecte pas la requête actuellement active. Appelez exec(QString) ou prepare() pour activer la politique.

Cette énumération a été introduite dans Qt 6.8.

Fonctions d’accès :

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

Voir également QSql::NumericalPrecisionPolicy, QSqlDriver::numericalPrecisionPolicy et QSqlDatabase::numericalPrecisionPolicy.

[since 6.8] positionalBindingEnabled : bool

Cette propriété active ou désactive l'binding positionnelle pour cette requête, en fonction de la valeur de « enable » (la valeur par défaut est « true »). La désactivation des liaisons positionnelles est utile si la requête elle-même contient un « ? » qui ne doit pas être traité comme un paramètre de liaison positionnelle, mais, par exemple, comme un opérateur JSON pour une base de données PostgreSQL.

Cette propriété n'aura aucun effet lorsque la base de données prend en charge nativement les liaisons positionnelles avec des points d'interrogation (voir également QSqlDriver::PositionalPlaceholders).

Cette énumération a été introduite dans Qt 6.8.

Fonctions d'accès :

Documentation des fonctions membres

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

Crée un objet QSqlQuery qui utilise le moteur de requêtes QSqlResult result pour communiquer avec une base de données.

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

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

Voir également QSqlDatabase.

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

Crée un objet QSqlQuery à partir de l'query SQL et de l'db de la base de données. Si db n'est pas spécifié ou n'est pas valide, la base de données par défaut de l'application est utilisée. Si query n'est pas une chaîne vide, elle sera exécutée.

Voir également QSqlDatabase.

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

Crée un objet QSqlQuery à partir d'other.

Cette fonction a été introduite dans Qt 6.2.

[noexcept] QSqlQuery::~QSqlQuery()

Détruit l'objet et libère toutes 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 valeurs par position. 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 écrasé par les données de la base de données après l’appel à exec().

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

Voir également 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 également previous(), next(), first(), last(), seek(), isActive() et isValid().

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

Définissez l'placeholder de l'espace réservé de manière à ce qu'il soit lié à la valeur val dans l'instruction préparée. Notez que le marqueur de paramètre (par exemple :) doit être inclus lors de la spécification du nom du paramètre. Si paramType est QSql::Out ou QSql::InOut, le paramètre sera remplacé par les données de la base de données après l’appel à exec(). Dans ce cas, un espace suffisant doit être préalloué pour stocker le résultat.

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

Voir également addBindValue(), prepare(), exec(), boundValue() et boundValues().

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

Définissez le paramètre de remplacement à la position pos pour qu'il soit associé à la valeur val dans l'instruction préparée. La numérotation des champs commence à 0. Si paramType correspond à QSql::Out ou QSql::InOut, le paramètre de remplacement sera remplacé par les données de la base de données après l'appel à exec().

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

Renvoie la valeur associée à l'placeholder.

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

QVariant QSqlQuery::boundValue(int pos) const

Renvoie la valeur associée à l'espace réservé situé à 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 correspond à l'ordre de liaison, que la liaison soit nominale 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 correspond à l'ordre de liaison, que la liaison soit nominale ou positionnelle.

Cette fonction a été introduite dans Qt 6.6.

Voir également boundValues() et boundValueName().

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

Renvoie une liste de valeurs liées.

L'ordre de la liste correspond à l'ordre de liaison, que la liaison soit nominale 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 également boundValue(), bindValue(), addBindValue() et boundValueNames().

void QSqlQuery::clear()

Efface le jeu de résultats et libère toutes les ressources utilisées par la requête. Met la requête en état « inactif ». Vous ne devriez que très 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éalablement préparée. Renvoie ` true ` si la requête s'est exécutée avec succès ; sinon, renvoie ` false`.

Notez que la dernière erreur associée à cette requête est réinitialisée lors de l'appel de la fonction exec().

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

bool QSqlQuery::exec(const QString &query)

Exécute la requête SQL contenue dans ` query`. Renvoie ` true ` et définit l'état de la requête sur ` active ` si la requête a abouti ; sinon, renvoie ` false`. La chaîne ` query ` doit respecter la syntaxe appropriée à la base de données SQL interrogée (par exemple, le SQL standard).

Une fois la requête exécutée, le curseur se trouve sur un enregistrement non valide et doit être déplacé vers un enregistrement valide avant que les valeurs des données puissent être récupérées (par exemple, à l’aide de ` next()`).

Notez que la dernière erreur associée à cette requête est réinitialisée lors de l’appel de la fonction exec().

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.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 en mode batch. 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 en mode batch, le pilote simulera ce comportement à l'aide d'appels classiques de type ` exec()`.

Renvoie ` true ` si la requête s'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, il faut ajouter une QVariant vide du type correspondant à l'QVariantList; par exemple, il faut utiliser QVariant(QMetaType::fromType<QString>()) si vous utilisez des chaînes de caractères.

Remarque : chaque QVariantList liée doit contenir le même nombre de variantes.

Remarque : le type des QVariants d’une liste ne doit pas changer. Par exemple, vous ne pouvez pas mélanger des variantes de type entier et de type chaîne de caractères au sein d’une QVariantList.

Le paramètre mode indique comment l’ QVariantList lié sera interprété. Si mode est ValuesAsRows, chaque variante de l’ QVariantList sera interprétée comme une valeur pour une nouvelle ligne. ValuesAsColumns est un cas particulier pour le pilote Oracle. Dans ce mode, chaque entrée d’un QVariantList sera interprétée comme une valeur de tableau pour une valeur IN ou OUT au sein d’une procédure stockée. Notez que cela ne fonctionnera que si la valeur IN ou OUT est un type de table 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 qui a été exécutée avec succès.

Dans la plupart des cas, cette fonction renvoie la même chaîne de caractères que ` lastQuery()`. Si une requête préparée contenant des espaces réservés est exécutée sur un SGBD qui ne prend pas en charge cette fonctionnalité, la préparation de cette requête est émulée. Les espaces réservés de la requête d'origine sont remplacés par leurs valeurs associées afin de former une nouvelle requête. Cette fonction renvoie la requête modifiée. Elle est principalement utile à des fins de débogage.

Voir également lastQuery().

void QSqlQuery::finish()

Indique au pilote de base de données qu’aucune autre donnée ne sera récupérée à partir de cette requête tant qu’elle n’aura pas été réexécutée. Il n’est généralement pas nécessaire d’appeler cette fonction, mais cela peut s’avérer utile pour libérer des ressources telles que des verrous ou des curseurs si vous prévoyez de réutiliser la requête ultérieurement.

Met la requête en état inactif. Les valeurs liées conservent leurs valeurs.

Voir également prepare(), exec() et isActive().

bool QSqlQuery::first()

Récupère le premier enregistrement du résultat, s'il existe, et positionne la requête sur cet enregistrement. Notez que le résultat doit être dans l'état « active » et que la fonction « isSelect() » doit renvoyer « true » avant d'appeler cette fonction ; sinon, celle-ci 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 sur une position non valide et « false » est renvoyé.

Voir également 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é exécutée avec succès via ` exec()` mais qui n'est pas encore terminée. Lorsque vous avez terminé avec une requête active, vous pouvez la désactiver en appelant ` finish()` ou ` clear()`, ou bien supprimer l'instance ` QSqlQuery `.

SELECT Remarque : les requêtes actives de type « SELECT »présentent un intérêt particulier. Dans certaines bases de données prenant en charge les transactions, une requête active de type « SELECT » peut entraîner l’échec des appels ` commit()` ou ` rollback()`. Avant de valider (commit) ou d’annuler (rollback) une transaction, vous devez donc désactiver votre requête active de type « » en utilisant l’une des méthodes indiquées ci-dessus.

Voir également isSelect().

bool QSqlQuery::isForwardOnly() const

Renvoie forwardOnly.

Remarque : fonctionde lecture pour la propriété forwardOnly.

Voir également forwardOnly, next() et seek().

bool QSqlQuery::isNull(int field) const

Renvoie ` true ` si la requête n'est pas de type ` active`, si la requête n'est pas positionnée sur un enregistrement valide, si l'adresse ` field` n'existe pas ou si l'adresse ` field ` est nulle ; dans le cas contraire, renvoie ` false`. Notez que pour certains pilotes, la fonction `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'existe aucun champ portant cette name; sinon, renvoie `isNull(int index)` pour l'index du champ correspondant.

Cette surcharge est moins efficace que isNull()

Remarque : dans les versions de Qt antérieures à la version 6.8, cette fonction prenait en paramètre QString et non QAnyStringView.

Il s'agit d'une fonction surchargée.

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

Renvoie positionalBindingEnabled.

Remarque : fonctionde lecture pour la propriété 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 instruction « 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 existe, et positionne la requête sur cet enregistrement. Notez que le résultat doit être dans l'état « active » et que la fonction « isSelect() » doit renvoyer « true » avant d'appeler cette fonction ; sinon, celle-ci 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 sur une position non valide et « false » est renvoyé.

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

QSqlError QSqlQuery::lastError() const

Renvoie des informations sur la dernière erreur (le cas échéant) survenue lors de cette requête.

Voir également QSqlError et QSqlDatabase::lastError().

QVariant QSqlQuery::lastInsertId() const

Renvoie l'identifiant (ID) de l'objet correspondant à la dernière ligne insérée, si la base de données le prend en charge. Une erreur « QVariant » sera renvoyée si la requête n'a inséré aucune valeur ou si la base de données ne renvoie pas l'identifiant. Si l'insertion a concerné plusieurs lignes, le comportement n'est pas défini.

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

Remarque : pour que cette fonction fonctionne dans PSQL, la table doit contenir des OID, qui ne sont pas nécessairement créés par défaut. Vérifiez la variable de configuration default_with_oids pour vous en assurer.

Voir également QSqlDriver::hasFeature().

QString QSqlQuery::lastQuery() const

Renvoie le texte de la requête actuellement utilisée, ou une chaîne vide s'il n'y a pas de texte de requête.

Voir aussi executedQuery().

bool QSqlQuery::next()

Récupère l'enregistrement suivant dans le résultat, s'il existe, et positionne la requête sur l'enregistrement récupéré. Notez que le résultat doit être dans l'état « active » et que la fonction ` isSelect()` doit renvoyer `true` avant d'appeler cette fonction ; sinon, celle-ci 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, le système tente de récupérer le premier enregistrement.
  • Si le résultat se trouve actuellement après le dernier enregistrement, aucun changement n’est effectué et la valeur false est renvoyée.
  • Si le résultat se trouve quelque part au milieu, le système tente de récupérer l’enregistrement suivant.

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

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

bool QSqlQuery::nextResult()

Supprime le jeu de résultats actuel et passe au suivant, s'il en existe un.

Certaines bases de données sont capables de renvoyer plusieurs ensembles de résultats pour des procédures stockées ou des 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 au(x) ensemble(s) de résultats suivant(s).

Si un nouvel ensemble de résultats est disponible, cette fonction renvoie « true ». La requête sera repositionnée sur un enregistrement non valide 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 aucun nouvel ensemble de résultats n’est disponible, la fonction renvoie « false » et la requête est mise en état inactif. Dans tous les cas, l’ancien ensemble de résultats sera supprimé.

Lorsqu’une des instructions n’est pas une instruction SELECT, un nombre de lignes affectées peut être disponible à la place d’un jeu de résultats.

Notez que certaines bases de données, par exemple Microsoft SQL Server, exigent l’utilisation de curseurs non défilables lors de l’utilisation de plusieurs ensembles de résultats. Certaines bases de données peuvent exécuter toutes les instructions en une seule fois, tandis que d’autres peuvent retarder l’exécution jusqu’à ce que l’ensemble de résultats soit effectivement consulté ; certaines bases de données peuvent également imposer des restrictions quant aux instructions autorisé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 est impossible de le déterminer. Notez que pour les instructions de type « SELECT », la valeur n'est pas définie ; utilisez plutôt la fonction « size() ». Si la requête n'est pas de type « active », la fonction renvoie -1.

Voir également size() et QSqlDriver::hasFeature().

QSql::NumericalPrecisionPolicy QSqlQuery::numericalPrecisionPolicy() const

Renvoie la propriété `numericalPrecisionPolicy`.

Remarque : fonctiongetter pour la propriété numericalPrecisionPolicy.

Voir aussi setNumericalPrecisionPolicy().

bool QSqlQuery::prepare(const QString &query)

Prépare la requête SQL query en vue de son 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 la liaison de valeurs. Les espaces réservés de type Oracle (deux points suivis d’un nom, par exemple :surname) et de type ODBC (?) sont tous deux pris en charge ; toutefois, ils ne peuvent pas être mélangés dans une même requête. Consultez la page Detailed Description pour des exemples.

Remarques sur la portabilité : certaines bases de données choisissent de retarder la préparation d’une requête jusqu’à sa première exécution. Dans ce cas, la préparation d’une requête syntaxiquement incorrecte aboutit, mais chaque appel consécutif à exec() échouera. Lorsque la base de données ne prend pas directement en charge les placeholders nommés, le placeholder ne peut contenir que des caractères de l’ensemble [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 la fonction isSelect() doit renvoyer «true» avant d'appeler cette fonction, sinon celle-ci ne fera rien et renverra «false».

Les règles suivantes s'appliquent :

  • Si le résultat se trouve actuellement avant le premier enregistrement, aucun changement n'est effectué et la valeur false est renvoyée.
  • Si le résultat se trouve actuellement après le dernier enregistrement, le programme tente de récupérer le dernier enregistrement.
  • Si le résultat se trouve quelque part au milieu, une tentative est effectuée pour récupérer l’enregistrement précédent.

Si l’enregistrement n’a pas pu être récupéré, le résultat est positionné avant le premier enregistrement et la valeur « false » est renvoyée. Si l’enregistrement est récupéré avec succès, la valeur « true » est renvoyée.

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

QSqlRecord QSqlQuery::record() const

Renvoie un objet ` QSqlRecord ` contenant les informations relatives aux champs de la requête en cours. Si la requête pointe vers une ligne valide (la fonction `isValid()` renvoie `true`), l'objet est renseigné avec les valeurs de cette ligne. Un objet vide est renvoyé lorsqu'il n'y a pas de requête active (la fonction `isActive()` renvoie `false`).

Pour récupérer les valeurs d'une requête, il est recommandé d'utiliser ` value()` car sa recherche par 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, la fonction ` QSqlRecord::indexOf()` est utilisée 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 également 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 situé à la position index, s'il est disponible, et positionne la requête sur l'enregistrement récupéré. Le premier enregistrement se trouve à la position 0. Notez que la requête doit être à l'état « active » et que la fonction isSelect() doit renvoyer «true» avant d'appeler cette fonction.

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

  • Si index est négatif, le résultat est positionné avant le premier enregistrement et la valeur false est renvoyée.
  • Sinon, le programme tente de se positionner sur l’enregistrement situé à la position index. Si l’enregistrement situé à la position index n’a pas pu être récupéré, le résultat est positionné après le dernier enregistrement et 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égative ou nulle, il n’y a pas de changement et la valeur « false » est renvoyée.
    • index est positif, le système tente de positionner le résultat à la position absolue index - 1, en suivant les mêmes règles que pour la recherche non relative, décrites ci-dessus.
  • Si le résultat est actuellement positionné après le dernier enregistrement et :
    • index est positif ou égal à zéro, il n'y a pas de changement et la valeur « false » est renvoyée.
    • index est négative, on tente de 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 se trouve actuellement quelque part au milieu, et que le décalage relatif index le place en dessous de zéro, le résultat est positionné avant le premier enregistrement et la valeur « false » est renvoyée.
  • Sinon, on tente de se déplacer vers l’enregistrement situé à index enregistrements en avant de l’enregistrement actuel (ou à index enregistrements en arrière de l’enregistrement actuel si index est négatif). Si l’enregistrement situé à l’offset index n’a pas pu être récupéré, le résultat est positionné après le dernier enregistrement si index >= 0 (ou avant le premier enregistrement si index est négatif), et la valeur « false » est renvoyée. Si l’enregistrement est récupéré avec succès, la valeur « true » est renvoyée.

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

void QSqlQuery::setForwardOnly(bool forward)

Définit la propriété forwardOnly sur forward.

Remarque : fonctionde définition pour la propriété forwardOnly.

Voir également isForwardOnly(), forwardOnly, next() et seek().

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

Définit la propriété « numericalPrecisionPolicy » sur « precisionPolicy ».

Remarque : fonctionde définition de la propriété numericalPrecisionPolicy.

Voir également numericalPrecisionPolicy().

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

Définit la propriété « positionalBindingEnabled » sur « enable ».

Remarque : fonctionde définition de la propriété positionalBindingEnabled.

Cette fonction a été introduite dans Qt 6.7.

Voir également 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 fourniture d'informations sur la taille des requêtes. Notez que pour les instructions non de type `SELECT ` (la fonction `isSelect()` renvoie ` false`), la fonction `size()` renvoie -1. Si la requête n’est pas active (la fonction `isActive()` renvoie ` false`), la valeur -1 est renvoyée.

Pour déterminer le nombre de lignes affectées par une instruction non «SELECT », 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 ne rate 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 actuel.

Les champs sont numérotés de gauche à droite en fonction du texte de l'instruction « SELECT », par exemple dans

SELECT forename, surname FROM people;

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

Un QVariant non valide est renvoyé si le champ index n’existe pas, si la requête est inactive ou si la requête est positionnée sur un enregistrement non valide.

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

QVariant QSqlQuery::value(QAnyStringView name) const

Renvoie la valeur du champ nommé « name » dans l'enregistrement actuel. Si le champ « name » n'existe pas, une variante non valide est renvoyée.

Cette surcharge est moins efficace que value()

Remarque : dans les versions de Qt antérieures à la version 6.8, cette fonction prenait en paramètre « QString », et non « QAnyStringView ».

Il s'agit d'une fonction surchargée.

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

La fonction « move-assign » attribue « other » à cet objet.

Cette fonction a été introduite dans 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.