int sqlite3_stmt_explain(sqlite3_stmt *pStmt, int eMode);
sqlite3_stmt_explain(S,E) 介面會變更已準備敘述 S 的 EXPLAIN 設定。如果 E 為零,則 S 將成為一般的已準備敘述。如果 E 為 1,則 S 的行為如同其 SQL 文字以「EXPLAIN」開頭。如果 E 為 2,則 S 的行為如同其 SQL 文字以「EXPLAIN QUERY PLAN」開頭。
呼叫 sqlite3_stmt_explain(S,E) 可能會導致 S 重新準備。SQLite 會嘗試避免重新準備,但在第一次轉換到 EXPLAIN 或 EXPLAIN QUERY PLAN 模式時,可能需要重新準備。
由於可能需要重新準備,如果 S 無法重新準備,則呼叫 sqlite3_stmt_explain(S,E) 將會以 SQLITE_ERROR 失敗,因為它是使用 sqlite3_prepare() 而不是較新的 sqlite3_prepare_v2() 或 sqlite3_prepare_v3() 介面建立的,因此沒有儲存的 SQL 文字可用於重新準備。
變更已準備敘述的 explain 設定並不會變更敘述的原始 SQL 文字。因此,如果 SQL 文字原本以 EXPLAIN 或 EXPLAIN QUERY PLAN 開頭,但呼叫 sqlite3_stmt_explain(S,0) 將敘述轉換為一般敘述,即使敘述現在的行為像一般 SQL 敘述,EXPLAIN 或 EXPLAIN QUERY PLAN 關鍵字仍會出現在 sqlite3_sql(S) 輸出中。
如果 explain 模式成功變更,此常式會傳回 SQLITE_OK;如果 explain 模式無法變更,則會傳回錯誤碼。在敘述作用中時,無法變更 explain 模式。因此,良好的做法是在呼叫 sqlite3_stmt_explain(S,E) 之前立即呼叫 sqlite3_reset(S)。