Snowflake Native SDK for Connectors 入門

Snowflake Native SDK for Connectors は、外部データソースからSnowflakeにデータを取り込むSnowflakeネイティブアプリをビルドするために使用できるユニバーサルコンポーネントを提供するライブラリです。提供されるコンポーネントは、コネクタアプリケーションの推奨フローを定義し、カスタマイズを可能にし、取り込みロジックを構築するための構成要素を提供します。

Snowflake Native SDK for Connectors は、ローカルでプルおよび構築するコードとして配布されます。以下に、 SDK の構造、プロジェクトでの使用方法、アプリケーションのデプロイとインストール方法、開発中の使用方法に慣れるための情報を提供します。

プロジェクト構造

Snowflake Native SDK for Connectors は複数の部分で構成されており、以下で説明します。

  • connectors-native-sdk

このディレクトリには実際の Snowflake Native SDK for Connectors ソースコードとテストが含まれています。ネイティブアプリの性質上、Snowflake内のソースコードにはJavaコードだけでなく、データベースオブジェクト定義がバンドルされた SQL コードも含まれます。

Javaコードは、通常のJavaライブラリと同様に src/main ディレクトリにあります。 src/test 内にあるユニットテストも同様です。さらに、 src/ ディレクトリ内には、 intTest および appTest ディレクトリがあります。これらはそれぞれ、統合テストとアプリケーションテストです。これら両方のテストタイプでは、Snowflakeアカウントへの接続が必要です。前者は、スタンドアロンのデータベースオブジェクトを使用して SDK コンポーネントをテストしますが、後者は実際のアプリケーションをデプロイし、それを使用してテストを実行します。

SQL ソースファイルは src/main/resources ディレクトリ内に含まれています。これらは、 Snowflake Native SDK for Connectors を構築するときにjarアーカイブ内に含まれます。これらを使用するには、jarから抽出し、アプリケーションパッケージ内のSnowflakeステージにコピーされる構築ターゲットディレクトリ内に置く必要があります。

  • connectors-native-sdk-test

このディレクトリには、 Snowflake Native SDK for Connectors に基づいてコネクタのユニットテストを簡単に行えるように設計されたヘルパーライブラリが含まれています。これは、一部のデータベースオブジェクトのモック実装、カスタマイズできないコードの一部を上書きできる特別に設計されたテストビルダー、および AssertJ ライブラリ に基づくいくつかのカスタムアサーションを提供します。

SDK のインストールと使用方法

現在、 Snowflake Native SDK for Connectors をインストールして使用するには、開発者が手動でいくつかのアクションを実行する必要があります。

Snowflake Native SDK for Connectors ライブラリはMaven Centralから入手できます

repositories {
    mavenCentral()
}

dependencies {
    compileOnly 'com.snowflake:connectors-native-sdk:2.0.0'
    testImplementation 'com.snowflake:connectors-native-sdk-test:2.0.0'
}

提供された SQL ファイルにアクセスするには、それらをネイティブアプリのターゲットディレクトリに抽出する必要があります。これを実現するには、次のGradleタスク定義を使用します(現時点では、 build.gradle ファイルに手動でコピーする必要があります)。

String defaultBuildDir = './sf_build'
String defaultSrcDir = './app'
String libraryName = 'connectors-native-sdk'

project.tasks.register('copySdkComponents') {
    it.group = 'Snowflake'
    it.description = "Copies .sql files from ${sdkComponentsDirName} directory to the connector build file."
    doLast {
        copySdkComponents(libraryName, defaultBuildDir, sdkComponentsDirName)
    }
}

private void copySdkComponents(String libraryName, String defaultBuildDir, String sdkComponentsDirName) {
    TaskLogger.info("Starting 'copySdkComponents' task...")
    def targetDir = getCommandArgument('targetDir', {defaultBuildDir})

    try {
        project.copy {
            TaskLogger.info("Copying [${sdkComponentsDirName}] directory with .sql files to '${targetDir}'")
            from project.zipTree(project.configurations.compileClasspath.find {
                it.name.startsWith(libraryName)})
            into targetDir
            include "${sdkComponentsDirName}/**"
        }
    } catch (IllegalArgumentException e) {
        Utils.exitWithErrorLog("Unable to find [${libraryName}] in the compile classpath. Make sure that the library is " +
                "published to Maven local repository and the proper dependency is added to the build.gradle file.")
    }
    project.copy {
        TaskLogger.info("Copying [${libraryName}] jar file to [${targetDir}]")
        from configurations.runtimeClasspath.find {
            it.name.startsWith(libraryName)
        }
        into targetDir
        rename ("^.*${libraryName}.*\$", "${libraryName}.jar")
    }
    TaskLogger.success("Copying sdk components finished successfully.")
}
Copy

このタスクを実行するには:

./gradlew copySdkComponents
Copy

抽出された SQL ファイルは、ネイティブアプリの setup.sql の実行中に実行できます。

展開とインストール

Snowflake Native SDK for Connectors は Snowflake Native App Framework と一緒に使用するように設計されています。つまり、他のネイティブアプリと同じようにデプロイとインストールが行われます。つまり、最初にアプリケーションパッケージを作成し、すべてのファイルをステージにアップロードする必要があるため、アプリケーションパッケージ内にステージを作成することをお勧めします。上記のサンプルスクリプトが使用された場合、 Snowflake Native SDK for Connectors からの必要なファイルはすべて、コネクタのターゲットビルドディレクトリにすでに存在しているはずです。つまり、コネクタのカスタムコードとStreamlitファイルも存在することを確認するのは開発者の責任です。詳細については、 アプリケーションパッケージの作成 をご参照ください。

アプリケーションパッケージが作成され、ステージにファイルがアップロードされると、アプリケーションの version を作成できます。。アプリケーションインスタンスは登録済みバージョンを使用する代わりにステージ内のファイルから直接作成できるため、開発中はこのステップはオプションです。詳細については、 アプリケーションオブジェクトの作成 をご参照ください。

開発

Snowflake Native SDK for Connectors は、各コネクタアプリケーションの一般的なユースケースを処理するオブジェクトとプロシージャを提供します。これには、構成、ライフサイクル、インジェスチョン定義などが含まれます。機能の全リストを確認するには、 SDK リファレンスをご参照ください。定義済み機能の一部はカスタマイズできます。詳細については、「ストアドプロシージャとハンドラーのカスタマイズ」をご参照ください。

テスト

前述のとおり、コネクタネイティブ SDK にはさまざまな種類のテストが含まれています。これには単体テスト、統合テスト、アプリケーションテストが含まれます。ユニットテストは、前述の connectors-native-sdk-test で提供されている機能を使用します。統合テストとアプリケーションテストでは、Snowflakeへの接続が必要です。接続の詳細は、 .env/snowflake_credentials ファイルを使用して定義できます。アプリケーションテストディレクトリには、リソース内の空のコネクタアプリケーションも含まれています。そのアプリケーションは、テストスイートの実行中にデプロイされます

追加のリソース:

独自のコネクタの実装を体験するには、 チュートリアル: Native SDK for ConnectorsのJavaテンプレート をお試しください。