API-Unterstützung für ODBC-Treiber

Der Snowflake ODBC-Treiber unterstützt die Version 3.52 der ODBC-API. Unter diesem Thema werden die für Snowflake relevanten ODBC-Routinen aufgelistet und angezeigt, ob sie unterstützt werden. Die Routinen sind in Kategorien eingeteilt, die auf der Grundlage der von ihnen ausgeführten Funktion erstellt wurden.

Die vollständige API-Referenz finden Sie in der Microsoft ODBC-Programmierreferenz.

Unter diesem Thema:

Verbinden mit einer Datenquelle

Funktionsname

Unterstützt

Anmerkungen

SQLAllocHandle

SQLConnect

SQLDriverConnect

SQLAllocEnv

Wird vom Snowflake-Treiber unterstützt, ist aber in ODBC-API-Version 3.x veraltet.

SQLAllocConnect

Wird vom Snowflake-Treiber unterstützt, ist aber in ODBC-API-Version 3.x veraltet.

SQLBrowseConnect

Abrufen von Informationen zu einem Treiber und einer Datenquelle

Funktionsname

Unterstützt

Anmerkungen

SQLDataSources

SQLDrivers

SQLGetInfo

SQLGetFunctions

SQLGetTypeInfo

Einstellen und Abrufen von Treiberattributen

Funktionsname

Unterstützt

Anmerkungen

SQLSetConnectAttr

Das Festlegen von SQL_ATTR_METADATA_ID wirkt sich nur auf die Funktionen SQLTables und SQLColumns aus (und nicht auf die anderen unterstützten Katalogfunktionen).

SQLGetConnectAttr

Der Nur-Lese-Modus wird nicht unterstützt. SQL_MODE_READ_ONLY wird an den Treiber übergeben, aber Snowflake schreibt immer noch in die Datenbank. . . Außerdem wurden einige Attribute nach API-Version 3.52 eingeführt: 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

Wird vom Snowflake-Treiber unterstützt, ist aber in ODBC-API-Version 3.x veraltet.

SQLGetConnectOption

Wird vom Snowflake-Treiber unterstützt, ist aber in ODBC-API-Version 3.x veraltet.

SQLSetEnvAttr

SQLGetEnvAttr

Das SQL_ATTR_CONNECTION_POOLING-Attribut wurde nach ODBC-API in Version 3.52 eingeführt und wird nicht unterstützt.

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

Zusätzlich zu den Standardattributen unterstützt die Snowflake-Implementierung das Attribut SQL_SF_STMT_ATTR_LAST_QUERY_ID, mit dem der Benutzer die letzte Abfrage-ID abrufen kann, die dem angegebenen Anweisungshandle zugeordnet ist. Ein unvollständiges Beispiel finden Sie unten im Abschnitt Beispiele.

SQLSetStmtOption

Wird vom Snowflake-Treiber unterstützt, ist aber in ODBC-API-Version 3.x veraltet. Ersetzt durch SQLSetStmtAttr.

SQLGetStmtOption

Wird vom Snowflake-Treiber unterstützt, ist aber in ODBC-API-Version 3.x veraltet. Ersetzt durch SQLGetStmtAttr.

SQLParamOptions

Wird vom Snowflake-Treiber unterstützt, ist aber in ODBC-API-Version 3.x veraltet. Ersetzt durch SQLSetStmtAttr.

Jede der vorhergehenden Funktionen hat eine entsprechende Funktion, die breite Zeichen (Unicode) akzeptiert. Jede solche Unicode-Funktion hat den oben gezeigten Namen, gefolgt von „W“. Beispielsweise hat die Funktion SQLGetStmtAttr, die ein char-Array als dritten Parameter akzeptiert, eine entsprechende Funktion mit dem Namen SQLGetStmtAttrW, die ein wchar-Array als dritten Parameter akzeptiert.

Snowflake-spezifisches Verhalten

  • SQLSetConnectAttr

    Diese Methode unterstützt zwei Snowflake-spezifische Attribute:

    Attributname

    Beschreibung

    SQL_SF_CONN_ATTR_APPLICATION

    Dies überschreibt den Wert, der durch die Einstellung APPLICATION in der Registrierungs- oder INI-Datei angegeben wird.

    SQL_SF_CONN_ATTR_PRIV_KEY

    Dies ist ein EVP_PKEY*-Zeiger, der auf eine speicherinterne Kopie des privaten Schlüssels verweist. Dadurch werden die Einstellungen PRIV_KEY_FILE und PRIV_KEY_PWD in der Registrierung oder der INI-Datei überschrieben. Snowflake empfiehlt, dieses Attribut zum Festlegen des privaten Schlüssels zu verwenden.

Einstellen und Abrufen von Deskriptorfeldern

Funktionsname

Unterstützt

Anmerkungen

SQLGetDescField

SQLGetDescRec

SQLSetDescField

SQLSetDescRec

Vorbereitung von SQL-Anforderungen

Funktionsname

Unterstützt

Anmerkungen

SQLAllocStmt

Wird vom Snowflake-Treiber unterstützt, ist aber in ODBC-API-Version 3.x veraltet.

SQLBindParameter

SQLPrepare

SQLGetCursorName

SQLSetCursorName

SQLSetScrollOptions

Wird vom Snowflake-Treiber unterstützt, aber veraltete ODBC-API.

SQLSetParam

Wird vom Snowflake-Treiber unterstützt, ist aber ab ODBC-API-Version 2.x veraltet. Ersetzt durch SQLBindParameter.

Bemerkung

Es gibt eine Obergrenze für die Datengröße, die Sie binden können. Weitere Details dazu finden Sie unter Begrenzung der Abfragetextgröße.

Übermitteln von Anforderungen

Funktionsname

Unterstützt

Anmerkungen

SQLExecute

SQLExecDirect

SQLNativeSql

SQLDescribeParam

Unabhängig vom Datentyp, der an dem Parameter gebunden ist, führt Snowflake eine serverseitige Konvertierung durch und gibt einen VARCHAR-Wert mit einer maximalen Länge von 16.777.216 zurück.

SQLNumParams

SQLParamData

Nicht unterstützt, da Streaming nicht unterstützt wird.

SQLPutData

Nicht unterstützt, da Streaming nicht unterstützt wird.

Abrufen von Ergebnissen und Informationen über Ergebnisse

Funktionsname

Unterstützt

Anmerkungen

SQLBindCol

SQLError

Wird vom Snowflake-Treiber unterstützt, ist aber in ODBC-API-Version 3.x veraltet. Ersetzt durch SQLGetDiagRec.

SQLGetData

SQLGetDiagField

SQLGetDiagRec

SQLRowCount

SQLNumResultCols

SQLDescribeCol

SQLColAttribute

SQLColAttributes

Wird vom Snowflake-Treiber unterstützt, ist aber ab ODBC-API-Version 2.x veraltet. Ersetzt durch SQLColAttribute.

SQLFetch

SQLFetchScroll

Das FetchOrientation-Argument unterstützt nur den SQL_FETCH_NEXT-Wert. Alle anderen Typen von Abrufen scheitern.

SQLExtendedFetch

Ersetzt durch SQLFetchScroll in Treiber mit API-Version 3.x.

SQLSetPos

Snowflake unterstützt die Funktionalität nicht.

SQLBulkOperations

Snowflake unterstützt die Funktionalität nicht.

Abrufen von Informationen zu den Systemtabellen der Datenquelle (Katalogfunktionen)

Funktionsname

Unterstützt

Anmerkungen

SQLColumnPrivileges

Gibt ein leeres Resultset zurück.

SQLColumns

SQLForeignKeys

SQLPrimaryKeys

SQLProcedureColumns

Gibt ein leeres Resultset zurück.

SQLProcedures

Snowflake hat keine prozedurale Sprache, daher gibt diese Funktion ein leeres Resultset zurück.

SQLSpecialColumns

Gibt ein leeres Resultset zurück.

SQLStatistics

Gibt ein leeres Resultset zurück.

SQLTablePrivileges

Gibt ein leeres Resultset zurück.

SQLTables

Wenn der an die Funktion übergebene Parameter „TABLE“ ist, gibt die Funktion alle Tabellentypen zurück, einschließlich transienter Tabellen und temporärer Tabellen. . . Wenn der an die Funktion übergebene Parameter „VIEW“ ist, gibt die Funktion alle Arten von Ansichten zurück, einschließlich materialisierter Ansichten. . . Wenn der an die Funktion übergebene Parameter „TABLE, VIEW“ oder „%“ ist, gibt die Funktion Informationen zu allen Tabellentypen und Ansichtstypen zurück.

Wenn der an die Katalogfunktion übergebene Name ein ungültiges Zeichen enthält oder wenn der Name keinem Datenbankobjekt entspricht, gibt die Funktion ein leeres Resultset zurück.

Das Einstellen von SQL_ATTR_METADATA_ID wirkt sich nur auf die Funktionen SQLTables und SQLColumns aus.

Beenden einer Anweisung

Funktionsname

Unterstützt

Anmerkungen

SQLFreeStmt

SQLCloseCursor

SQLCancel

SQLEndTran

SQLTransact

Wird vom Snowflake-Treiber unterstützt, ist aber in ODBC-API-Version 3.x veraltet. Ersetzt durch SQLEndTran.

Beenden einer Verbindung

Funktionsname

Unterstützt

Anmerkungen

SQLCancelHandle

Eingeführt in die API nach Version 3.52.

SQLDisconnect

SQLFreeHandle

SQLFreeConnect

Wird vom Snowflake-Treiber unterstützt, ist aber in ODBC-API-Version 3.x veraltet.

SQLFreeEnv

Wird vom Snowflake-Treiber unterstützt, ist aber in ODBC-API-Version 3.x veraltet.

Sonstige Funktionen

Funktionsname

Unterstützt

Anmerkungen

SQLCompleteAsync

Eingeführt in die API nach Version 3.52.

Benutzerdefinierte SQL-Datentypen

Einige SQL-Datentypen, die von Snowflake unterstützt werden, haben keine direkte Zuordnung in ODBC (z. B. TIMESTAMP_*tz, VARIANT). Damit der ODBC-Treiber die nicht unterstützten Datentypen verarbeiten kann, enthält die mit dem Treiber gelieferte Headerdatei Definitionen für die folgenden benutzerdefinierten Datentypen:

////////////////////////////////////////////////////////////////////////////////////////////////////
/// 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

Der folgende Code veranschaulicht die Beispielnutzung der benutzerdefinierten Datentypen:

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

Beispiele

Dieser Abschnitt enthält Beispiele für die Verwendung der API.

Abrufen der letzten Abfrage-ID

Das Abrufen der letzten Abfrage-ID ist eine Snowflake-Erweiterung des ODBC-Standards.

Rufen Sie zum Abrufen der letzten Abfrage-ID die Funktion SQLGetStmtAttr (oder SQLGetStmtAttrW) auf, und übergeben Sie das Attribut SQL_SF_STMT_ATTR_LAST_QUERY_ID und ein Zeichenarray, das groß genug ist, um die Abfrage-ID aufzunehmen.

Das folgende Beispiel zeigt, wie die Abfrage-ID für eine Abfrage abgerufen wird:

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

Wenn die Ausführung unter Linux oder macOS erfolgt, rufen Sie SQLGetStmtAttrW auf und übergeben Sie Parameter des entsprechenden Datentyps (z. B. „wchar“ anstelle von „char“).