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

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

另请参阅 QSqlDatabase 。

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

从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

返回查询的当前内部位置。第一条记录位于位置零处。如果位置无效，该函数将返回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 处的绑定值name。

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

该函数在 Qt 6.6 中引入。

另请参阅 boundValueNames()。

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

返回所有已绑定值的名称。

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

该函数在 Qt 6.6 中引入。

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

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

返回一个绑定值的列表。

该列表的顺序遵循绑定顺序，无论使用的是命名绑定还是位置绑定。

可以通过以下方式检查已绑定的值：

   constQVariantList list=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 。

示例：

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

上面的示例将四行新数据插入到myTable 中：

1  Harald
2  Boris
3  Trond
4  NULL

要绑定 NULL 值，必须将相关类型的空QVariant 添加到已绑定的QVariantList 中；例如，如果使用字符串，则应使用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 ，并且查询将设为非活动状态。无论哪种情况，旧的结果集都将被丢弃。

当其中一条语句为非 SELECT 语句时，可能会返回受影响的行数，而非结果集。

请注意，某些数据库（例如 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

返回 numericalPrecisionPolicy。

另请参阅 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() 来获取某列的索引。

QSqlQuery q("select * from employees");
QSqlRecord rec=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 为正数，则尝试将结果定位在绝对位置index - 1，遵循上述针对非相对寻址的相同规则。
• 如果结果当前位于最后一条记录之后，且：
  • index 该值为正数或零，则不进行任何更改，并返回 false。
  • index 为负数，则尝试将结果定位在距最后一条记录index + 1的相对位置处，遵循下述规则。
• 如果结果当前位于中间某处，且相对偏移量 `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)

该函数将 `other ` 移入并赋值给该对象。

该函数自 Qt 6.2 起引入。