QSqlQuery Class

メンバ関数ドキュメント

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

QSqlResult result を使用してデータベースと通信する QSqlQuery オブジェクトを構築します。

[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() を呼び出した後に、プレースホルダはデータベースからのデータで上書きされます。

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)

プリペアド・ステートメントの値val にバインドされるプレースホルダplaceholder を設定する。プレースホルダ名を指定する際には、プレースホルダ・マーク（例：: ）を含めなければならないことに注意してください。paramType がQSql::Out またはQSql::InOut の場合、exec() を呼び出した後、プレースホルダはデータベースからのデータで上書きされます。この場合、結果を格納するのに十分な領域をあらかじめ確保しておかなければならない。

NULL値をバインドするには、NULLQVariant を使用します。例えば、文字列をバインドする場合は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()

事前に準備された 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 に4つの新しい行を挿入している：

1  Harald
2  Boris
3  Trond
4  NULL

QVariant(QMetaType::fromType<QString>()) NULL値をバインドするには、関連する型のNULLQVariant をバインドされたQVariantList に追加しなければならない。

mode パラメータは、バインドされたQVariantList がどのように解釈されるかを示します。mode がValuesAsRows の場合、QVariantList 内のすべてのバリアントは新しい行の値として解釈されます。ValuesAsColumns は Oracle ドライバの特殊なケースです。このモードでは、QVariantList 内の各エントリーは、ストアドプロシージャ内の IN または OUT 値の配列値として解釈されます。このモードは、IN値またはOUT値が基本型の1つの列のみからなるテーブル型である場合にのみ動作することに注意してください。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 が返されます。

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 が NULL の場合は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()

可能であれば、結果の最後のレコードを取得し、取得したレコード上にクエリを配置します。この関数を呼び出す前に、result がactive の状態にあり、isSelect() が true を返していなければなりません。成功した場合は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が返される。レコードの取得に成功した場合は true が返される。

previous()、first()、last()、seek()、at()、isActive()、isValid()も参照のこと 。

bool QSqlQuery::nextResult()

現在の結果セットを破棄し、利用可能な場合は次の結果セットに移動します。

データベースによっては、ストアドプロシージャやSQLバッチ（複数の文を含む問い合わせ文字列）に対して複数の結果セットを返すことができます。クエリ実行後に複数の結果セットが利用可能な場合、この関数を使用して次の結果セットに移動することができます。

新しい結果セットが利用可能な場合、この関数は true を返します。クエリは新しい結果セット内の無効なレコードに再配置され、データ値を取得する前に有効なレコードに移動する必要があります。新しい結果セットが利用できない場合、この関数はfalse を返し、クエリは非アクティブに設定されます。いずれの場合も、古い結果セットは破棄されます。

文の1つが非選択文である場合、結果セットの代わりに、影響を受ける行のカウントが利用できるかもしれません。

Microsoft SQL Serverなど一部のデータベースでは、複数の結果セットを扱う際にスクロールできないカーソルが必要です。データベースによっては、全てのステートメントを一度に実行するものもあれば、結果セットに実際にアクセスするまで実行を遅らせるものもあります。

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では、クエリ文字列には一度に1つの文しか含めることができません。複数の文が指定された場合、この関数は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() が真を返していなければなりません。

以下のルールが適用される：

• 結果が現在最初のレコードの前にある場合、変更はなく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 になります。この関数を呼び出す前に、クエリがactive の状態になっていて、isSelect() が true を返していなければならないことに注意してください。

relative が偽（デフォルト）の場合、以下のルールが適用される：

• 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- このオブジェクトにother を割り当てます。

この関数は Qt 6.2 で導入されました。