SnowSQLから|sf-cli|への移行¶

|sf-cli|ソフトウェアをインストールする¶

SnowSQLと同様に、|sf-cli|には:ref:`バイナリインストーラ<label-snowcli_install_package_managers>`が用意されています。さらに、:ref:`homebrew<label-snowcli_install_homebrew>`と:ref:`pip<label-snowcli_install_pip>`を使用してソフトウェアをインストールすることもできます。

現在、|sf-cli|は次のプラットフォームをサポートしています。

• macOS（arm）

  • パッケージインストーラ

  • Homebrew

  • PyPi（pip）

• macOS（x86_64）:

  • パッケージインストーラ

  • Homebrew

  • PyPi（pip）

• Linux（x86_64、aarch64）:

  • debパッケージインストーラ

  • rpmパッケージインストーラ

  • PyPi（pip）

• Windows（64ビット）:

  • インストーラ

  • PyPi（pip）

現在、SnowflakeCLIは次のプラットフォームをサポートしていません。

• Linux bashインストーラ

|sf-cli|のインストールについて詳しくは、:doc:`/developer-guide/snowflake-cli/installation/installation`をご覧ください。

SnowSQLの接続と設定を移行する¶

|sf-cli|には、SnowSQLから|sf-cli|への移行プロセスを簡素化する:doc:`snow helpers</developer-guide/snowflake-cli/command-reference/helpers-commands/overview>`コマンドグループが用意されています。次のコマンドを使用すると、既存の接続と環境変数を簡単にインポートできます。

• snow helpers import-snowsql-connections</developer-guide/snowflake-cli/command-reference/helpers-commands/import-snowsql-connections>`コマンドでは、インタラクティブメニューを使用して、インポートするSnowSQL接続を選択できます。詳細については、 :ref:`label-snowcli_import_connections_snowsql をご参照ください。

• snow helpers check-snowsql-env-vars</developer-guide/snowflake-cli/command-reference/helpers-commands/check-snowsql-env-vars>`コマンドでは、SnowSQL環境で設定されている環境変数を診断し、対応する|sf-cli|の変数を表示することができます。詳細については、 :doc:/developer-guide/snowflake-cli/project-definitions/use-sql-variables` をご参照ください。

SnowSQLを使用してインラインSQLステートメントまたはファイルを実行するが、すべてのスクリプトを編集したくない場合は、:codenowrap:`snowsql`を :codenowrap:`snow sql`コマンドにマッピングするエイリアスを作成することを検討してください。。たとえばUnix系のシステムでは次のコマンドを使用します。

alias snowsql='snow sql'

このエイリアスにより、既存のスクリプトを|sf-cli|で使用できます。

なお、上級者のSnowSQLユーザーの場合、通常はSnowSQLの構成に使用されるオプションに関連した、非互換性に関するメッセージが表示されることがあります。|sf-cli|はすべてのSnowSQL構成オプションを使用するわけではないため、スクリプトのコピーを作成し、互換性のないオプションを削除する必要が生じる場合があります。

SnowSQLにロールバックする¶

|sf-cli|は独自の構成ファイルを使用するため、SnowSQLを引き続き使用できます。SnowSQLと|sf-cli|の両方をインストールし、独立して実行することができます。上記のようにエイリアスを設定した場合、SnowSQLの :codenowrap:`snowsql`コマンドを使用するには、エイリアスを削除する必要があります。

構成ファイルの相違¶

• SnowSQL

  SnowSQLは、TOML形式のファイルである:ref:構成ファイル<label-configuring_snowsql>`で構成されます。これには、接続設定、ツールのさまざまな設定、SQLクエリで使用できる変数が含まれます。構成は複数の場所に分割できるため、システム全体のデフォルトを定義し、ユーザーごとにオーバーライドすることができます。:codenowrap:--config`コマンドラインオプションを指定することで、カスタムの場所から構成を指定することもできます。詳細については、 接続パラメーターリファレンス をご参照ください。

• Snowflake CLI

  |sf-cli|にも、接続構成や</developer-guide/snowflake-cli/connecting/configure-cli>`ツールの設定を指定する独自のTOML:doc:構成ファイルがあります。SQLクエリで後で使用するために変数を定義することはできません。|sf-cli|の変数は、:doc:`プロジェクト定義ファイル</developer-guide/snowflake-cli/project-definitions/use-sql-variables>`において、プロジェクトレベルで定義されます。|sf-cli|は、デフォルトでユーザーのホームディレクトリにある1つの構成ファイルのみを使用します。:codenowrap:--config`コマンドラインオプションを指定することで、カスタムの場所から構成を指定することもできます。詳細については、 snow コマンドリファレンスをご参照ください。

|sf-cli|のデフォルトの構成ファイルを見つける¶

デフォルトの|sf-cli|構成の場所はシステムによって異なり、:ref:`label-cli_config_locations`で指定された順序によって決まります。

• |sf-cli|のインストールについて、:codenowrap:`default_config_file_path`パラメーターの値を確認するには、次のように :codenowrap:`snow --info`コマンドを実行します。

  snow --info
  

  Copy

  [
    ...
  
    {
        "key": "default_config_file_path",
        "value": "/<user_home>/.snowflake/config.toml"
    },
  
    ...
  ]
  

SnowSQL からの接続をインポートします。¶

codenowrap:snow helpers import-snowsql-connections`コマンドを使用して、すべてのSnowSQL接続をインポートできます。詳細については、:ref:`label-snowcli_import_connections_snowsql`と:doc:/developer-guide/snowflake-cli/command-reference/helpers-commands/import-snowsql-connections`のコマンドリファレンスをご覧ください。

デフォルトの接続構成を手動で移行する¶

:codenowrap:`snow helpers import-snowsql-connections`コマンドを使用した接続のインポートを行わないことにした場合、デフォルトの接続を手動で移行できます。

デフォルトの接続の指定の違いとしては、以下のような点が挙げられます。

• SnowSQL

  デフォルトの接続はSnowSQL:ref:`構成ファイル<label-configuring_snowsql>`で構成され、接続設定は:ref:`[connections]<label-connecting_default_connection_settings>`セクションで直接定義されています。

• Snowflake CLI

  デフォルトの接続は|sf-cli|:doc:`構成ファイル</developer-guide/snowflake-cli/connecting/configure-cli>`で、:codenowrap:`default_connection_name`という名前付きの接続として構成され、構成の最上位に設定されます（:ref:`label-cli_set_default_connection`参照）。:codenowrap:`snow connection set-default`コマンドを使用すると、デフォルトの接続を変更できます。

デフォルトでは、SnowSQLも|sf-cli|もデフォルトの接続構成を使用してSnowflakeに接続します。SnowSQLで構成している場合は、次のようにしてこの構成を|sf-cli|構成ファイルに移行する必要があります。

1. SnowSQL構成ファイルを開き、:codenowrap:`[connections]`セクションのデフォルトの接続パラメーターを確認します。|sf-cli|に接続を追加する際、この接続パラメーターの値が必要になります。

2. |sf-cli|に接続を追加するには、次のいずれかのメソッドを使用します。

   • 次のように、|sf-cli|構成ファイルを手動で編集します。

     1. |sf-cli|構成ファイルを開きます。

     2. :codenowrap:`[connections.your_connection_name]`セクションを追加し、SnowSQL構成ファイルからデフォルトの構成の詳細をコピーして貼り付けます。

     3. パラメーターの名前を次のように変更します。

        • accountname から account

        • username から user

        • dbname から database

        • schemaname から schema

        • warehousename から warehouse

        • rolename から role

     4. 構成ファイルの最上位に、:codenowrap:`default_connection_name = "your_connection_name"`設定を追加または設定します（:ref:`label-cli_set_default_connection`参照）。

   • snow connection add`コマンドと :codenowrap:`snow connection set-default`コマンドを使用します。詳細については、 :ref:`label-snowcli_snow_connection_command をご参照ください。

名前付き接続構成を手動で移行する¶

接続のインポートに :codenowrap:`snow helpers import-snowsql-connections`コマンドを使用しない場合は、手動で移行できます。

名前付き接続の指定の違いとしては、以下のような点が挙げられます。

• SnowSQL

  名前付き接続はSnowSQL:ref:`構成ファイル<label-connecting_named_connection>`で構成されます。それぞれの名前付き接続には独自の :codenowrap:`[connections.your_connection_name]`セクションがあります。

• Snowflake CLI

  Snowflake CLIは、:ref:`名前付き接続の構成<label-snowcli_define_connections>`にほぼ同じ形式を使用します。SnowSQL構成からコピーして、デフォルトの接続で指定されているようにパラメーター名を変更することができます。

デフォルトでは、SnowSQLでも|sf-cli|でも、名前付き接続を使用してSnowflakeに接続できます。SnowSQLでそうした名前付き接続を引き続き使用する場合は、|sf-cli|構成ファイルに移行する必要があります。

1. SnowSQL構成ファイルを開き、:codenowrap:`[connections.your_connection_name]`セクションを探します。|sf-cli|に:ref:`接続<label-snowsql_migration_migrate_connections>`を追加するときは、接続パラメーターの値が必要です。

2. |sf-cli|に接続を追加するには、次のいずれかのメソッドを使用します。

   • 次のように、|sf-cli|構成ファイルを手動で編集します。

     1. |sf-cli|構成ファイルを開きます。

     2. :codenowrap:`[connections.your_connection_name]`セクションを追加し、SnowSQL構成ファイルからデフォルトの構成の詳細をコピーして貼り付けます。

     3. パラメーターの名前を次のように変更します。

        • accountname から account

        • username から user

        • dbname から database

        • schemaname から schema

        • warehousename から warehouse

        • rolename から role

   • snow connection add`コマンドを使用します。詳細については、 :ref:`label-snowcli_snow_connection_command をご参照ください。

ログを構成する¶

|sf-cli|のログを手動で構成する方法については、:ref:`label-snowcli_configure_logging`のドキュメントをご覧ください。

変数を移行する¶

|sf-cli|は構成ファイルによる変数の指定をサポートしていません。代わりに、変数を特定のプロジェクトに関連付けるプロジェクト中心のアプローチを使用しています。|sf-cli|では、snowflake.ymlプロジェクト定義ファイル</developer-guide/snowflake-cli/project-definitions/about>`で変数を定義できます。これらの変数は、:doc:/developer-guide/snowflake-cli/project-definitions/about`に記載されているように、SQLクエリで使用できます。

• プロジェクトの変数を定義するには、プロジェクトの:file:`snowflake.yml`ファイルに :codenowrap:`env`セクションを追加し、クエリで使用する変数をすべて指定します。

次の例では、database、:codenowrap:`role`という2つの変数を定義しています。

definition_version: 2
env:
  database: "dev"
  role: "eng_rl"

環境変数を手動で移行する¶

SnowSQLでは、接続を開始するとき、コマンドラインパラメーターを指定する代わりに環境変数（codenowrap:$SNOWSQL_ACCOUNT、:codenowrap:`$SNOWSQL_DATABASE`など）を使用できます。このアプローチにより、デフォルトの接続構成を指定するために別の方法をとることができます。|sf-cli|は同様の機能を提供しますが、パラメーター名が異なっており、環境変数を介してより多くの構成パラメーターをオーバーライドできます。環境変数を使用してSnowflakeに接続する場合の詳細については、:ref:`環境変数を使用してSnowflakeに接続する<label-snowcli_environment_creds>`をご覧ください。また|sf-cli|のドキュメントで、:ref:`環境変数を構成する<label-snowcli_env_var_support>`可能性についての情報もご確認ください。

デフォルトの接続を使用する¶

• 構成ファイルで定義されたデフォルトの構成を使用して接続するには:

  • SnowSQL

    snowsql -q "select 1"
    

    Copy

  • Snowflake CLI

    snow sql -q "select 1"
    

    Copy

コマンドラインオプションで接続を使用する¶

• 構成ファイルで定義されたデフォルトの構成を使用して接続し、コマンドラインオプションでパラメーターをオーバーライドするには:

  • SnowSQL

    snowsql --username myname -q "select 1"
    

    Copy

  • Snowflake CLI

    snow sql --username myname -q "select 1"
    

    Copy

    使用可能なコマンドラインオプションのリストについては、:doc:`/developer-guide/snowflake-cli/command-reference/sql-commands/sql`をご覧ください。なお一部のオプションは、SnowSQLとは名前が異なります。

名前付き構成を使用する¶

• 構成ファイルで定義された名前付き構成を使用して接続するには:

  • SnowSQL

    snowsql -c dev -q "select 1"
    

    Copy

  • Snowflake CLI

    snow sql -c dev -q "select 1"
    

    Copy

コマンドラインオプションのみを使用する¶

• 構成された接続の代わりにコマンドラインオプションのみを使用して接続するには:

  • SnowSQL

    snowsql \
      --accountname myaccount \
      --username myuser \
      --authenticator SNOWFLAKE_JWT \
      --private-key-path "path_to_my_key" \
      -q "select 1"
    

    Copy

  • Snowflake CLI

    snow sql \
      --temporary-connection \
      --accountname myaccount \
      --username myuser \
      --authenticator SNOWFLAKE_JWT \
      --private-key-path "path_to_my_key" \
      -q "select 1"
    

    Copy

    なお、この方法をとる場合、|sf-cli|は :codenowrap:`--temporary-connection`オプションを必要とします。

環境変数を使用する¶

• デフォルトの接続を使用して接続するには、複数のパラメーターを環境変数として渡します。

  • SnowSQL

    export SNOWSQL_USER=myuser
    snowsql -q "select 1"
    

    Copy

  • Snowflake CLI

    export SNOWFLAKE_USER=myuser
    snow sql -q "select 1"
    

    Copy

    環境変数の名前は異なる場合があります。詳細については、 Snowflake認証情報に環境変数を使用する をご参照ください。

接続、環境変数、コマンドラインオプションを組み合わせて使用する¶

• 名前付き接続、環境変数、コマンドラインオプションを組み合わせたアプローチを使用して接続するには:

  • SnowSQL

    export SNOWSQL_USER=myuser
    snowsql -c dev --accountname myaccount -q "select 1"
    

    Copy

  • Snowflake CLI

    export SNOWFLAKE_USER=myuser
    snow sql -c dev --accountname myaccount -q "select 1"
    

    Copy

    この方法は、デフォルトの接続と名前付き接続の両方で使用できます。

さまざまな入力からSQLクエリを実行する¶

|sf-cli|では、SQLで処理されるものと同様の入力を使用してSnowSQLクエリを実行できます。以下の例では、さまざまな入力を使用してSQLクエリを実行します。

• コマンドラインパラメーターを使用してクエリを実行する

  • SnowSQL

    snowsql -q "select 1"
    

    Copy

  • Snowflake CLI

    snow sql -q "select 1"
    

    Copy

• ファイルからクエリを実行する

  • SnowSQL

    snowsql -f test.sql
    

    Copy

  • Snowflake CLI

    snow sql -f test.sql
    

    Copy

• 標準の入力からクエリを実行する

  • SnowSQL

    cat test.sql | snowsql
    

    Copy

  • Snowflake CLI

    cat test.sql | snow sql --stdin
    

    Copy

クエリ結果をJSONファイルに保存する¶

|sf-cli|は現在、:ref:`SnowSQLの出力形式オプション<label-snowsql_export_data>`のすべてをサポートしているわけではありません。|sf-cli|では、クエリ結果を形式設定されたテーブルまたはJSONとして保存できます。CSVやその他の形式はまだ利用できませんが、`jq <https://jqlang.org/>`_などの外部ツールを使用して、JSONデータを他の形式に変換することができます。

• SnowSQL

  snowsql \
    -f test.sql \
    -o "output_format=json" \
    -o "output_file=result.json"
  

  Copy

• Snowflake CLI

  snow sql -f test.sql --format json > result.json
  

  Copy

変数を使用してクエリを実行する¶

SnowSQLも|sf-cli|も、クエリで変数を使用できます。SnowSQLでは、コマンドラインオプション、構成ファイル、いくつかの:ref:`組み込み変数<label-snowsql_variables>`により、変数を使用できます。|sf-cli|は構成ファイルの変数や組み込み変数の使用はサポートしていませんが、コマンドラインオプションによるパラメーターの指定や、プロジェクト定義ファイルによる変数の指定はサポートしています。SnowSQL構成ファイルの変数の移行について詳しくは、:ref:`label-snowsql_migration_variables`をご覧ください。

SnowSQLの構成から変数を移行したら、コマンドラインオプションとプロジェクト定義の両方から変数を使用して|sf-cli|クエリを実行できます。

変数を使用する場合、SnowSQLと|sf-cli|の間には次のような大きな違いがあることに注意してください。

• 変数の置換に使用する構文が異なります。SnowSQLは :codenowrap:`&variable`または :codenowrap:`&{variable}`構文を使用しますが、|sf-cli|は :codenowrap:`<% variable %>`を使用します。SnowSQLの構文は現在サポートされていますが、非推奨です。

• |sf-cli|では変数置換が自動的に有効になるため、SnowSQLの場合のように明示的に有効にする必要はありません。

• |sf-cli|プロジェクト定義ファイル内の変数名は、以下に示すように、:codenowrap:`ctx.env`で始める必要があります。

以下の例は、変数を使用してSQLクエリを実行する場合の違いを示しています。

• コマンドラインオプションで変数を使用してクエリを実行する（:codenowrap:`x`は変数名）

  • SnowSQL

    snowsql \
      -o variable_substitution=true \
      -q "select &x" \
      -D x=1
    

    Copy

  • Snowflake CLI

    snow sql \
      -q "select <% x %>" \
      -D x=1
    

    Copy

  • |sf-cli|（迅速な移行をしやすくするために非推奨の構文を使用）

    snow sql \
      -q "select &x" \
      -D x=1
    

    Copy

• SnowSQL構成と|sf-cli|プロジェクト定義ファイルで変数を使用してクエリを実行する

  • SnowSQL

    # save variables to config
    echo "[variables]
    xyz=Hello World" > custom_config
    
    
    # execute query
    snowsql \
      --config custom_config \
      -o variable_substitution=true \
      -q "select '&{xyz}'"
    

    Copy

  • Snowflake CLI

    # save variables to project definition
    echo "definition_version: 2
    env:
      xyz: Hello World" > snowflake.yml
    
    # execute query
    snow sql -q "select '<% ctx.env.xyz %>'"
    

    Copy

  • |sf-cli|（迅速な移行をしやすくするために非推奨の構文を使用）

    # save variables to project definition
    echo "definition_version: 2
    env:
      xyz: Hello World" > snowflake.yml
    
    
    # execute query
    snow sql -q "select '&{ctx.env.xyz}'"
    

    Copy