ODBC ドライバー API サポート

Snowflake ODBC ドライバーは、 ODBC API のバージョン3.52をサポートしています。このトピックでは、Snowflakeに関連する ODBC ルーチンをリストし、それらがサポートされているかどうかを示します。ルーチンは、実行する機能に基づいてカテゴリに分類されます。

完全な API リファレンスについては、 Microsoft ODBC プログラマーズリファレンス をご参照ください。

このトピックの内容:

データソースへの接続

関数名

サポート対象

メモ

SQLAllocHandle

SQLConnect

SQLDriverConnect

SQLAllocEnv

Snowflakeドライバーによりサポートされていますが、 ODBC API バージョン3.xでは非推奨です。

SQLAllocConnect

Snowflakeドライバーによりサポートされていますが、 ODBC API バージョン3.xでは非推奨です。

SQLBrowseConnect

ドライバーおよびデータソースに関する情報の取得

関数名

サポート対象

メモ

SQLDataSources

SQLDrivers

SQLGetInfo

SQLGetFunctions

SQLGetTypeInfo

ドライバー属性の設定および取得

関数名

サポート対象

メモ

SQLSetConnectAttr

SQL_ATTR_METADATA_ID の設定は、 SQLTables 関数と SQLColumns 関数のみに影響します(他の サポートされているカタログ関数 には影響なし)。

SQLGetConnectAttr

読み取り専用モードはサポートされていません。SQL_MODE_READ_ONLY はドライバーに渡されますが、Snowflakeは引き続きデータベースに書き込みます。 . . また、 API バージョン3.52以降でいくつかの属性が導入されました。SQL_ATTR_ASYNC_DBC_EVENT、 SQL_ATTR_ASYNC_DBC_FUNCTIONS_ENABLE、 SQL_ATTR_ASYNC_DBC_PCALLBACK、 SQL_ATTR_ASYNC_DBC_PCONTEXT、 SQL_ATTR_DBC_INFO_TOKEN。

SQLSetConnectOption

Snowflakeドライバーによりサポートされていますが、 ODBC API バージョン3.xでは非推奨です。

SQLGetConnectOption

Snowflakeドライバーによりサポートされていますが、 ODBC API バージョン3.xでは非推奨です。

SQLSetEnvAttr

SQLGetEnvAttr

SQL_ATTR_CONNECTION_POOLING 属性は、 ODBCAPI バージョン3.52の後に導入されており、サポートされていません。

SQLSetStmtAttr

SQL_ATTR_CURSOR_SCROLLABLE only supports a SQL_NONSCROLLABLE value. . SQL_ATTR_USE_BOOKMARKS only supports a SQL_UB_OFF value. . . For compatibility with third-party tools, SQL_ATTR_ENABLE_AUTO_IPD defaults to true, even though the ODBC standard says it should default to false. . . Setting SQL_ATTR_METADATA_ID only affects the SQLTables and SQLColumns functions (and not the other supported catalog functions). . . Unsupported attributes: SQL_ATTR_SIMULATE_CURSOR, SQL_ATTR_FETCH_BOOKMARK_PTR, SQL_ATTR_KEYSET_SIZE.

SQLGetStmtAttr

標準属性に加えて、Snowflake実装は属性 SQL_SF_STMT_ATTR_LAST_QUERY_ID をサポートします。これにより、ユーザーは指定されたステートメントハンドルに関連付けられた最新のクエリ ID を取得できます。部分的な例は、以下の セクションに記載されています。

SQLSetStmtOption

Snowflakeドライバーによりサポートされていますが、 ODBC API バージョン3.xでは非推奨です。 SQLSetStmtAttr に置き換えられました。

SQLGetStmtOption

Snowflakeドライバーによりサポートされていますが、 ODBC API バージョン3.xでは非推奨です。 SQLGetStmtAttr に置き換えられました。

SQLParamOptions

Snowflakeドライバーによりサポートされていますが、 ODBC API バージョン3.xでは非推奨です。 SQLSetStmtAttr に置き換えられました。

上記の各関数には、ワイド文字(Unicode)を受け入れる対応する関数があります。そのような各Unicode関数には、上記の名前の後に「W」が付いています。例えば、3番目のパラメーターとしてchar配列を受け入れる関数 SQLGetStmtAttr には、3番目のパラメーターとしてwchar配列を受け入れる SQLGetStmtAttrW という名前の対応する関数があります。

Snowflake固有の動作

  • SQLSetConnectAttr

    このメソッドは、次の2つのSnowflake固有の属性をサポートしています。

    属性名

    説明

    SQL_SF_CONN_ATTR_APPLICATION

    これにより、レジストリまたは.iniファイルの APPLICATION 設定で指定された値が上書きされます。

    SQL_SF_CONN_ATTR_PRIV_KEY

    これは、プライベートキーのメモリ内コピーを指す EVP_PKEY*ポインターです。これにより、レジストリまたは.iniファイルの PRIV_KEY_FILE および PRIV_KEY_PWD 設定が上書きされます。Snowflakeは、この属性を使用して秘密キーを設定することをお勧めします。

記述子フィールドの設定および取得

関数名

サポート対象

メモ

SQLGetDescField

SQLGetDescRec

SQLSetDescField

SQLSetDescRec

SQL リクエストの準備

関数名

サポート対象

メモ

SQLAllocStmt

Snowflakeドライバーによりサポートされていますが、 ODBC API バージョン3.xでは非推奨です。

SQLBindParameter

SQLPrepare

SQLGetCursorName

SQLSetCursorName

SQLSetScrollOptions

Snowflakeドライバーによりサポートされていますが、 ODBC API では非推奨です。

SQLSetParam

Snowflakeドライバーによりサポートされていますが、 ODBC API バージョン2.xでは非推奨です。 SQLBindParameter に置き換えられました。

注釈

バインドできるデータのサイズには上限があります。詳細については、 クエリテキストサイズの制限 をご参照ください。

リクエストの送信

関数名

サポート対象

メモ

SQLExecute

SQLExecDirect

SQLNativeSql

SQLDescribeParam

パラメーターにバインドされているデータ型に関係なく、Snowflakeはサーバー側の変換を実行し、最大長が16777216の VARCHAR を返します。

SQLNumParams

SQLParamData

ストリーミングはサポートされていないため、サポート対象外です。

SQLPutData

ストリーミングはサポートされていないため、サポート対象外です。

結果および結果に関する情報の取得

関数名

サポート対象

メモ

SQLBindCol

SQLError

Snowflakeドライバーによりサポートされていますが、 ODBC API バージョン3.xでは非推奨です。 SQLGetDiagRec に置き換えられました。

SQLGetData

SQLGetDiagField

SQLGetDiagRec

SQLRowCount

SQLNumResultCols

SQLDescribeCol

SQLColAttribute

SQLColAttributes

Snowflakeドライバーによりサポートされていますが、 ODBC API バージョン2.xでは非推奨です。 SQLColAttribute に置き換えられました。

SQLFetch

SQLFetchScroll

FetchOrientation 引数は SQL_FETCH_NEXT 値のみをサポートします。他のすべてのタイプのフェッチは失敗します。

SQLExtendedFetch

API バージョン3.xドライバーで、 SQLFetchScroll に置き換えられました。

SQLSetPos

Snowflakeはこの機能をサポートしていません。

SQLBulkOperations

Snowflakeはこの機能をサポートしていません。

データソースのシステムテーブルに関する情報の取得(カタログ関数)

関数名

サポート対象

メモ

SQLColumnPrivileges

空の結果セットを返します。

SQLColumns

SQLForeignKeys

SQLPrimaryKeys

SQLProcedureColumns

空の結果セットを返します。

SQLProcedures

Snowflakeには手続き型言語がないため、この関数は空の結果セットを返します。

SQLSpecialColumns

空の結果セットを返します。

SQLStatistics

空の結果セットを返します。

SQLTablePrivileges

空の結果セットを返します。

SQLTables

関数に渡されるパラメーターが「TABLE」の場合、関数は一時テーブルや仮テーブルを含むすべてのタイプのテーブルを返します。 . . 関数に渡されるパラメーターが「VIEW」の場合、関数はマテリアライズドビューを含むすべてのタイプのビューを返します。 . . 関数に渡されるパラメーターが「TABLE、VIEW」または「%」の場合、関数はすべてのタイプのテーブルとすべてのタイプのビューに関する情報を返します。

カタログ関数に渡された名前に無効な文字がある場合、または名前がどのデータベースオブジェクトとも一致しない場合、関数は空の結果セットを返します。

SQL_ATTR_METADATA_ID の設定は、 SQLTables 関数と SQLColumns 関数のみに影響します。

ステートメントの終了

関数名

サポート対象

メモ

SQLFreeStmt

SQLCloseCursor

SQLCancel

SQLEndTran

SQLTransact

Snowflakeドライバーによりサポートされていますが、 ODBC API バージョン3.xでは非推奨です。 SQLEndTran に置き換えられました。

接続の終了

関数名

サポート対象

メモ

SQLCancelHandle

バージョン3.52以後の API に導入されました。

SQLDisconnect

SQLFreeHandle

SQLFreeConnect

Snowflakeドライバーによりサポートされていますが、 ODBC API バージョン3.xでは非推奨です。

SQLFreeEnv

Snowflakeドライバーによりサポートされていますが、 ODBC API バージョン3.xでは非推奨です。

その他の関数

関数名

サポート対象

メモ

SQLCompleteAsync

バージョン3.52以後の API に導入されました。

カスタム SQL データ型

Snowflakeでサポートされている一部の SQL データ型には、 ODBC に直接マッピングがありません(例:TIMESTAMP_*tz、 VARIANT)。サポートされていないデータ型で ODBC ドライバーを使用できるようにするために、ドライバーに付属のヘッダーファイルには、次のカスタムデータ型の定義が含まれています。

////////////////////////////////////////////////////////////////////////////////////////////////////
/// Custom SQL Data Type Definition
///
///
////////////////////////////////////////////////////////////////////////////////////////////////////

#define SQL_SF_TIMESTAMP_LTZ 2000
#define SQL_SF_TIMESTAMP_TZ  2001
#define SQL_SF_TIMESTAMP_NTZ 2002
#define SQL_SF_ARRAY         2003
#define SQL_SF_OBJECT        2004
#define SQL_SF_VARIANT       2005

次のコードは、カスタムデータ型の使用例を示しています。

// bind insert as timestamp_ntz
SQLRETURN rc;
rc = SQLPrepare(odbc.StmtHandle,
               (SQLCHAR *) "insert into testtimestampntz values (?)",
               SQL_NTS);

 SQL_TIMESTAMP_STRUCT bindData;
 SQLLEN datalen = sizeof(SQL_TIMESTAMP_STRUCT);
 bindData.year = 2017;
 bindData.month = 11;
 bindData.day = 30;
 bindData.hour = 18;
 bindData.minute = 17;
 bindData.second = 5;
 bindData.fraction = 123456789;

 rc = SQLBindParameter(
   odbc.StmtHandle, 1, SQL_PARAM_INPUT,
   SQL_C_TIMESTAMP, SQL_SF_TIMESTAMP_NTZ,
   100, 0, &bindData, sizeof(bindData), &datalen);

 rc = SQLExecute(odbc.StmtHandle);

 // query table
 rc = SQLExecDirect(odbc.StmtHandle, (SQLCHAR *)"select * from testtimestampntz", SQL_NTS);

 rc = SQLFetch(odbc.StmtHandle);

 // fetch data as timestamp
 SQL_TIMESTAMP_STRUCT ret;
 SQLLEN retLen = (SQLLEN) 0;
 rc = SQLGetData(odbc.StmtHandle, 1, SQL_C_TIMESTAMP, &ret, (SQLLEN)sizeof(ret), &retLen);

このセクションでは、APIの使用例を示します。

最後のクエリ IDの取得

最後のクエリ ID の取得は、 ODBC 標準のSnowflake拡張機能です。

最後のクエリ ID を取得するには、関数 SQLGetStmtAttr (または SQLGetStmtAttrW)を呼び出し、属性 SQL_SF_STMT_ATTR_LAST_QUERY_ID とクエリ ID を保持するのに十分な大きさの文字配列を渡します。

以下の例は、クエリのクエリ ID を取得する方法を示しています。

// Space to store the query ID.
// The SQLGetStmtAttr() function fills this in with the actual ID.
char queryId[37];   // Maximum 36 chars plus string terminator.

// The length (in characters) of the query ID. The SQLGetStmtAttr() function fills this in
// with the actual length of the query ID (usually 36).
SQLINTEGER idLen;

// Execute a query.
rc = SQLExecDirect(odbc.StmtHandle, (SQLCHAR *) "select 1", SQL_NTS);

// Retrieve the query ID (queryId) and the length of that query ID (idLen).
SQLGetStmtAttr(odbc.StmtHandle, SQL_SF_STMT_ATTR_LAST_QUERY_ID, queryId, sizeof(queryId), &idLen);

Linuxまたは macOSで実行している場合は、 SQLGetStmtAttrW を呼び出して、適切なデータ型のパラメーター(たとえば、「char」ではなく「wchar」)を渡します。