ストアドプロシージャ API

このトピックでは、Snowflakeのストアドプロシージャの JavaScript API について説明します。

Snowflakeのストアドプロシージャは JavaScriptで記述されています。API は、 JavaScript オブジェクトとそれらのオブジェクトのメソッドで構成されます。

このトピックの内容:

オブジェクト: snowflake

snowflake オブジェクトには、デフォルトでストアドプロシージャの JavaScript コードからアクセスできます。オブジェクトを作成する必要はありません。このオブジェクトには、ストアドプロシージャ APIのメソッドが含まれています。例:

create procedure stproc1()
  returns string not null
  language javascript
  as
  -- "$$" is the delimiter for the beginning and end of the stored procedure.
  $$
  // The "snowflake" object is provided automatically in each stored procedure.
  // You don't need to create it.
  //         |||||||||
  //         vvvvvvvvv
  var statement = snowflake.createStatement(...);
  ...
  $$
  ;

より広範なコード例は ストアドプロシージャの使用 で提供されています。

定数

なし。

メソッド

createStatement(sql_command_object)

このメソッドは、 Statement オブジェクトを作成して返します。オブジェクトの execute() メソッドは後で実行できます。

パラメーター
sql_command_object

入力パラメーターは、実行されるステートメントのテキストと、そのステートメントにバインドされる必要がある値を含む JSON オブジェクト(辞書)です。

戻り値

Statement オブジェクトです。

エラー

次の場合に JavaScript エラーをスローします。

  • sqlText がないか、空のクエリテキストが含まれている。

  • データ型がサポートされていない引数をステートメントがバインドしようとする。データ型マッピングの詳細については、 SQL および JavaScript データ型マッピング をご参照ください。バインディングの詳細については、 変数のバインド をご参照ください。

この例では、値をバインドしません。

var stmt = snowflake.createStatement(
   {sqlText: "INSERT INTO table1 (col1) VALUES (1);"}
   );

この例では、値をバインドします。

var stmt = snowflake.createStatement(
   {
   sqlText: "INSERT INTO table2 (col1, col2) VALUES (?, ?);",
   binds:["LiteralValue1", variable2]
   }
);

追加の例を含むバインディングの詳細については、 変数のバインド をご参照ください。

execute(command)

このメソッドは、 SQL コマンドを直接実行します。

パラメーター

入力は、 createStatement() メソッドの場合と同じです。

戻り値

ResultSet オブジェクトの形式の結果セット。

エラー

次の場合に JavaScript エラーをスローします。

  • クエリの実行中にコンパイルエラーなどのエラーが発生した。

  • sqlText がないか、空のクエリテキストが含まれている。

  • データ型がサポートされていない引数をステートメントがバインドしようとする。データ型マッピングの詳細については、 SQL および JavaScript データ型マッピング をご参照ください。追加の例を含むバインディングの詳細については、 変数のバインド をご参照ください。

注釈

この execute() メソッド(例: snowflake.execute())は、 Statement オブジェクトのメソッド(例: Statement.execute())と完全に同じではありません。

オブジェクト: Statement

ストアドプロシージャ Statement オブジェクトは、クエリステートメントを実行し、ステートメントに関するメタデータ(列データ型など)にアクセスするためのメソッドを提供します。

ステートメントオブジェクトの作成時に、 SQL が解析され、準備されたステートメントが作成されます。

定数

なし。

メソッド

execute()

このメソッドは、この Statement オブジェクトに保存された準備済みステートメントを実行します。

パラメーター

なし(メソッドは Statement オブジェクトに既に保存されている情報を使用するため)。

戻り値

ResultSet オブジェクトの形式の結果セット。

エラー

クエリが失敗した場合、 JavaScript エラーをスローします。

ストアドプロシージャの使用 をご参照ください。

注釈

この execute() メソッド(例: Statement.execute())は、 snowflake オブジェクトのメソッド(例: snowflake.execute())と完全に同じではありません。

実行する SQL ステートメントの snowflake.execute(statement_in_JSON_form) パラメーターが必要です。 Statement.execute() はパラメーターを取りません。ステートメントオブジェクトの作成時に指定された SQL ステートメントを使用します。

getQueryId()

このメソッドは、実行された最新のクエリの UUID を返します。

パラメーター

なし。

戻り値

クエリ IDである UUIDを含む文字列。

エラー

このステートメントによってクエリがまだ実行されていない場合、メソッドは「ステートメントはまだ実行されていません」というエラーをスローします。

var queryId = statement.getQueryId();
getSqlText()

このメソッドは、準備されたクエリのテキストを Statement オブジェクトに返します。

パラメーター

なし。

戻り値

準備されたクエリテキストの文字列。

エラー

なし。

var queryText = statement.getSqlText();
getColumnCount()

このメソッドは、実行されたクエリの結果セットの列数を返します。クエリがまだ実行されていない場合、このメソッドはエラーをスローします。

パラメーター

なし。

戻り値

列の数。

エラー

ステートメントがまだ実行されていない場合、 JavaScript エラーをスローします(したがって、返される列の数は必ずしも決定できません)。

var column_count = statement.getColumnCount();
getRowCount()

このメソッドは、実行されたクエリの結果セットの行数を返します。クエリがまだ実行されていない場合、このメソッドはエラーをスローします。

パラメーター

なし。

戻り値

行の数。

エラー

ステートメントがまだ実行されていない場合、JavaScriptエラーをスローします(したがって、返される行の数を判別できません)。

var row_count = statement.getRowCount();
getColumnSqlType(colIdx|colName)

このメソッドは、指定された列の SQL データ型を返します。

パラメーター

列のインデックス番号( 0 ではなく 1 から始まる )または列の名前。(メソッドは、パラメーターとして異なるデータ型を受け入れるためにオーバーロードされます)

テーブルの作成時に列名に二重引用符が使用されていない限り、列名はすべて大文字にする必要があります(列名の大文字と小文字は保持される)。

戻り値

列の SQL データ型。

エラー

次の場合に JavaScript エラーをスローします。

  • Statement がまだ実行されていない。

  • 指定された名前またはインデックスを持つ列が存在しない。

getColumnType(colIdx|colName)

このメソッドは、指定された列の JavaScript データ型を返します。

パラメーター

列のインデックス番号( 0 ではなく 1 から始まる )または列の名前。(メソッドは、パラメーターとして異なるデータ型を受け入れるためにオーバーロードされます)

テーブルの作成時に列名に二重引用符が使用されていない限り、列名はすべて大文字にする必要があります(列名の大文字と小文字は保持される)。

戻り値

列の JavaScript データ型。

エラー

次の場合に JavaScript エラーをスローします。

  • Statement がまだ実行されていない。

  • 指定されたインデックスまたは名前の列が存在しない。

getColumnName(colIdx)

このメソッドは、指定された列の名前を返します。

パラメーター

列のインデックス番号(0 ではなく 1 から開始)。

戻り値

列の名前。

エラー

次の場合に JavaScript エラーをスローします。

  • Statement がまだ実行されていない。

  • 指定されたインデックスを持つ列が存在しない。

getColumnScale(colIdx)

このメソッドは、指定された列のスケールを返します。スケールは、小数点以下の桁数です。列のスケールは CREATE TABLE または ALTER TABLE ステートメントで指定されました。例:

create table scale_example  (
    n10_4 numeric(10, 4)    // Precision is 10, Scale is 4.
    );

このメソッドはどのデータ型でも呼び出すことができますが、数値データ型で使用することを目的としています。

パラメーター

スケールが必要な列のインデックス( 0 ではなく 1 から開始)。

戻り値

列のスケール(数値列の場合)。非数値(列)の場合は 0

エラー

次の場合に JavaScript エラーをスローします。

  • Statement がまだ実行されていない。

  • 指定されたインデックスを持つ列が存在しない。

ストアドプロシージャの使用 をご参照ください( getColumnScale() を検索)。

isColumnNullable(colIdx)

このメソッドは、指定された列が SQL NULL 値を許可するかどうかを返します。

パラメーター

列のインデックス(0 ではなく 1 から開始)。

戻り値

列がSQL NULL値を許可する場合は true 。それ以外の場合は、 false

エラー

次の場合に JavaScript エラーをスローします。

  • Statement がまだ実行されていない。

  • 指定されたインデックスを持つ列が存在しない。

isColumnText(colIdx)

列のデータ型が次の SQL テキストデータ型のいずれかである場合、このメソッドはtrueを返します。

  • CHAR または CHAR(N)、およびそれらの同義語 CHARACTER および CHARACTER(N)

  • VARCHAR または VARCHAR(N)

  • STRING

  • TEXT

それ以外の場合は、falseを返します。

パラメーター

列のインデックス(0 ではなく 1 から開始)。

戻り値

true 、列のデータ型が SQL テキストデータ型のいずれかである場合。 false 、他のすべてのデータ型。

エラー

次の場合に JavaScript エラーをスローします。

  • Statement がまだ実行されていない。

  • 指定されたインデックスを持つ列が存在しない。

注釈

APIは、列のデータ型を決定するためのいくつかのメソッドを提供します。最初の方法は上記で詳しく説明されています。残りのメソッドには同じパラメーターとエラーがあります。唯一の違いは戻り値です。

isColumnArray(colIdx)
戻り値

true 、列のデータ型がARRAY(半構造化データ)の場合。 false 、他のすべてのデータ型。

isColumnBinary(colIdx)
戻り値

true 、列のデータ型が BINARY または VARBINARY の場合。 false 、他のすべてのデータ型。

isColumnBoolean(colIdx)
戻り値

true 、列のデータ型が BOOLEANの場合。 false 、他のすべてのデータ型。

isColumnDate(colIdx)
戻り値

true 、列のデータ型が DATE の場合。 false 、他のすべてのデータ型。

isColumnNumber(colIdx)
戻り値

true 、列のデータ型が SQL 数値型(NUMBER、 NUMERIC、 DECIMAL、 INT、 INTEGER、 BIGINT、 SMALLINT、 TINYINT、 BYTEINT、 FLOAT、 FLOAT4、 FLOAT8、 DOUBLE、 DOUBLE、 PRECISION、または REAL)のいずれかである場合。 false 、他のすべてのデータ型。

isColumnObject(colIdx)
戻り値

true 、列のデータ型が OBJECT (半構造化データ)の場合。 false 、他のすべてのデータ型。

isColumnTime(colIdx)
戻り値

true 、列のデータ型が TIME または DATETIME の場合。 false 、他のすべてのデータ型。

isColumnTimestamp(colIdx)
戻り値

true 、列のデータ型が SQL タイムスタンプ型(TIMESTAMP、 TIMESTAMP_LTZ、 TIMESTAMP_NTZ、または TIMESTAMP_TZ)のいずれかである場合。 false 、他の日付および時刻データ型(DATE、 TIME、または DATETIME)を含む他のすべてのデータ型。

isColumnVariant(colIdx)
戻り値

true 、列のデータ型が VARIANT (半構造化データ)の場合。 false 、他のすべてのデータ型。

オブジェクト: ResultSet

このオブジェクトには、クエリによって返された結果が含まれます。結果は、ゼロ以上の行のセットとして扱われ、各行には1つ以上の列が含まれます。ここでは、「セット」という用語は数学的な意味では使用されません。数学では、セットは順序付けられていませんが、 ResultSet には順序があります。

ResultSet は、いくつかの点で SQL カーソルの概念に似ています。たとえば、カーソルで一度に1行を表示できるように、 ResultSet で一度に1行を表示できます。

通常、 ResultSet を取得した後、次の操作を繰り返して反復処理します。

  • next() を呼び出して次の行を取得します。

  • getColumnValue() などのメソッドを呼び出して、現在の行からデータを取得します。

ResultSet のデータについて十分に知らない場合(例えば、各列のデータ型がわからない場合)、データに関する情報を提供する他のメソッドを呼び出すことができます。

ResultSet オブジェクトのメソッドの一部は、 Statement オブジェクトのメソッドに似ています。例えば、両方のオブジェクトには getColumnSqlType(colIdx) メソッドがあります。

定数

なし。

メソッド

next()

このメソッドは ResultSet の次の行を取得し、アクセスできるようにします。

このメソッドは、新しいデータ行を返しません。代わりに、行を使用可能にして、 ResultSet.getColumnValue() などのメソッドを呼び出してデータを取得できるようにします。

最初の行を 含む 、結果セットの各行に対して next() を呼び出す必要があります。。

パラメーター

なし。

戻り値

true 、行を取得した場合。 false 、取得する行がもうない場合。

したがって、 next() がfalseを返すまで ResultSet を反復処理できます。

エラー

なし。

getColumnSqlType(colIdx|colName)

このメソッドは、指定された列の SQL データ型を返します。

パラメーター

列のインデックス番号( 0 ではなく 1 から始まる )または列の名前。(メソッドは、パラメーターとして異なるデータ型を受け入れるためにオーバーロードされます)

テーブルの作成時に列名に二重引用符が使用されていない限り、列名はすべて大文字にする必要があります(列名の大文字と小文字は保持される)。

戻り値

列の SQL データ型。

エラー

次の場合に JavaScript エラーをスローします。

  • ResultSet が空であるか、 next() がまだ呼び出されていない。

  • 指定されたインデックスまたは名前の列が存在しない。

getColumnValue(colIdx|colName)

このメソッドは、現在の行( next() によって最後に取得された行)の列の値を返します。

パラメーター

列のインデックス番号( 0 ではなく 1 から始まる )または列の名前。(メソッドは、パラメーターとして異なるデータ型を受け入れるためにオーバーロードされます)

テーブルの作成時に列名に二重引用符が使用されていない限り、列名はすべて大文字にする必要があります(列名の大文字と小文字は保持される)。

戻り値

指定された列の値。

エラー

次の場合に JavaScript エラーをスローします。

  • ResultSet が空であるか、 next() がまだ呼び出されていない。

  • 指定されたインデックスまたは名前の列が存在しない。

データベースの行を JavaScript 配列に変換します。

var valueArray = [];
// For each row...
while (myResultSet.next())  {
    // Append each column of the current row...
    valueArray.push(myResultSet.getColumnValue('MY_COLUMN_NAME1'));
    valueArray.push(myResultSet.getColumnValue('MY_COLUMN_NAME2'));
    ...
    // Do something with the row of data that we retrieved.
    f(valueArray);
    // Reset the array before getting the next row.
    valueArray = [];
    }

また、列の値は ResultSet オブジェクトのプロパティとしてアクセスできます(例: myResultSet.MY_COLUMN_NAME)。

var valueArray = [];
// For each row...
while (myResultSet.next())  {
    // Append each column of the current row...
    valueArray.push(myResultSet.MY_COLUMN_NAME1);
    valueArray.push(myResultSet.MY_COLUMN_NAME2);
    ...
    // Do something with the row of data that we retrieved.
    f(valueArray);
    // Reset the array before getting the next row.
    valueArray = [];
    }

注釈

CREATE TABLE ステートメントで列名を二重引用符で区切らない限り、列名は JavaScript コードですべて大文字にする必要があります。

getColumnValueAsString(colIdx|colName)

このメソッドは、列の値を文字列として返します。これは、テーブルの元のデータ型に関係なく列の値が必要な場合に便利です。

このメソッドは、文字列値を返すことを除いて、メソッド getColumnValue() と同じです。

詳細については、 getColumnValue() をご参照ください。

getQueryId()

このメソッドは、実行された最新のクエリの UUID を返します。

パラメーター

なし。

戻り値

クエリ IDである UUIDを含む文字列。

var queryId = resultSet.getQueryId();

オブジェクト: SfDate

JavaScript には、Snowflake SQL データ型 TIMESTAMP_LTZ、 TIMESTAMP_NTZ、 TIMESTAMP_TZに対応するネイティブデータ型はありません。データベースから TIMESTAMP 型の値を取得し、それを JavaScript 変数として保存する場合(値を ResultSet から JavaScript 変数にコピーするなど)、Snowflakeで定義された JavaScript データ型 SfDate を使用します。 SfDate (「SnowFlake 日付」)データ型は、 JavaScript 日付データ型の拡張です。 SfDate には追加のメソッドがありますが、これらについては以下で説明されています。

定数

なし。

メソッド

特に指定がない限り、以下の例では UTC タイムゾーンを想定しています。

getEpochSeconds()

このメソッドは、「エポック」の開始(1970年1月1日の午前0時)からの秒数を返します。

パラメーター

なし。

戻り値

1970年1月1日の午前0時から変数に保存されているタイムスタンプまでの秒数。

ストアドプロシージャを作成します。

CREATE OR REPLACE PROCEDURE test_get_epoch_seconds(TSV VARCHAR)
    RETURNS FLOAT
    LANGUAGE JAVASCRIPT
    AS
    $$
    var sql_command = "SELECT '" + TSV + "'::TIMESTAMP_NTZ;";
    var stmt = snowflake.createStatement( {sqlText: sql_command} );
    var resultSet = stmt.execute();
    resultSet.next();
    var my_sfDate = resultSet.getColumnValue(1);
    return my_sfDate.getEpochSeconds();
    $$
    ;

手順に異なるタイムスタンプを渡し、各タイムスタンプのエポックからの秒数を取得します。

CALL test_get_epoch_seconds('1970-01-01 00:00:00.000000000');
+------------------------+
| TEST_GET_EPOCH_SECONDS |
|------------------------|
|                      0 |
+------------------------+
CALL test_get_epoch_seconds('1970-01-01 00:00:01.987654321');
+------------------------+
| TEST_GET_EPOCH_SECONDS |
|------------------------|
|                      1 |
+------------------------+
CALL test_get_epoch_seconds('1971-01-01 00:00:00');
+------------------------+
| TEST_GET_EPOCH_SECONDS |
|------------------------|
|               31536000 |
+------------------------+
getNanoSeconds()

このメソッドは、オブジェクトのナノ秒フィールドの値を返します。これは、エポックの開始からのナノ秒ではなく、小数秒です。したがって、値は常に0と999999999の間です。

パラメーター

なし。

戻り値

ナノ秒数。

ストアドプロシージャを作成します。

CREATE OR REPLACE PROCEDURE test_get_nano_seconds2(TSV VARCHAR)
    RETURNS FLOAT
    LANGUAGE JAVASCRIPT
    AS
    $$
    var sql_command = "SELECT '" + TSV + "'::TIMESTAMP_NTZ;";
    var stmt = snowflake.createStatement( {sqlText: sql_command} );
    var resultSet = stmt.execute();
    resultSet.next();
    var my_sfDate = resultSet.getColumnValue(1);
    return my_sfDate.getNanoSeconds();
    $$
    ;
-- Should be 0 nanoseconds.
-- (> SNIPPET_TAG=query_03_01
CALL test_get_nano_seconds2('1970-01-01 00:00:00.000000000');

手順に異なるタイムスタンプを渡し、それぞれからナノ秒数を取得します。

CALL test_get_nano_seconds2('1970-01-01 00:00:00.000000000');
+------------------------+
| TEST_GET_NANO_SECONDS2 |
|------------------------|
|                      0 |
+------------------------+
CALL test_get_nano_seconds2('1970-01-01 00:00:01.987654321');
+------------------------+
| TEST_GET_NANO_SECONDS2 |
|------------------------|
|              987654321 |
+------------------------+
CALL test_get_nano_seconds2('1971-01-01 00:00:00.000123456');
+------------------------+
| TEST_GET_NANO_SECONDS2 |
|------------------------|
|                 123456 |
+------------------------+
getScale()

このメソッドは、データ型の精度、つまり小数点以下の桁数を返します。例えば、 TIMESTAMP_NTZ(3)の精度は3(ミリ秒)です。TIMESTAMP_NTZ(0)の精度は0(小数秒なし)です。TIMSTAMP_NTZの精度は9(ナノ秒)です。

最小値は0です。最大値は9(精度は1ナノ秒)です。デフォルトの精度は9です。

パラメーター

なし。

戻り値

小数点以下の桁数(小数秒フィールドの桁数)。

ストアドプロシージャを作成します。

CREATE OR REPLACE PROCEDURE test_get_scale(TSV VARCHAR, SCALE VARCHAR)
    RETURNS FLOAT
    LANGUAGE JAVASCRIPT
    AS
    $$
    var sql_command = "SELECT '" + TSV + "'::TIMESTAMP_NTZ(" + SCALE + ");";
    var stmt = snowflake.createStatement( {sqlText: sql_command} );
    var resultSet = stmt.execute();
    resultSet.next();
    var my_sfDate = resultSet.getColumnValue(1);
    return my_sfDate.getScale();
    $$
    ;

-- Should be 0.
-- (> SNIPPET_TAG=query_04_01
CALL test_get_scale('1970-01-01 00:00:00', '0');

この例では、タイムスタンプは TIMESTAMP_NTZ(0)として定義されているため、精度は0です。

CALL test_get_scale('1970-01-01 00:00:00', '0');
+----------------+
| TEST_GET_SCALE |
|----------------|
|              0 |
+----------------+

この例では、タイムスタンプは TIMESTAMP_NTZ(2)として定義されているため、精度は2です。

CALL test_get_scale('1970-01-01 00:00:01.123', '2');
+----------------+
| TEST_GET_SCALE |
|----------------|
|              2 |
+----------------+

この例では、タイムスタンプは TIMESTAMP_NTZとして定義されているため、精度は9であり、これがデフォルトです。

CALL test_get_scale('1971-01-01 00:00:00.000123456', '9');
+----------------+
| TEST_GET_SCALE |
|----------------|
|              9 |
+----------------+
getTimezone()

このメソッドは、タイムゾーンを UTCの前後の分数として返します。

パラメーター

なし。

戻り値

UTCの前後の分数としてのタイムゾーン。

ストアドプロシージャを作成します。

CREATE OR REPLACE PROCEDURE test_get_Timezone(TSV VARCHAR)
    RETURNS FLOAT
    LANGUAGE JAVASCRIPT
    AS
    $$
    var sql_command = "SELECT '" + TSV + "'::TIMESTAMP_TZ;";
    var stmt = snowflake.createStatement( {sqlText: sql_command} );
    var resultSet = stmt.execute();
    resultSet.next();
    var my_sfDate = resultSet.getColumnValue(1);
    return my_sfDate.getTimezone();
    $$
    ;

この例では、タイムゾーンは UTCから8時間(480分)遅れています。

CALL test_get_timezone('1970-01-01 00:00:01-08:00');
+-------------------+
| TEST_GET_TIMEZONE |
|-------------------|
|              -480 |
+-------------------+

この例では、タイムゾーンは UTCより11時間(660分)進んでいます。

CALL test_get_timezone('1971-01-01 00:00:00.000123456+11:00');
+-------------------+
| TEST_GET_TIMEZONE |
|-------------------|
|               660 |
+-------------------+
toString()
パラメーター

なし。

戻り値

このメソッドは、タイムスタンプの文字列表現を返します。

これは、 SfDate を作成して toString メソッドを呼び出す簡単な例を示しています。

CREATE OR REPLACE PROCEDURE test_toString(TSV VARCHAR)
    RETURNS VARIANT
    LANGUAGE JAVASCRIPT
    AS
    $$
    var sql_command = "SELECT '" + TSV + "'::TIMESTAMP_TZ;";
    var stmt = snowflake.createStatement( {sqlText: sql_command} );
    var resultSet = stmt.execute();
    resultSet.next();
    var my_sfDate = resultSet.getColumnValue(1);
    return my_sfDate.toString();
    $$
    ;
CALL test_toString('1970-01-02 03:04:05');
+-------------------------------------------+
| TEST_TOSTRING                             |
|-------------------------------------------|
| "Fri Jan 02 1970 03:04:05 GMT+0000 (UTC)" |
+-------------------------------------------+