Класс QSqlQuery

Класс QSqlQuery предоставляет средство для выполнения и обработки SQL-запросов. Подробнее...

• Список всех членов, включая унаследованные

Открытые типы

Открытые функции

Подробное описание

QSqlQuery инкапсулирует функциональность, связанную с созданием, навигацией и извлечением данных из SQL-запросов, которые выполняются на QSqlDatabase. Она может быть использована для выполнения операторов DML (язык манипулирования данными), таких как SELECT, INSERT, UPDATE и DELETE, а также операторов DDL (язык определения данных), таких как CREATE TABLE. Она также может быть использована для выполнения баз данных-специфичных команд, которые не являются стандартными SQL (например, SET DATESTYLE=ISO для PostgreSQL).

Успешно выполненные SQL-запросы устанавливают состояние запроса в активное, так что isActive() возвращает true. В противном случае состояние запроса устанавливается в неактивное. В любом случае, при выполнении нового SQL-запроса запрос позиционируется на недействительной записи. Активный запрос должен быть переведён на действительную запись (так что isValid() возвращает true) перед тем, как можно получить значения.

Для некоторых баз данных, если существует активный запрос, который является SELECT оператором, когда вы вызываете commit() или rollback(), выполнение commit или rollback завершится неудачно. Смотрите isActive() для получения подробностей.

Навигация по записям выполняется с помощью следующих функций:

• next()
• previous()
• first()
• last()
• seek()

Эти функции позволяют программисту перемещаться вперёд, назад или произвольно по записям, возвращённым запросом. Если вам нужно перемещаться только вперёд по результатам (например, используя next()), вы можете использовать setForwardOnly(), что сэкономит значительное количество памяти и улучшит производительность на некоторых базах данных. После того как активный запрос позиционирован на действительной записи, данные можно извлечь, используя value(). Все данные передаются из SQL-бекенда с помощью QVariants.

Например:

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

Для доступа к данным, возвращаемым запросом, используйте value(int). Каждый столбец в данных, возвращаемых оператором SELECT, доступен путём передачи позиции столбца в операторе, начиная с 0. Это делает использование запросов SELECT * нежелательным, так как порядок возвращаемых столбцов не определён.

В целях эффективности, нет функций для доступа к столбцу по имени (если вы не используете подготовленные запросы с именами, как описано ниже). Для преобразования имени столбца в индекс, используйте record().indexOf(), например:

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

QSqlQuery поддерживает выполнение подготовленных запросов и привязку значений параметров к плейсхолдерам. Некоторые базы данных не поддерживают эти функции, поэтому Qt эмулирует необходимую функциональность. Например, драйверы Oracle и ODBC имеют надлежащую поддержку подготовленных запросов, и Qt использует её; но для баз данных, которые не имеют этой поддержки, Qt реализует эту функцию самостоятельно, например, подставляя плейсхолдеры фактическими значениями при выполнении запроса. Используйте numRowsAffected() для того, чтобы узнать, сколько строк было затронуто не-SELECT запросом, и size() для того, чтобы узнать, сколько было получено SELECT.

Базы данных Oracle идентифицируют плейсхолдеры, используя синтаксис с двоеточием и именем, например :name. ODBC просто использует символы ?. Qt поддерживает оба синтаксиса, с ограничением, что вы не можете смешивать их в одном запросе.

Вы можете получить значения всех столбцов в одной переменной, используя boundValues().

Примечание: Не все SQL-операции поддерживают привязку значений. Обратитесь к документации вашей системы баз данных, чтобы проверить их доступность.

Подходы к привязке значений

Ниже представлен один и тот же пример, использующий каждый из четырёх различных подходов к привязке, а также один пример привязки значений к хранимой процедуре.

Привязка по имени с использованием именованных плейсхолдеров:

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

Позиционная привязка с использованием именованных плейсхолдеров:

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

Привязка значений с использованием позиционных плейсхолдеров (версия 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();

Привязка значений с использованием позиционных плейсхолдеров (версия 2):

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

Привязка значений к хранимой процедуре:

Этот код вызывает хранимую процедуру под названием AsciiToInt(), передавая ей символ через параметр in и получая результат в параметре 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

Обратите внимание, что свободные параметры сохранят свои значения.

Хранимые процедуры, которые используют оператор return для возврата значений или возвращают несколько наборов результатов, не полностью поддерживаются. Для получения подробной информации см. Драйверы баз данных SQL.

Предупреждение: Вы должны загрузить драйвер SQL и открыть соединение перед созданием объекта QSqlQuery. Кроме того, соединение должно оставаться открытым, пока существует запрос; в противном случае поведение QSqlQuery не определено.

См. также QSqlDatabase, QSqlQueryModel, QSqlTableModel и QVariant.

Документация по типам членов

перечисление QSqlQuery::BatchExecutionMode

Документация по функциям-членам

QSqlQuery::QSqlQuery(const QSqlQuery &other)

Создаёт копию other.

QSqlQuery::QSqlQuery(const QSqlDatabase &db)

Создаёт объект QSqlQuery, используя базу данных db. Если db недействителен, используется базу данных по умолчанию.

См. также QSqlDatabase.

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

Создаёт объект QSqlQuery, используя SQL-запрос query и базу данных db. Если db не указан или недействителен, используется базу данных по умолчанию. Если query не пустая строка, она будет выполнена.

См. также QSqlDatabase.

QSqlQuery::QSqlQuery(QSqlResult *result)

Создаёт объект QSqlQuery, который использует QSqlResult result для взаимодействия с базой данных.

QSqlQuery &QSqlQuery::operator=(const QSqlQuery &other)

Присваивает other этому объекту.

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::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::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.

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

Возвращает список привязанных значений.

Порядок в списке соответствует порядку привязки, независимо от того, используется ли именованная или позиционная привязка.

Значения связей можно проверить следующим образом:

    QVariantList list = query.boundValues();
    for (int i = 0; i < list.size(); ++i)
        cout << i << ": " << list.at(i).toString().toUtf8().data() << "\n";

Эта функция была добавлена в Qt 6.0.

См. также boundValue(), bindValue() и addBindValue().

void QSqlQuery::clear()

Очищает набор результатов и освобождает ресурсы, удерживаемые запросом. Устанавливает состояние запроса в неактивное. Вам редко, если вообще необходимо вызывать эту функцию.

const QSqlDriver *QSqlQuery::driver() const

Возвращает драйвер базы данных, связанный с запросом.

bool QSqlQuery::exec(const QString &query)

Выполняет SQL-запрос в query. Возвращает true, и устанавливает состояние запроса в активное, если запрос был успешным; в противном случае возвращает 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::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::QString);
q.addBindValue(names);

if (!q.execBatch())
    qDebug() << q.lastError();

В приведенном выше примере вставляются четыре новые строки в myTable:

1  Harald
2  Boris
3  Trond
4  NULL

Для привязки значений NULL необходимо добавить нулевой QVariant соответствующего типа в привязанный QVariantList; например, QVariant(QMetaType::QString) следует использовать при работе со строками.

Примечание: Каждый привязанный QVariantList должен содержать одинаковое количество вариантов.

Примечание: Тип QVariants в списке не должен изменяться. Например, нельзя смешивать целые и строковые варианты в пределах QVariantList.

Параметр 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(). Если подготовленный запрос с плейсхолдерами выполняется на СУБД, которая их не поддерживает, подготовка этого запроса эмулируется. Плейсхолдеры в исходном запросе заменяются их привязанными значениями для формирования нового запроса. Эта функция возвращает измененный запрос. Она в основном полезна для отладки.

См. также lastQuery().

void QSqlQuery::finish()

Указывает драйверу базы данных, что больше данных из этого запроса не будет получено до его повторного выполнения. Обычно вызывать эту функцию нет необходимости, но она может быть полезна для освобождения ресурсов, таких как блокировки или курсоры, если вы намерены повторно использовать запрос в будущем.

Устанавливает запрос в неактивное состояние. Привязанные значения сохраняют свои значения.

См. также prepare(), exec() и isActive().

bool QSqlQuery::first()

Получает первую запись в результате, если она доступна, и позиционирует запрос на полученной записи. Обратите внимание, что результат должен находиться в активном состоянии и isSelect() должен возвращать true перед вызовом этой функции, иначе она ничего не сделает и вернет false. Возвращает true при успехе. При неудаче позиция запроса устанавливается в недопустимую, и возвращается false.

См. также next(), previous(), last(), seek(), at(), isActive() и isValid().

bool QSqlQuery::isActive() const

Возвращает true , если запрос активен. Активный QSqlQuery — это тот, который был успешно exec()'d, но еще не завершен. Когда вы закончили работу с активным запросом, вы можете сделать запрос неактивным, вызвав finish() или clear(), или вы можете удалить экземпляр QSqlQuery.

Примечание: Особого внимания заслуживает активный запрос, представляющий собой SELECT утверждение. Для некоторых баз данных, поддерживающих транзакции, активный запрос, являющийся SELECT утверждением, может привести к тому, что commit() или rollback() завершатся неудачей, поэтому перед подтверждением или откатчиком вам следует сделать ваш активный SELECT утверждение запрос неактивным с помощью одного из вышеперечисленных способов.

См. также isSelect().

bool QSqlQuery::isForwardOnly() const

Возвращает true , если вы можете прокручивать результат только вперед; в противном случае возвращает false.

См. также setForwardOnly() и next().

bool QSqlQuery::isNull(int field) const

Возвращает true , если запрос не активен, запрос не расположен на допустимой записи, такого поля field не существует или field имеет значение NULL; в противном случае false. Обратите внимание, что для некоторых драйверов isNull() не будет возвращать точную информацию до попытки извлечения данных.

См. также isActive(), isValid() и value().

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

Это перегруженная функция.

Возвращает true , если нет поля с таким именем name; в противном случае возвращает isNull(int index) для соответствующего индекса поля.

Этот перегруз менее эффективен, чем isNull()

bool QSqlQuery::isSelect() const

Возвращает true , если текущий запрос — это SELECT утверждение; в противном случае возвращает 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

Возвращает идентификатор объекта последней вставленной строки, если база данных это поддерживает. Недопустимый QVariant будет возвращён, если запрос не вставил никакого значения или если база данных не сообщает об идентификаторе. Если более одной строки была затронута вставкой, поведение не определено.

Для баз данных MySQL будет возвращено поле автоинкремента строки.

Примечание: Для работы этой функции в PSQL таблица должна содержать OIDs, которые могут быть не созданы по умолчанию. Проверьте переменную конфигурации default_with_oids , чтобы убедиться.

См. также QSqlDriver::hasFeature().

QString QSqlQuery::lastQuery() const

Возвращает текст текущего запроса или пустую строку, если текущего запроса нет.

См. также executedQuery().

bool QSqlQuery::next()

Извлекает следующую запись в результате, если она доступна, и позиционирует запрос на извлечённую запись. Обратите внимание, что результат должен находиться в активном состоянии (isActive()) и функция 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(), setForwardOnly(), next(), isSelect(), numRowsAffected(), isActive() и lastError().

int QSqlQuery::numRowsAffected() const

Возвращает количество строк, затронутых оператором SQL результата, или -1, если это невозможно определить. Обратите внимание, что для SELECT операторов значение не определено; используйте size() вместо этого. Если запрос не активен (isActive()), возвращается -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()

Извлекает предыдущую запись в результате, если она доступна, и позиционирует запрос на извлечённую запись. Обратите внимание, что результат должен находиться в активном состоянии (isActive()) и функция 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. Обратите внимание, что запрос должен быть в активном состоянии (isActive()) и isSelect() должно возвращать true перед вызовом этой функции.

Если relative равно false (по умолчанию), применяются следующие правила:

• Если index отрицательный, результат позиционируется перед первой записью, и возвращается false.
• В противном случае происходит попытка перейти к записи с позицией index. Если запись с позицией index не может быть извлечена, результат позиционируется после последней записи, и возвращается false. Если запись успешно извлечена, возвращается true.

Если relative равно true, применяются следующие правила:

• Если результат находится перед первой записью и:
  • index отрицательный или нулевой, изменений не происходит, и возвращается false.
  • index положительный, происходит попытка позиционировать результат на абсолютной позиции index - 1, следуя тем же правилам для non relative seek, выше.
• Если результат находится после последней записи и:
  • index положительный или нулевой, изменений не происходит, и возвращается false.
  • index отрицательный, происходит попытка позиционировать результат на позиции index + 1 относительно последней записи, следуя правилу ниже.
• Если результат находится где-то посередине, и относительный сдвиг index перемещает результат ниже нуля, результат позиционируется перед первой записью, и возвращается false.
• В противном случае, происходит попытка перейти к записи, на index позиций вперёд от текущей записи (или на index позиций назад, если index отрицательный). Если запись с таким смещением не может быть извлечена, результат позиционируется после последней записи, если index >= 0, (или перед первой записью, если index отрицательный), и возвращается false. Если запись успешно извлечена, возвращается true.

См. также next(), previous(), first(), last(), at(), isActive() и isValid().

void QSqlQuery::setForwardOnly(bool forward)

Устанавливает режим только вперёд в значение forward. Если forward равно true, разрешены только next() и seek() с положительными значениями для перемещения по результатам.

Режим только вперёд может быть (в зависимости от драйвера) более эффективным с точки зрения памяти, так как результаты не требуется кешировать. Он также повысит производительность в некоторых базах данных. Для этого необходимо вызвать setForwardOnly() до подготовки или выполнения запроса. Обратите внимание, что конструктор, принимающий запрос и базу данных, может выполнить запрос.

Режим только вперёд выключен по умолчанию.

Установка forward only в значение false является предложением для движка базы данных, который имеет последнее слово о том, является ли результат набора данных только forward-only или прокручиваемым. isForwardOnly() всегда будет возвращать правильный статус набора результатов.

Примечание: Вызов setForwardOnly после выполнения запроса приведет, как минимум, к неожиданным результатам, а в худшем случае — к аварийному завершению.

Примечание: Чтобы убедиться, что запрос forward-only был успешно выполнен, приложение должно проверять lastError() на наличие ошибки не только после выполнения запроса, но и после навигации по результатам запроса.

Предупреждение: PostgreSQL: При навигации по результатам запроса в режиме forward-only не выполняйте другие SQL-команды на том же подключении к базе данных. Это приведет к потере результатов запроса.

См. также isForwardOnly(), next(), seek(), и QSqlResult::setForwardOnly().

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

Указывает драйверу базы данных возвращать числовые значения с точностью, заданной параметром precisionPolicy.

Например, драйвер Oracle может извлекать числовые значения в виде строк, чтобы предотвратить потерю точности. Если высокая точность не важна, используйте этот метод для повышения скорости выполнения, минуя преобразования строк.

Примечание: Драйверы, которые не поддерживают извлечение числовых значений с низкой точностью, проигнорируют политику точности. Вы можете использовать QSqlDriver::hasFeature(), чтобы узнать, поддерживает ли драйвер эту функцию.

Примечание: Установка политики точности не влияет на активный запрос. Вызовите exec(QString) или prepare(), чтобы активировать политику.

См. также QSql::NumericalPrecisionPolicy и numericalPrecisionPolicy().

int QSqlQuery::size() const

Возвращает размер результата (количество строк), или -1, если размер определить невозможно или если база данных не поддерживает предоставление информации о размерах запросов. Обратите внимание, что для запросов, не являющихся SELECT, (isSelect() возвращает false), size() вернет -1. Если запрос не активен (isActive() возвращает false), возвращается -1.

Чтобы определить количество строк, затронутых операцией, не являющейся SELECT, используйте numRowsAffected().

См. также isActive(), numRowsAffected(), и QSqlDriver::hasFeature().

QVariant QSqlQuery::value(int index) const

Возвращает значение поля index в текущей записи.

Поля нумеруются слева направо, используя текст оператора SELECT, например, в

SELECT forename, surname FROM people;

поле 0 — forename, а поле 1 — surname. Использование SELECT * не рекомендуется, так как порядок полей в запросе не определён.

Возвращается недействительный QVariant, если поле index не существует, запрос не активен или запрос расположен на недействительной записи.

См. также previous(), next(), first(), last(), seek(), isActive(), и isValid().

QVariant QSqlQuery::value(const QString &name) const

Это перегруженный метод.

Возвращает значение поля с именем name в текущей записи. Если поле name не существует, возвращается недействительный вариант.

Этот перегруз менее эффективен, чем value()