Node.js 드라이버 사용하기¶
드라이버를 사용하기 위한 일반적인 워크플로:
Snowflake에 연결합니다.
문(예: SQL 쿼리 또는 DDL/DML 명령)을 실행합니다.
Snowflake에서 반환된 쿼리 결과를 사용합니다.
연결을 종료합니다.
중요
Snowflake 스테이지에서 파일을 업로드 및 다운로드하려면 최소 버전이 다음과 같은 드라이버를 사용해야 합니다.
이 항목의 내용:
연결하기¶
Snowflake에 문을 실행하려면 우선 연결해야 합니다. Snowflake Node.js 드라이버를 사용하면 다음과 같은 방법으로 연결할 수 있습니다.
단일 연결 만들기¶
Snowflake에 대한 단일 연결을 만들려면:
snowflake.createConnection
을 호출하여 새Connection
오브젝트를 생성하고 연결 옵션 을 지정하는 JavaScript 오브젝트를 전달합니다.Connection
오브젝트를 사용하여connect
메서드를 호출해 연결합니다.참고
authenticator
옵션을EXTERNALBROWSER
(브라우저 기반 SSO 를 사용하기 위해) 또는https://<okta_계정_이름>.okta.com
(Okta를 통해 기본 SSO 를 사용하기 위해)으로 설정한 경우에는connect
메서드가 아닌connectAsync
메서드를 호출합니다.연결 오류를 처리하려면 다음 서명이 있는 콜백 함수를 전달합니다.
function(err, conn)
여기서:
err
은 JavaScriptError
오브젝트입니다.conn
은 현재Connection
오브젝트입니다.
연결 중에 오류가 발생하면
connect
메서드에서 콜백 함수로Error
오브젝트를 전달합니다. 콜백 함수에서 이 오브젝트를 사용하여 오류에 대한 세부 정보를 가져올 수 있습니다. 현재Connection
오브젝트에 대한 정보가 필요한 경우 콜백 함수로 전달된conn
인자를 사용할 수 있습니다.
다음 예에서는 연결을 하고 인증을 위한 비밀번호를 사용합니다. 다른 인증 메서드를 사용하려면 인증 옵션 을 참조하십시오.
// Load the Snowflake Node.js driver. var snowflake = require('snowflake-sdk');// Create a Connection object that we can use later to connect. var connection = snowflake.createConnection({ account: account, username: user, password: password, application: application });// Try to connect to Snowflake, and check whether the connection was successful. connection.connect( function(err, conn) { if (err) { console.error('Unable to connect: ' + err.message); } else { console.log('Successfully connected to Snowflake.'); // Optional: store the connection ID. connection_ID = conn.getId(); } } );
연결을 만들 때 연결 옵션 설정 의 설명과 같이 연결 옵션을 설정할 수 있습니다.
연결 풀 만들기¶
클라이언트 애플리케이션이 Snowflake에 액세스해야 할 때마다 연결을 생성하는 대신, 필요에 따라 재사용할 수 있는 Snowflake 연결 캐시를 정의할 수 있습니다. 연결 풀링을 사용하면 일반적으로 연결을 생성하기 위해 소요되는 시간이 감소합니다. 그러나 DNS 문제가 발생하면 클라이언트가 대체 DNS로 장애 조치를 수행하는 속도가 느려질 수 있습니다.
연결 풀을 만들려면:
snowflake.createPool(connectionOptions, poolOptions)
을 호출하여 새ConnectionPool
오브젝트를 생성하고 연결 옵션 및 풀 옵션을 지정하는 2개의 JavaScript 오브젝트를 전달합니다.참고
Snowflake Node.js 드라이버는 오픈 소스 node-pool 라이브러리를 사용하여 연결 풀을 구현합니다. 지원되는
poolOptions
에 대한 정보는 노드-풀 라이브러리 설명서 의 opts 인자에 대한 설명을 참조하십시오.ConnectionPool
오브젝트를 사용하여use
함수를 호출해 연결 풀에서 단일 연결에 대한 명령문을 실행합니다.연결 오류를 처리하려면 다음 서명이 있는 콜백 함수를 전달합니다.
function(err, stmt, rows)
여기서:
err
은 JavaScriptError
오브젝트입니다.stmt
는 문장의 리터럴 텍스트 등 실행된 SQL 문에 대한 정보가 포함된 오브젝트입니다.rows
는 문장의 《결과 세트》가 포함된 배열입니다.
문 실행 중에 오류가 발생하면
connect
메서드가Error
오브젝트를 콜백 함수로 전달합니다. 콜백 함수에서 이 오브젝트를 사용하여 오류에 대한 세부 정보를 가져올 수 있습니다.
다음 예에서는 최대 10개의 활성 연결을 지원하는 연결 풀을 생성합니다. 그리고 인증을 위해 비밀번호를 사용합니다. 다른 인증 메서드를 사용하려면 인증 옵션 을 참조하십시오.
// Create the connection pool instance const connectionPool = snowflake.createPool( // connection options { account: account, username: user, password: password }, // pool options { max: 10, // specifies the maximum number of connections in the pool min: 0 // specifies the minimum number of connections in the pool } );
다음 예제에서는 connectionPool.use
메서드를 사용하여 풀의 연결을 사용해 SQL 문을 실행합니다. clientConnection.execute
메서드는 실행할 SQL 문을 지정하고 콜백 함수를 정의합니다.
// Use the connection pool and execute a statement connectionPool.use(async (clientConnection) => { const statement = await clientConnection.execute({ sqlText: 'select 1;', complete: function (err, stmt, rows) { var stream = stmt.streamRows(); stream.on('data', function (row) { console.log(row); }); stream.on('end', function (row) { console.log('All rows consumed'); }); } }); });
연결 풀을 생성 때 연결 옵션 설정 의 설명과 같이 연결 옵션을 설정할 수 있습니다.
연결 옵션 설정하기¶
새 Connection
오브젝트를 구성할 때 연결에 대한 옵션(예: 계정 식별자, 사용자 이름 등)을 지정하는 JavaScript 오브젝트를 전달합니다. 다음 섹션에서는 설정이 가능한 옵션에 대해 설명합니다. 옵션을 설정하려면 옵션의 이름을 JavaScript 오브젝트의 속성 이름으로 지정합니다.
필수 연결 옵션¶
account
username
Snowflake 사용자 또는 ID 공급자의 로그인 이름(예: Okta 로그인 이름).
region
(사용되지 않음)계정이 위치한 리전 의 ID입니다.
참고
이 옵션은 더 이상 사용되지 않으며 이전 버전과의 호환성을 위해서만 여기에 포함된 것입니다. 다음과 같은 계정 로케이터를 식별자로 사용하기 에 설명된 것처럼, 계정 식별자에 리전을 포함하도록 전환하는 것이 좋습니다.
var connection = snowflake.createConnection({ account: "myaccount.us-east-2", username: "myusername", password: "mypassword" });
또한, 서버를 인증하기 위한 옵션 도 지정해야 합니다.
인증 옵션¶
application
Snowflake에 연결하는 클라이언트 애플리케이션의 이름을 지정합니다.
authenticator
사용자 로그인 자격 증명을 확인하기 위해 사용할 인증자를 지정합니다. 인증자는 다음 값 중 1개로 설정할 수 있습니다.
값
설명
SNOWFLAKE
내부 Snowflake 인증자를 사용합니다.
password
옵션도 설정해야 합니다.EXTERNALBROWSER
웹 브라우저를 사용하여 Okta, ADFS 또는 계정에 정의된 기타 SAML 2.0 규격 ID 공급자(IdP)를 인증합니다.
https://<okta_계정_이름>.okta.com
OAUTH
인증을 위해 OAuth를 사용합니다. OAuth 토큰에
token
옵션도 설정해야 합니다(아래 참조).SNOWFLAKE_JWT
키 페어 인증을 사용합니다. 키 페어 인증 & 키 페어 순환 사용하기 섹션을 참조하십시오.
기본값은
SNOWFLAKE
입니다.인증에 대한 자세한 내용은 페더레이션 인증 관리하기/사용하기 및 클라이언트, 드라이버 및 커넥터를 사용한 OAuth 를 참조하십시오.
password
사용자의 비밀번호입니다.
authenticator
옵션을SNOWFLAKE
로 설정하거나 Okta 계정에 Okta URL 엔드포인트 (예:https://<okta_계정_이름>.okta.com
) 를 설정하거나authenticator
옵션을 설정하지 않은 경우 이 옵션을 설정합니다.
token
인증에서 사용할 OAuth 토큰을 지정합니다.
authenticator
옵션을OAUTH
로 설정한 경우 이 옵션을 설정합니다.privateKey
키 페어 인증을 위한 개인 키(PEM 형식)를 지정합니다. 자세한 내용은 키 페어 인증 & 키 페어 순환 사용하기 섹션을 참조하십시오.
privateKeyPath
개인 키 파일(예:
rsa_key.p8
)에 대한 로컬 경로를 지정합니다. 자세한 내용은 키 페어 인증 & 키 페어 순환 사용하기 섹션을 참조하십시오.privateKeyPass
파일이 암호화된 경우 개인 키 파일의 암호를 해독하기 위한 암호를 지정합니다. 자세한 내용은 키 페어 인증 & 키 페어 순환 사용하기 섹션을 참조하십시오.
추가 연결 옵션¶
arrayBindingThreshold
대량 삽입 작업에서 드라이버가 사용하는 최대 바인드 수를 설정합니다. 기본값은 100000(100K)입니다.
clientSessionKeepAlive
기본적으로 클라이언트 연결은 일반적으로 가장 최근 쿼리가 실행된 후 약 3~4시간 후에 시간이 초과가 발생합니다.
clientSessionKeepAlive
옵션이true
로 설정된 경우, 서버로의 클라이언트 연결은 쿼리가 실행되지 않은 경우에도 무한대로 활성 상태를 유지합니다.이 옵션의 기본 설정은 false입니다.
이 옵션은
true
로 설정하면, 프로그램이 종료되었을 때 프로그램이 서버와의 연결을 명시적으로 끊어야 합니다. 연결을 끊지 않고 종료하지 마십시오.clientSessionKeepAliveHeartbeatFrequency
(
clientSessionKeepAlive
가 true인 경우에만 적용됨)하트비트 메시지 사이의 빈도(초 단위 간격)를 설정합니다.
대략적으로 연결 하트비트 메시지는 쿼리를 대체하고 연결에 대한 시간 초과 카운트다운을 다시 시작하는 것으로 간주할 수 있습니다. 즉, 활동이 없은 후 4시간 이상 후에 연결 시간이 초과되는 경우 하트비트는 타이머를 재설정하여 가장 최근 하트비트(또는 쿼리) 후 최소 4시간까지 시간 초과가 발생하지 않도록 합니다.
기본값은 3600초(1시간)입니다. 유효한 값 범위는 900~3600입니다. 시간 초과는 주로 4시간 후에 발생하므로 일반적으로 1시간마다 하트비트는 연결을 유지하기에 데 충분합니다. 3600초 미만의 하트비트 간격은 거의 필요하지 않거나 유용하지 않습니다.
database
연결 후 세션에서 사용할 기본 데이터베이스입니다.
noProxy
드라이버가 프록시 서버를 우회하여 직접 연결해야 하는 호스트 목록을 지정합니다(예: Amazon S3 액세스를 무시하는
*.amazonaws.com
). 여러 호스트의 경우, 호스트 이름을 파이프 기호(|
)로 구분합니다. 별표를 와일드카드로 사용할 수도 있습니다. 예:noProxy: "*.amazonaws.com|*.my_company.com"
proxyHost
인증된 프록시 서버의 호스트 이름을 지정합니다.
proxyPassword
proxyUser
로 지정된 사용자의 비밀번호를 지정합니다.proxyPort
인증된 프록시 서버의 포트를 지정합니다.
proxyProtocol
인증된 프록시 서버에 연결하기 위해 사용되는 프로토콜을 지정합니다. 이 속성을 사용하여
http
또는https
의 HTTP 프로토콜을 지정합니다.proxyUser
인증된 프록시 서버에 연결하기 위해 사용되는 사용자 이름을 지정합니다.
resultPrefetch
클라이언트가 큰 결과 세트를 프리페치하기 위해 사용할 스레드 수입니다. 유효한 값: 1~10.
role
연결 후에 세션에서 사용할 기본 보안 역할입니다.
schema
연결 후 세션에서 사용할 기본 스키마입니다.
timeout
응답이 없는 동안 연결을 유지하는 시간(밀리초)입니다. 기본값: 60,000(1분).
warehouse
연결 후 세션에서 사용한 기분 가상 웨어하우스입니다. 쿼리 실행, 데이터 로드 등을 위해 사용됩니다.
일부 연결 옵션의 경우 지정된 데이터베이스 오브젝트(데이터베이스, 스키마, 웨어하우스 또는 역할)가 이미 시스템에 있는 것으로 가정합니다. 지정된 오브젝트가 없는 경우 연결하는 동안 기본값이 설정되지 않습니다.
연결 후 USE <오브젝트> 명령을 통해 모든 선택 사항 연결 옵션을 설정하거나 재정의할 수도 있습니다.
Snowflake에 인증하기¶
Snowflake에 인증하기 위해서는 다음 옵션 중 1개를 사용할 수 있습니다.
비밀번호 기반 인증. 이 옵션을 사용하려면 연결할 때
password
옵션을 설정합니다.웹 브라우저를 통한 Single Sign-On(SSO).
Okta를 통한 기본 SSO.
웹 브라우저를 통한 Single Sign-On(SSO) 사용하기¶
Snowflake에서 Single Sign-On(SSO) 을 사용하도록 구성한 경우, 브라우저 기반 SSO를 사용하여 인증하도록 클라이언트 애플리케이션을 구성할 수 있습니다.
애플리케이션 코드에서:
authenticator
옵션을EXTERNALBROWSER
로 설정합니다.연결하려면
connect
메서드가 아닌connectAsync
메서드를 호출합니다.
예:
// Use a browser to authenticate via SSO.
var connection = snowflake.createConnection({
...,
authenticator: "EXTERNALBROWSER"
});
// Establish a connection. Use connectAsync, rather than connect.
connection.connectAsync(
function (err, conn)
{
... // Handle any errors.
}
).then(() =>
{
// Execute SQL statements.
var statement = connection.execute({...});
});
웹 기반 SSO를 사용한 인증에 대한 자세한 내용은 웹 기반 SSO 를 참조하십시오.
Okta를 통한 기본 SSO 사용하기¶
Okta를 통해 Snowflake에서 Single Sign-On(SSO)를 사용하도록 구성 한 경우, Okta를 통해 기본 SSO 인증을 사용하도록 클라이언트 애플리케이션을 구성할 수 있습니다.
애플리케이션 코드에서:
다음 옵션을 설정합니다.
authenticator
옵션을 Okta 계정(예:https://<okta_계정_이름>.okta.com
)에 대한 Okta URL 엔드포인트로 설정합니다.username
및password
옵션을 ID 공급자(IdP)의 사용자 이름 및 비밀번호로 설정합니다.
연결하려면
connect
메서드가 아닌connectAsync
메서드를 호출합니다.
예:
// Use native SSO authentication through Okta.
var connection = snowflake.createConnection({
...,
username: '<user_name_for_okta>',
password: '<password_for_okta>',
authenticator: "https://myaccount.okta.com"
});
// Establish a connection.
connection.connectAsync(
function (err, conn)
{
... // Handle any errors.
}
);
// Execute SQL statements.
var statement = connection.execute({...});
Okta를 통한 기본 SSO 인증 사용과 관련한 자세한 내용은 기본 SSO — Okta만 해당 을 참조하십시오.
키 페어 인증 & 키 페어 순환 사용하기¶
드라이버는 키 페어 인증 및 키 순환을 지원합니다. 이 방법을 사용하려면:
키 페어 인증 & 키 페어 순환 에서의 설명과 같이 키 페어 인증을 구성합니다.
애플리케이션 코드에서:
authenticator
옵션을SNOWFLAKE_JWT
로 설정합니다.개인 키를 사용하여 다음 방법 중 1개로 인증합니다.
privateKey
옵션을 개인 키로 설정합니다.privateKeyPath
옵션을 개인 키 파일의 경로로 설정합니다.파일이 암호화된 경우에는
privateKeyPass
옵션도 개인 키의 암호를 해독하기 위한 암호 구문으로 설정해야 합니다.
다음 예에서는 파일에서 개인 키를 로드하여
privateKey
옵션을 개인 키로 설정합니다.// Read the private key file from the filesystem. var crypto = require('crypto'); var fs = require('fs'); var privateKeyFile = fs.readFileSync('<path_to_private_key_file>/rsa_key.p8'); // Get the private key from the file as an object. const privateKeyObject = crypto.createPrivateKey({ key: privateKeyFile, format: 'pem', passphrase: 'passphrase' }); // Extract the private key from the object as a PEM-encoded string. var privateKey = privateKeyObject.export({ format: 'pem', type: 'pkcs8' }); // Use the private key for authentication. var connection = snowflake.createConnection({ ... authenticator: "SNOWFLAKE_JWT", privateKey: privateKey }); // Establish a connection. connection.connect( function (err, conn) { ... // Handle any errors. } ); // Execute SQL statements. var statement = connection.execute({...});다음 예에서는
privateKeyPath
옵션을 암호화된 개인 키 파일로 설정하고privateKeyPass
옵션을 개인 키의 암호를 해독하기 위해 사용되는 암호 구문으로 설정합니다.// Use an encrypted private key file for authentication. // Specify the passphrase for decrypting the key. var connection = snowflake.createConnection({ ... authenticator: "SNOWFLAKE_JWT", privateKeyPath: "<path-to-privatekey>/privatekey.p8", privateKeyPass: '<passphrase_to_decrypt_the_private_key>' }); // Establish a connection. connection.connect( function (err, conn) { ... // Handle any errors. } ); // Execute SQL statements. var statement = connection.execute({...});
OAuth 사용하기¶
OAuth를 사용하려 연결하려면, authenticator
옵션을 OAUTH
로 설정하고 token
옵션을 OAuth 액세스 토큰으로 설정합니다. 예:
// Use OAuth for authentication.
var connection = snowflake.createConnection({
...
authenticator: "OAUTH",
token: "<your_oauth_token>"
});
// Establish a connection.
connection.connect(
function (err, conn)
{
... // Handle any errors.
}
);
// Execute SQL statements.
var statement = connection.execute({...});
자세한 내용은 클라이언트, 드라이버 및 커넥터를 사용한 OAuth 섹션을 참조하십시오.
인증된 프록시를 통해 연결하기¶
Connection
오브젝트를 생성할 때 연결 옵션으로 인증 자격 증명을 제공하여 인증된 프록시를 통해 Snowflake에 연결할 수 있습니다.
참고
인증된 프록시 서버를 통한 연결은 Snowflake Node.js 드라이버 버전 1.6.4 이상부터 지원됩니다.
다음 예는 HTTP를 사용하여 인증된 프록시에 연결하는 방법을 보여줍니다.
var connection = snowflake.createConnection({
account: "account",
username: "user",
password: "password",
proxyHost: "localhost",
proxyPort: 3128,
proxyUser: "myname",
proxyPassword: "mypass"
});
HTTPS를 사용하여 인증된 프록시에 연결하려면 아래와 같이 proxyProtocol
연결 속성도 제공해야 합니다.
var connection = snowflake.createConnection({
account: "account",
username: "user",
password: "password",
proxyHost: "localhost",
proxyPort: 3128,
proxyUser: "myname",
proxyPassword: "mypass",
proxyProtocol: "https"
});
SnowCD를 사용한 Snowflake로의 네트워크 연결 확인하기¶
드라이버를 구성한 후에는 SnowCD 를 사용하여 Snowflake로의 네트워크 연결을 평가하고 문제를 해결할 수 있습니다.
초기 구성 프로세스 및 언제라도 필요할 때 SnowCD를 사용하여 Snowflake로의 네트워크 연결을 평가하고 문제를 해결할 수 있습니다.
OCSP(온라인 인증서 상태 프로토콜)¶
드라이버가 연결되면 Snowflake는 Snowflake를 가장하는 호스트가 아니라 Snowflake에 연결되었음을 확인하는 인증서를 전송합니다. 드라이버는 해당 인증서를 OCSP(온라인 인증서 상태 프로토콜) 서버로 전송하여 인증서가 해지되지 않았는지 확인합니다.
드라이버가 인증서를 확인하기 위해 OCSP 서버에 연결할 수 없는 경우 드라이버는 《페일 오픈》 또는 《페일 클로즈》 메시지를 표시할 수 있습니다.
페일 오픈 또는 페일 클로즈 모드 선택하기¶
1.2.0 이전 버전의 Node.js 드라이버의 모드는 기본적으로 페일 클로즈입니다. 1.2.0 이상 버전의 경우에는 기본적으로 페일 오픈입니다. snowflake.createConnection()
메서드를 호출하기 전 ocspFailOpen
전역 매개 변수를 설정하여 기본 동작을 재정의할 수 있습니다. 매개 변수는 true 또는 false로 설정할 수 있습니다.
snowflake.configure( {ocspFailOpen: false} );
const connection = snowflake.createConnection(
{
account: <account_identifier>,
...
}
);
문 실행하기¶
문은 connection.execute()
메서드를 호출하여 실행할 수 있습니다. execute()
메서드에서는 SQL 텍스트 및 complete
콜백을 지정하기 위해 사용할 수 있는 options
오브젝트를 허용합니다. complete
콜백은 문의 실행이 종료되고 결과를 사용할 수 있을 때 호출됩니다.
var statement = connection.execute({ sqlText: 'create database testdb', complete: function(err, stmt, rows) { if (err) { console.error('Failed to execute statement due to the following error: ' + err.message); } else { console.log('Successfully executed statement: ' + stmt.getSqlText()); } } });
참고
단일 요청의 최대 페이로드 크기는 16MB입니다.
문 매개 변수 바인딩하기¶
종종 문의 데이터와 자리 표시자를 바인딩해야 하는 경우가 있습니다. 이러한 방식으로 문을 실행하는 것은 SQL 삽입 공격을 방지할 수 있으므로 유용합니다. 다음 문을 살펴보겠습니다.
connection.execute({ sqlText: 'select c1 from (select 1 as c1 union all select 2 as c1) where c1 = 1;' });
다음 바인딩을 사용하여 동일한 결과를 얻을 수 있습니다.
connection.execute({ sqlText: 'select c1 from (select :1 as c1 union all select :2 as c1) where c1 = :1;', binds: [1, 2] });
바인딩을 위한 ?
구문도 지원됩니다.
connection.execute({ sqlText: 'select c1 from (select ? as c1 union all select ? as c1) where c1 = ?;', binds: [1, 2, 1] });
참고
바인딩할 수 있거나 일괄 결합할 수 있는 데이터 크기의 상한에는 제한이 있습니다. 자세한 내용은 쿼리 텍스트 크기 제한 섹션을 참조하십시오.
SQL 문 일괄 실행하기(다중 문 지원)¶
Node.js의 버전 1.6.18 이상에서는 세미콜론으로 구분된 SQL 문 배치를 전송하여 단일 요청에서 실행되도록 할 수 있습니다.
참고
기본적으로 Snowflake는 다중 문으로 실행된 쿼리에 대한 오류를 반환합니다. 이러한 동작은 SQL 삽입 을 방지하기 위한 방법의 일부로 수행됩니다. 다중 문 기능을 사용하면 SQL이 삽입될 가능성이 있으므로 신중하게 사용해야 합니다. SnowflakeStatement.setParameter()
메서드를 사용해 실행할 문의 개수를 지정하여 위험을 줄일 수 있으며, 문을 추가하여 삽입하는 것이 더욱 어려워집니다. 자세한 내용은 인터페이스: SnowflakeStatement 섹션을 참조하십시오.
여러 명령문이 포함된 쿼리는 단일 명령문이 포함된 쿼리와 동일한 방식으로 실행할 수 있지만, 쿼리 문자열에 세미콜론으로 구분된 여러 명령문이 포함된다는 점이 다릅니다.
다중 문은 다음의 2가지 방법으로 사용할 수 있습니다.
Statement.setParameter("MULTI_STATEMENT_COUNT", n)
을 호출하여 한 번에 이 문을 실행할 수 있는 문의 수를 지정합니다.다음 명령 중 하나를 실행하여 세션 수준 또는 계정 수준에서 MULTI_STATEMENT_COUNT 매개 변수를 설정합니다.
alter session set MULTI_STATEMENT_COUNT = 0;
또는:
alter account set MULTI_STATEMENT_COUNT = 0;
매개 변수를 0으로 설정하면 무제한 수의 문이 허용됩니다. 매개 변수를 1로 설정하면 한 번에 1개의 문만 허용됩니다.
다음 예에서는 세션 수준에서 문 수를 무제한으로 설정한 다음 SQL 문 세 개를 실행합니다.
var statement = connection.execute({ alter session set MULTI_STATEMENT_COUNT = 0; sqlText: 'create table test(n int); insert into test values (1), (2); select * from test order by n', complete: function(err, stmt, rows) { if (err) { console.error('Failed to execute statement due to the following error: ' + err.message); } else { // code to process the results } } });
일괄 삽입을 위한 배열 바인딩하기¶
일괄 INSERT 연산을 위한 데이터 배열 바인딩이 지원됩니다. 배열의 배열을 다음과 같이 전달합니다.
connection.execute({ sqlText: 'insert into t(c1, c2, c3) values(?, ?, ?)', binds: [[1, 'string1', 2.0], [2, 'string2', 4.0], [3, 'string3', 6.0]] });
참고
대규모 배열을 바인딩하면 성능에 영향을 주며 데이터의 크기가 너무 커서 서버에서 처리할 수 없는 경우에는 거부될 수 있습니다.
문 취소하기¶
문은 statement.cancel()
메서드를 호출하여 취소할 수 있습니다.
statement.cancel(function(err, stmt) { if (err) { console.error('Unable to abort statement due to the following error: ' + err.message); } else { console.log('Successfully aborted statement'); } });
요청 다시 제출하기¶
어쩌면 네트워크 오류 또는 시간 초과로 인해 Snowflake가 SQL 문을 성공적으로 실행했는지 확실하지 않은 경우 요청 ID를 사용하여 같은 문을 다시 제출할 수 있습니다. 예를 들어, 데이터를 추가하려고 INSERT 명령을 제출했지만 적시에 확인을 받지 못했는데, 명령에 어떤 문제가 있는지는 모른다고 가정해 보십시오. 이런 상황에서는 똑같은 명령을 새 명령으로 실행하면 명령을 두 번 실행하여 데이터 중복을 일으킬 수 있으므로 그렇게 하고 싶지는 않을 것입니다.
SQL 문에 요청 ID를 포함하면 데이터 중복 가능성을 피할 수 있습니다. 초기 요청에서 요청 ID로 요청을 다시 제출하면 초기 요청이 실패하는 경우에만 다시 제출된 명령이 실행됩니다. 자세한 내용은 SQL 문 실행 요청 다시 제출하기 를 참조하십시오.
다음 코드 샘플에서는 요청 ID를 저장하고 사용하여 문을 다시 제출하는 방법을 보여줍니다. 문을 실행할 때 getRequestId()
함수를 사용하여 제출된 요청의 ID를 검색할 수 있습니다. 그런 다음 해당 ID를 사용하여 나중에 같은 문을 실행할 수 있습니다. 다음 예제에서는 INSERT 문을 실행하고 requestId
변수에 요청 ID를 저장합니다.
var requestId; connection.execute({ sqlText: 'INSERT INTO testTable VALUES (1);', complete: function (err, stmt, rows) { var stream = stmt.streamRows(); requestId = stmt.getRequestId(); // Retrieves the request ID stream.on('data', function (row) { console.log(row); }); stream.on('end', function (row) { console.log('done'); }); } });
명령이 성공적으로 실행되었다는 확인을 받지 못한 경우 그림과 같이 저장된 요청 ID를 사용하여 요청을 다시 제출할 수 있습니다.
connection.execute({ sqlText: 'INSERT INTO testTable VALUES (1);', // optional requestId: requestId, // Uses the request ID from before complete: function (err, stmt, rows) { var stream = stmt.streamRows(); stream.on('data', function (row) { console.log(row); }); stream.on('end', function (row) { console.log('done'); }); } });
requestId
와 sqlText
를 사용하여 요청을 다시 제출하기로 할 때 다음 상호 작용에 유의하십시오.
requestId
가 이미 존재하는 경우, 즉 다시 제출하는 요청이 이전 요청과 일치하는 경우, 이 명령은sqlText
쿼리를 무시하고 원래 명령에서 쿼리를 다시 제출합니다.requestId
가 존재하지 않는 경우, 즉 이전 요청과 일치하지 않는 경우, 이 명령은sqlText
쿼리를 실행합니다.
결과 사용하기¶
인라인 결과 반환하기¶
결과를 사용하는 가장 일반적인 방법은 complete
콜백을 connection.execute()
로 전달하는 방법입니다. 문의 실행이 종료되고 결과를 사용할 수 있으면, 결과 행이 인라인으로 반환되면서 complete
콜백이 호출됩니다.
connection.execute({ sqlText: 'select * from sometable', complete: function(err, stmt, rows) { if (err) { console.error('Failed to execute statement due to the following error: ' + err.message); } else { console.log('Number of rows produced: ' + rows.length); } } });
결과 스트리밍하기¶
결과를 행의 스트림으로 사용할 수도 있습니다. 이는 statement.streamRows()
메서드를 호출하여 수행할 수 있으며, 이를 통해 수신될 때 행을 사용하기 위해 사용될 수 있는 Node.js Readable
스트림이 반환됩니다. Readable
스트림에 대한 자세한 내용은 Node.js 설명서 를 참조하십시오.
예:
var statement = connection.execute({ sqlText: 'select * from sometable' }); var stream = statement.streamRows(); stream.on('error', function(err) { console.error('Unable to consume all rows'); }); stream.on('data', function(row) { // consume result row... }); stream.on('end', function() { console.log('All rows consumed'); });
일괄 처리 결과¶
기본적으로 statement.streamRows()
메서드에서는 결과의 모든 행이 포함되는 스트림이 생성됩니다. 그러나 하위 결과 세트만을 사용하거나 결과 행을 일괄적으로 사용하려는 경우에는 start
및 end
인자를 사용하여 streamRows()
를 호출할 수 있습니다. 이러한 추가 옵션이 지정되면 요청된 범위 내의 행만 스트리밍됩니다.
connection.execute({ sqlText: 'select * from sometable', streamResult: true, // prevent rows from being returned inline in the complete callback complete: function(err, stmt, rows) { // no rows returned inline because streamResult was set to true console.log('rows: ' + rows); // 'rows: undefined' // only consume at most the last 5 rows in the result rows = []; stmt.streamRows({ start: Math.max(0, stmt.getNumRows() - 5), end: stmt.getNumRows() - 1, }) .on('error', function(err) { console.error('Unable to consume requested rows'); }) .on('data', function(row) { rows.push(row); }) .on('end', function() { console.log('Number of rows consumed: ' + rows.length); }); } })
데이터 타입 캐스팅¶
결과 행이 생성되면 드라이버는 SQL 데이터 타입을 해당 JavaScript 데이터 타입으로 자동으로 매핑합니다. 예를 들어, TIMESTAMP 및 DATE 타입의 값은 JavaScript 날짜 오브젝트로 반환됩니다.
JavaScript를 SQL 데이터 타입으로 완전하게 매핑하려면 아래 테이블을 참조하십시오.
SQL 데이터 타입
JavaScript 데이터 타입
참고
VARCHAR, CHAR, CHARACTER, STRING, TEXT
문자열
INT, INTEGER, BIGINT, SMALLINT
숫자
기본 매핑입니다. 세션 매개 변수 JS_TREAT_INTEGER_AS_BIGINT를 사용하여 JavaScript Bigint로 매핑합니다.
NUMBER(전체 자릿수, 소수 자릿수), DECIMAL(p, s), NUMERIC(p, s), 여기서
scale
= 0숫자
기본 매핑입니다. 세션 매개 변수 JS_TREAT_INTEGER_AS_BIGINT를 사용하여 JavaScript Bigint로 매핑합니다.
NUMBER(전체 자릿수, 소수 자릿수), DECIMAL(p, s), NUMERIC(p, s), 여기서
scale
> 0숫자
FLOAT, FLOAT4, FLOAT8, DOUBLE, DOUBLE PRECISION, REAL
숫자
TIMESTAMP, TIMESTAMP_LTZ, TIMESTAMP_NTZ, TIMESTAMP_TZ
날짜
TIMESTAMP_NTZ 값은 UTC 시간으로 반환됩니다.
DATE
날짜
TIME
문자열
SQL의 TIME 데이터 타입에 해당하는 타입이 JavaScript에는 없으며, 그러므로 JavaScript 문자열로 매핑됩니다.
BOOLEAN
부울
VARIANT, ARRAY, OBJECT
JSON
정수 데이터 타입을 Bigint로 가져오기¶
기본적으로, Snowflake INTEGER 열(BIGINT, NUMBER(p, 0) 등 포함)은 JavaScript의 Number 데이터 타입으로 변환됩니다. 하지만 가장 큰 올바른 Snowflake 정수 값은 가장 큰 올바른 JavaScript Number 값보다 큽니다. Snowflake INTEGER 열을 JavaScript Number보다 큰 값을 저장할 수 있는 JavaScript Bigint로 변환하려면 세션 매개 변수 JS_TREAT_INTEGER_AS_BIGINT를 설정합니다.
이 매개 변수는 다음의 2가지 방법으로 설정할 수 있습니다.
아래와 같이 ALTER SESSION 문을 사용합니다.
connection.execute( { sqlText: 'ALTER SESSION SET JS_TREAT_INTEGER_AS_BIGINT = TRUE', complete: function ... } );
연결 구성 정보에 매개 변수를 지정합니다.
var connection = snowflake.createConnection( { username: 'fakeusername', password: 'fakepassword', account: 'fakeaccountidentifier', jsTreatIntegerAsBigInt: true } );
데이터 타입을 문자열로 가져오기¶
connection.execute()
가 호출될 때 fetchAsString
옵션을 설정하여 모든 숫자 또는 날짜를 문자열로 강제 반환하도록 설정할 수 있습니다. 이를 통해 얻을 수 있는 결과는 다음과 같습니다.
DATE 또는 TIMESTAMP(또는 베리언트) 타입 값의 타입이 지정된 버전.
전체 자릿수가 손실되지 않고 JavaScript 숫자로 변환할 수 없는 숫자 SQL 타입의 문자열 버전.
예:
connection.execute({
sqlText: 'select 1.123456789123456789123456789 as "c1"',
fetchAsString: ['Number'],
complete: function(err, stmt, rows) {
if (err) {
console.error('Failed to execute statement due to the following error: ' + err.message);
} else {
console.log('c1: ' + rows[0].c1); // c1: 1.123456789123456789123456789
}
}
});
파일을 Snowflake 스테이지로 업로드하기¶
파일을 Snowflake 스테이지로 업로드하려면 PUT 명령을 사용합니다.
다음 예는 이름이 TABLE
인 테이블의 내부 스테이지에 파일을 업로드하는 방법을 보여줍니다. 데이터의 각 행이 수집되면 콘솔에 기록됩니다.
connection.execute({
sqlText: 'PUT file://C:\\Users\\Username\\Files\\employees0*.csv @DATABASE.SCHEMA.%TABLE;',
complete: function (err)
{
var stream = statement.streamRows();
stream.on('data', function (row)
{
console.log(row);
});
stream.on('end', function (row)
{
console.log('All rows consumed');
});
}
});
연결 종료하기¶
연결은 connection.destroy()
메서드를 호출하여 종료할 수 있습니다. 그러면 실행 중인 문의 완료를 대기하지 않고 연결과 관련된 세션이 즉시 종료됩니다.
connection.destroy(function(err, conn) { if (err) { console.error('Unable to disconnect: ' + err.message); } else { console.log('Disconnected connection with id: ' + connection.getId()); } });