QSqlQuery类

成员函数文档

[显式]QSqlQuery::QSqlQuery(QSqlResult *result)

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

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

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

另请参阅 QSqlDatabase。

[显式构造函数] QSqlQuery::QSqlQuery(const QSqlDatabase &db)

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

另请参阅 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值，请使用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值，请使用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

返回绑定值的列表。

列表的顺序是绑定顺序，无论是否使用命名或位置绑定。

可以通过以下方式检查绑定值。

    const QVariantList 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(const QString &query)

在查询（query）中执行SQL语句。如果查询成功，返回 true 并将查询状态设置为 active；否则返回 false。必须使用被查询SQL数据库适当的语法来书写 query 字符串（例如，标准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::exec()

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

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

另请参见 prepare()，bindValue()，addBindValue()，boundValue() 以及 boundValues()。

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 中添加相关类型的null值；例如，如果你使用字符串，应使用 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()

如果可用，检索结果中的第一条记录，并将查询定位到检索到的记录。请注意，结果必须处于活动状态，并且在调用此函数之前必须返回 true isSelect()，否则它将不执行任何操作并返回 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

如果您只能向前滚动通过结果集，则返回 true；否则返回 false。

另请参阅setForwardOnly()和next。

bool QSqlQuery::isNull(int field) const

如果查询未处于活动状态，或者查询未定位在有效的记录上，不存在这样的字段，或者该字段为空；否则返回false。注意，对于某些驱动程序，在尝试检索数据之后，isNull()才会返回准确信息。

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

bool QSqlQuery::isNull(const QString &name) const

这是一个重载函数。

如果没有字段具有此名称，返回true；否则返回对应字段索引的isNull(int index)。

此重载函数比isNull()效率低。

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

如果当前启用了位置绑定，返回true。

此函数是在Qt 6.7中引入的。

另请参阅setPositionalBindingEnabled()。

bool QSqlQuery::isSelect() const

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

bool QSqlQuery::isValid() const

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

bool QSqlQuery::last()

在结果中检索最后一条记录（如果有的话），并将查询定位在检索到的记录上。注意，结果必须处于活动状态，并且调用此函数之前必须调用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()

如果可用，检索结果中的下一个记录，并将查询定位到检索到的记录。请注意，结果必须在活动状态，并且在调用此函数之前必须返回 true，否则它将什么都不做并返回 false。

以下规则适用

• 如果结果目前位于第一条记录之前，例如查询执行后立即，则尝试检索第一条记录。
• 如果结果目前位于最后一条记录之后，则没有变化，返回 false。
• 如果结果位于中间某个位置，则尝试检索下一条记录。

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

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

bool QSqlQuery::nextResult()

丢弃当前结果集并导航到下一个（如果可用）。

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

如果有一个新的结果集可用，此函数将返回 true。查询将重置到新结果集中的一无效记录，在可以检索数据值之前必须导航到一个有效记录。如果没有新的结果集可用，函数返回 code translate="no">false并将查询设置为非活动状态。在任何情况下，旧的结果集都将被丢弃。

当其中一个语句是非选择语句时，可能可以获得受影响的行数，而不是结果集。

请注意，某些数据库，例如 Microsoft SQL Server，在处理多个结果集时需要非滚动游标。某些数据库可能会一次性执行所有语句，而其他数据库可能会延迟执行，直到结果集实际上被访问，并且某些数据库可能对 SQL 批量中允许使用的语句有约束。

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

int QSqlQuery::numRowsAffected() const

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

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

QSql::NumericalPrecisionPolicy QSqlQuery::numericalPrecisionPolicy() const

返回当前精度策略。

另请参阅 QSql::NumericalPrecisionPolicy 和 setNumericalPrecisionPolicy。

bool QSqlQuery::prepare(const QString &query)

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

查询可能包含用于绑定值的占位符。支持 Oracle样式的点名称（例如，:surname）和 ODBC样式的（?）占位符；但在同一查询中不能混合使用。有关示例，请参阅 详细描述。

兼容性说明：某些数据库选择在第一次执行前延迟准备查询。在这种情况下，准备语法错误的查询会成功，但随后的每个 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();

int nameCol = rec.indexOf("name"); // index of the field "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。注意，查询必须处于一个 活动 状态，并且 isSelect() 必须在调用此函数之前返回 true。

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

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

如果 relative 为真，则适用以下规则

• 如果当前结果定位在第一条记录之前，并且
  • index 为负数或零，则不进行任何更改，并返回 false。
  • index 为正数，将尝试将结果定位到绝对位置 index - 1，遵循上面非相对定位的同一条规则。
• 如果当前结果定位在最后一条记录之后，并且
  • index 为正数或零，则不进行任何更改，并返回 false。
  • index 为负数，则尝试将结果定位到最后记录的 index 相对位置。
• 如果当前结果位于中间某个位置，并且相对偏移 index 将结果移动到零以下，则结果将定位到第一条记录之前，并返回 false。
• 否则，将尝试将记录移动到当前记录前方 index 条（如果 index 为负数，则为当前记录后方 index 条记录）。如果无法检索到偏移 index 的记录，如果 index >= 0，则结果将定位到最后一条记录之后，如果 index 为负数，则结果将定位到第一条记录之前，并返回 false。如果成功检索到记录，则返回 true。

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

void QSqlQuery::setForwardOnly(bool forward)

将只向前进模式设置为 forward。如果 forward 为真，则只允许使用 next() 和正数值的 seek() 来导航结果。

只向前进模式（取决于驱动程序）可以更节省内存，因为不需要缓存结果。它还会提高某些数据库的性能。为了实现这一点，必须在查询准备或执行之前调用 setForwardOnly()。注意，接受查询和数据库的构造函数可能会执行查询。

默认情况下，只向前进模式是关闭的。

将只向前进设置为假是对数据库引擎的建议，数据库引擎有权决定结果集是只向前进的还是可滚动。函数 isForwardOnly() 总是返回结果集的正确状态。

另请参阅：isForwardOnly()、next()、seek()、和 QSqlResult::setForwardOnly。

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

指导数据库驱动以由 precisionPolicy 指定的精度返回数值。

例如，Oracle 驱动可以以字符串形式检索数值以防止精度丢失。如果高精度并不重要，可以使用此方法通过跳过字符串转换来提高执行速度。

注意：不支持以低精度获取数值的驱动将忽略精度策略。您可以使用 QSqlDriver::hasFeature() 来检查驱动是否支持此功能。

注意：设置精度策略不会影响当前活动的查询。请调用 exec(QString) 或 prepare() 以激活策略。

另请参阅：QSql::NumericalPrecisionPolicy 和 numericalPrecisionPolicy。

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

根据 enable（默认值为 true）启用或禁用此查询的定位 绑定。禁用定位绑定很有用，如果查询本身包含一个 '?'，则不应将其处理为定位绑定参数，例如，作为 PostgreSQL 数据库的 JSON 运算符。

当数据库具有对带有问号的位置绑定的本地支持时（另请参阅 QSqlDriver::PositionalPlaceholders），此函数将不会产生任何效果。

此函数是在Qt 6.7中引入的。

另请参阅：isPositionalBindingEnabled。

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(const QString &name) const

这是一个重载函数。

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

此重载比 value() 效率低。

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

将 other 移动分配给此对象。

此功能自Qt 6.2开始引入。