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

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値をバインドするには、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 をNULLに設定します。たとえば、文字列をバインドする場合はQVariant(QMetaType::fromType<QString>()) を使用します。

関連項目： addBindValue()、prepare()、exec()、boundValue()、およびboundValues()。

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

プレパードステートメント内の値val にバインドされるよう、位置pos のプレースホルダーを設定します。フィールドの番号付けは 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 の場合、クエリ文字列には一度に 1 つのステートメントしか含めることができません。複数のステートメントが指定された場合、この関数は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

NULL値をバインドするには、バインドされた`QVariantList`に、該当する型のNULL対応の`QVariant `を追加する必要があります。たとえば、文字列を使用する場合は`QVariant(QMetaType::fromType<QString>()) `を使用する必要があります。

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が返されます。成功した場合は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()

結果に含まれる最後のレコード（存在する場合）を取得し、クエリの位置を取得したレコードに設定します。この関数を呼び出す前に、結果が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 の場合、クエリ文字列には一度に 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() が 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 で導入されました。