QSqlQuery Class

成员函数文档

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

构造一个 QSqlQuery 对象，该对象使用QSqlResult result 与数据库通信。

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

使用数据库db 构建 QSqlQuery 对象。如果db 无效，将使用应用程序的默认数据库。

另请参阅 QSqlDatabase 。

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

使用 SQLquery 和数据库db 构造一个 QSqlQuery 对象。如果db 未指定或无效，则使用应用程序的默认数据库。如果query 不是空字符串，则将执行该查询。

另请参阅 QSqlDatabase 。

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

Move-从other 构造一个 QSqlQuery。

该函数在 Qt 6.2 中引入。

[noexcept] QSqlQuery::~QSqlQuery()

销毁对象并释放已分配的资源。

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

在使用位置值绑定时，将值val 添加到值列表中。addBindValue()调用的顺序决定了在准备好的查询中将值绑定到哪个占位符。如果paramType 是QSql::Out 或QSql::InOut ，那么在调用exec() 后，占位符将被数据库中的数据覆盖。

要绑定 NULL 值，请使用空QVariant ；例如，如果要绑定字符串，请使用QVariant(QMetaType::fromType<QString>()) 。

另请参阅 bindValue(),prepare(),exec(),boundValue() 和boundValues().

int QSqlQuery::at() const

返回查询的当前内部位置。第一条记录位于 0 位置。如果位置无效，函数将返回QSql::BeforeFirstRow 或QSql::AfterLastRow 这两个特殊的负值。

另请参阅 previous()、next()、first()、last()、seek()、isActive() 和isValid()。

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

将占位符placeholder 设置为与准备语句中的值val 绑定。请注意，在指定占位符名称时必须包含占位符标记（如: ）。如果paramType 是QSql::Out 或QSql::InOut ，在调用exec() 后，占位符将被数据库中的数据覆盖。在这种情况下，必须预先分配足够的空间来存储结果。

要绑定 NULL 值，请使用空QVariant ；例如，如果要绑定字符串，请使用QVariant(QMetaType::fromType<QString>()) 。

另请参阅 addBindValue(),prepare(),exec(),boundValue() 和boundValues().

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

将pos 位置的占位符设置为与准备语句中的val 值绑定。字段编号从 0 开始。如果paramType 是QSql::Out 或QSql::InOut ，在调用exec() 后，占位符将被数据库中的数据覆盖。

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

返回placeholder 的值。

另请参阅 boundValues()、bindValue() 和addBindValue()。

QVariant QSqlQuery::boundValue(int pos) const

返回位置pos 上占位符的值。

另请参阅 boundValues() 。

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

返回位置pos 上的绑定值名称。

无论使用的是命名绑定还是位置绑定，列表的顺序都是按绑定顺序排列的。

此函数在 Qt 6.6 中引入。

另请参阅 boundValueNames()。

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

返回所有绑定值的名称。

无论使用的是命名绑定还是位置绑定，列表的顺序均为绑定顺序。

此函数在 Qt 6.6 中引入。

另请参阅 boundValues() 和boundValueName()。

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

返回绑定值列表。

无论使用的是命名绑定还是位置绑定，列表的顺序都是按绑定顺序排列的。

绑定值可按以下方式检查：

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

该函数在 Qt 6.0 中引入。

另请参见 boundValue()、bindValue()、addBindValue() 和boundValueNames()。

void QSqlQuery::clear()

清除结果集并释放查询所持有的任何资源。将查询状态设置为非活动。很少需要调用此函数。

const QSqlDriver *QSqlQuery::driver() const

返回与查询相关的数据库驱动程序。

bool QSqlQuery::exec()

执行事先准备好的 SQL 查询。如果查询成功执行，则返回true ；否则返回false 。

请注意，在调用 exec() 时，该查询的最后一次错误会被重置。

另请参阅 prepare()、bindValue()、addBindValue()、boundValue() 和boundValues()。

bool QSqlQuery::exec(const QString &query)

执行query 中的 SQL。如果查询成功，则返回true 并将查询状态设置为active ；否则返回false 。query 字符串必须使用适合所查询 SQL 数据库的语法（例如，标准 SQL）。

执行查询后，查询会被定位在一条无效记录上，必须在检索数据值之前导航到一条有效记录（例如，使用next()) 。

请注意，在调用 exec() 时，该查询的最后一个错误会被重置。

对于 SQLite，查询字符串一次只能包含一条语句。如果给出的语句超过一条，函数将返回false 。

示例：

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

另请参阅 isActive(),isValid(),next(),previous(),first(),last() 和seek() 。

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

批量执行事先准备好的 SQL 查询。所有绑定参数必须是变量列表。如果数据库不支持批量执行，驱动程序将使用传统的exec() 调用来模拟批量执行。

如果查询成功执行，则返回true ；否则返回false 。

示例

QSqlQueryq; q.prepare("insert into myTable values (?, ?)")；QVariantListints; ints<< 1<< 2<< 3<< 4; q.addBindValue(ints)；QVariantListnames；names<< "Harald"<< "Boris"<< "Trond"<<QVariant(QMetaType::fromType<QString>()); q.addBindValue(names);if(!q.execBatch())    qDebug() << q.lastError();

上面的示例在myTable 中插入了四条新记录：

1  Harald
2  Boris
3  Trond
4  NULL

要绑定 NULL 值，必须在绑定的QVariantList 中添加相关类型的 nullQVariant ；例如，如果使用字符串，则应使用QVariant(QMetaType::fromType<QString>()) 。

mode 参数表示如何解释绑定的QVariantList 。如果mode 是ValuesAsRows ，则QVariantList 中的每个变量都将被解释为新行的值。ValuesAsColumns 是 Oracle 驱动程序的一种特殊情况。在这种模式下，QVariantList 中的每个条目都将被解释为存储过程中 IN 或 OUT 值的数组值。请注意，这只有在 IN 或 OUT 值是仅由一列基本类型组成的表类型时才有效，例如TYPE myType IS TABLE OF VARCHAR(64) INDEX BY BINARY_INTEGER;

另请参阅 prepare()、bindValue() 和addBindValue()。

QString QSqlQuery::executedQuery() const

返回最后一次成功执行的查询。

在大多数情况下，该函数返回与lastQuery() 相同的字符串。如果在不支持占位符的 DBMS 上执行带占位符的准备查询，则会模拟该查询的准备过程。原始查询中的占位符将被替换为其绑定值，从而形成一个新的查询。该函数将返回修改后的查询。它主要用于调试目的。

另请参见 lastQuery()。

void QSqlQuery::finish()

指示数据库驱动程序在重新执行查询之前不再从该查询中获取数据。通常情况下无需调用此函数，但如果以后打算重新使用查询，调用此函数可能有助于释放锁或游标等资源。

将查询设置为非活动。绑定值保留其值。

另请参阅 prepare()、exec() 和isActive()。

bool QSqlQuery::first()

检索结果中的第一条记录（如果有的话），并将查询定位在检索到的记录上。请注意，在调用此函数前，结果必须处于active 状态，且isSelect() 必须返回 true，否则将不起作用并返回 false。如果成功，则返回true 。如果不成功，查询位置将被设置为无效位置，并返回 false。

另请参见 next()、previous()、last()、seek()、at()、isActive() 和isValid()。

bool QSqlQuery::isActive() const

如果查询处于活动状态，则返回true 。活动的QSqlQuery 是指已成功exec() 但尚未结束的查询。完成活动查询后，可以通过调用finish() 或clear() 使查询处于非活动状态，也可以删除QSqlQuery 实例。

另请参阅 isSelect()。

bool QSqlQuery::isForwardOnly() const

返回forwardOnly 。

另请参阅 forwardOnly,next() 和seek() 。

bool QSqlQuery::isNull(int field) const

如果查询不是active 、查询未定位在有效记录上、没有这样的field 或field 为空，则返回true ；否则返回false 。请注意，对于某些驱动程序，isNull() 在尝试检索数据后才会返回准确信息。

另请参阅 isActive()、isValid() 和value()。

bool QSqlQuery::isNull(QAnyStringView name) const

这是一个重载函数。

如果name 中没有字段，则返回true ；否则返回相应字段索引的 isNull(int index)。

此重载函数的效率低于isNull()

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

返回positionalBindingEnabled 。

此函数在 Qt 6.7 中引入。

另请参阅 positionalBindingEnabled 。

bool QSqlQuery::isSelect() const

如果当前查询是SELECT 语句，则返回true ；否则返回false 。

bool QSqlQuery::isValid() const

如果查询当前位于有效记录上，则返回true ；否则返回false 。

bool QSqlQuery::last()

检索结果中的最后一条记录（如果有的话），并将查询定位在检索到的记录上。请注意，在调用此函数前，结果必须处于active 状态，且isSelect() 必须返回 true，否则将不起作用并返回 false。如果成功，则返回true 。如果不成功，查询位置将被设置为无效位置，并返回 false。

另请参见 next()、previous()、first()、seek()、at()、isActive() 和isValid()。

QSqlError QSqlQuery::lastError() const

返回上次查询出错（如果有）的错误信息。

另请参阅 QSqlError 和QSqlDatabase::lastError()。

QVariant QSqlQuery::lastInsertId() const

如果数据库支持，则返回最近插入记录的对象 ID。如果查询没有插入任何值，或者数据库不返回 ID，则将返回无效的QVariant 。如果插入操作涉及多条记录，则行为未定义。

对于 MySQL 数据库，将返回行的自动递增字段。

另请参阅 QSqlDriver::hasFeature().

QString QSqlQuery::lastQuery() const

返回当前使用的查询文本，如果没有当前查询文本，则返回空字符串。

另请参阅 executedQuery()。

bool QSqlQuery::next()

检索结果中的下一条记录（如果有的话），并将查询定位在检索到的记录上。需要注意的是，在调用此函数之前，结果必须处于active 状态，且isSelect() 必须返回 true，否则它将什么也不做并返回 false。

以下规则适用：

• 如果结果当前位于第一条记录之前，例如在执行查询后，会立即尝试检索第一条记录。
• 如果结果当前位于最后一条记录之后，则不会有任何变化，并返回 false。
• 如果结果位于中间位置，则会尝试检索下一条记录。

如果无法检索到记录，结果将位于最后一条记录之后，并返回 false。如果成功检索到记录，则返回 true。

另请参阅 previous()、first()、last()、seek()、at()、isActive() 和isValid()。

bool QSqlQuery::nextResult()

丢弃当前结果集，如果可用，则跳转到下一个结果集。

某些数据库能够为存储过程或 SQL 批量（包含多条语句的查询字符串）返回多个结果集。如果执行查询后有多个结果集可用，则可使用此函数导航到下一个或多个结果集。

如果有新的结果集可用，该函数将返回 true。查询将被重新定位到新结果集中的一条无效记录上，必须在检索数据值之前导航到一条有效记录。如果没有新的结果集，函数将返回false ，查询将被设置为非活动。无论如何，旧的结果集将被丢弃。

当其中一条语句是非选择语句时，可能会提供受影响行的计数，而不是结果集。

请注意，某些数据库（如 Microsoft SQL Server）在处理多个结果集时要求使用不可滚动游标。有些数据库可能会一次性执行所有语句，而有些数据库可能会延迟执行，直到实际访问结果集时才执行，有些数据库可能对允许在 SQL 批次中使用的语句有限制。

另请参阅 QSqlDriver::hasFeature(),forwardOnly,next(),isSelect(),numRowsAffected(),isActive() 和lastError() 。

int QSqlQuery::numRowsAffected() const

返回受结果 SQL 语句影响的行数，如果无法确定，则返回-1。请注意，对于SELECT 语句，该值是未定义的；请使用size() 代替。如果查询不是active ，则返回-1。

另请参阅 size() 和QSqlDriver::hasFeature()。

QSql::NumericalPrecisionPolicy QSqlQuery::numericalPrecisionPolicy() const

返回数值精度策略。

另请参阅 setNumericalPrecisionPolicy().

bool QSqlQuery::prepare(const QString &query)

准备执行 SQL 查询query 。如果查询准备成功，则返回true ；否则返回false 。

查询可能包含绑定值占位符。支持 Oracle 样式的冒号名称（如:surname ）和 ODBC 样式的占位符 (?)，但不能在同一查询中混合使用。有关示例，请参阅Detailed Description 。

可移植性说明：有些数据库会将准备查询的时间推迟到第一次执行查询时。在这种情况下，准备语法错误的查询会成功，但每个连续的exec() 都会失败。当数据库不直接支持命名占位符时，占位符只能包含 [a-zA-Z0-9_] 范围内的字符。

对于 SQLite，查询字符串一次只能包含一条语句。如果给出多条语句，函数将返回false 。

示例：

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

另请参阅 exec()、bindValue() 和addBindValue()。

bool QSqlQuery::previous()

检索结果中的前一条记录（如果有），并将查询定位在检索到的记录上。需要注意的是，在调用此函数前，结果必须处于active 状态，且isSelect() 必须返回 true，否则它将什么也不做并返回 false。

以下规则适用：

• 如果结果当前位于第一条记录之前，则不会有任何变化，并返回 false。
• 如果结果当前位于最后一条记录之后，则会尝试检索最后一条记录。
• 如果结果位于中间位置，则尝试检索前一条记录。

如果无法检索到记录，则将结果置于第一条记录之前，并返回 false。如果成功检索到记录，则返回 true。

另请参阅 next()、first()、last()、seek()、at()、isActive() 和isValid()。

QSqlRecord QSqlQuery::record() const

返回一个QSqlRecord ，其中包含当前查询的字段信息。如果查询指向一条有效的记录（isValid() 返回 true），则会用该行的值填充该记录。如果没有活动查询（isActive() 返回 false），则返回空记录。

要从查询中获取值，应使用value()，因为其基于索引的查找速度更快。

在下面的示例中，执行了SELECT * FROM 查询。由于没有定义列的顺序，QSqlRecord::indexOf() 用于获取列的索引。

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

intnameCol=rec.indexOf("name");// 字段 "name"的索引while(q.next())    qDebug() << q.value(nameCol).toString(); // output all names

另请参见 value().

const QSqlResult *QSqlQuery::result() const

返回与查询相关的结果。

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

检索位于index 位置的记录（如果有），并将查询定位在检索到的记录上。第一条记录位于位置 0。请注意，在调用此函数前，查询必须处于active 状态，且isSelect() 必须返回 true。

如果relative 为 false（默认值），则适用以下规则：

• 如果index 为负数，查询结果将被放置在第一条记录之前，并返回 false。
• 否则，将尝试移动到位置index 的记录。如果无法检索到位置index 的记录，则将结果置于最后一条记录之后，并返回 false。如果成功检索到记录，则返回 true。

如果relative 为 true，则适用以下规则：

• 如果结果当前位于第一条记录之前，且
  • index 为负数或零，则没有变化，并返回 false。
  • index 为正值，则会尝试将结果定位在绝对位置 - 1，并遵循上述非相对查找的相同规则。index
• 如果结果当前位于最后一条记录之后，且
  • index 为正值或零，则不会有任何变化，并返回 false。
  • index 为负数，则会尝试将结果定位在 + 1 的相对位置，与最后一条记录保持一致，具体规则如下。index
• 如果结果当前位于中间位置，且相对偏移量index 将结果移动到零以下，则将结果定位到第一条记录之前，并返回 false。
• 否则，将尝试移动到当前记录前面的记录index （如果index 为负数，则移动到当前记录后面的记录index ）。如果无法检索到偏移量index 处的记录，如果index >= 0，则将结果定位在最后一条记录之后（如果index 为负数，则定位在第一条记录之前），并返回 false。如果成功检索到记录，则返回 true。

另请参阅 next(),previous(),first(),last(),at(),isActive() 和isValid() 。

void QSqlQuery::setForwardOnly(bool forward)

将forwardOnly 设置为forward 。

另请参阅 isForwardOnly(),forwardOnly,next() 和seek() 。

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

将numericalPrecisionPolicy 设置为precisionPolicy 。

另请参阅 numericalPrecisionPolicy() 。

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

将positionalBindingEnabled 设置为enable 。

该函数在 Qt 6.7 中引入。

另请参阅 isPositionalBindingEnabled() 和positionalBindingEnabled 。

int QSqlQuery::size() const

返回结果的大小（返回的行数），如果无法确定大小或数据库不支持报告查询大小信息，则返回-1。请注意，对于非SELECT 语句（isSelect() 返回false ），size() 将返回-1。如果查询未激活（isActive() 返回false ），则返回-1。

要确定受非SELECT 语句影响的行数，请使用numRowsAffected()。

另请参阅 isActive()、numRowsAffected() 和QSqlDriver::hasFeature()。

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

将此查询与other 互换。该操作速度非常快，而且不会失败。

该函数在 Qt 6.2 中引入。

QVariant QSqlQuery::value(int index) const

返回当前记录中index 字段的值。

字段从左到右编号，使用SELECT 语句的文本，如

SELECT forename, surname FROM people;

字段 0 是forename ，字段 1 是surname 。不建议使用SELECT * ，因为查询中字段的顺序是未定义的。

如果字段index 不存在、查询处于非活动状态或查询位于无效记录上，则会返回无效的QVariant 。

另请参阅 previous()、next()、first()、last()、seek()、isActive() 和isValid()。

QVariant QSqlQuery::value(QAnyStringView name) const

这是一个重载函数。

返回当前记录中名为name 的字段的值。如果字段name 不存在，则返回无效变量。

此重载函数的效率低于value()

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

Move-assignsother 到此对象。

此函数在 Qt 6.2 中引入。