外部 Apache Hive Metastore External Apache Hive Metastore

この記事では、既存の外部 Apache Hive メタストアに接続するように Azure Databricks クラスターを設定する方法について説明します。This article describes how to set up Azure Databricks clusters to connect to existing external Apache Hive metastores. ここでは、推奨される metastore セットアップとクラスター構成の要件について説明し、その後に、外部 metastore に接続するようにクラスターを構成するための手順を示します。It provides information about recommended metastore setup and cluster configuration requirements, followed by instructions for configuring clusters to connect to an external metastore. 次の表は、Databricks Runtime の各バージョンでサポートされている Hive metastore バージョンをまとめたものです。The following table summarizes which Hive metastore versions are supported in each version of Databricks Runtime.

Databricks Runtime のバージョンDatabricks Runtime Version 0.13-1.2.10.13 - 1.2.1 2.12.1 2.22.2 2.32.3 3.1.03.1.0
5.3 以上5.3 and above はい。Yes はい。Yes はい。Yes はい。Yes はい。Yes
5.1-5.2 および4.x5.1 - 5.2 and 4.x はい。Yes はい。Yes はい。Yes はい。Yes NoNo
3.x3.x はい。Yes はい。Yes NoNo NoNo NoNo

重要

  • SQL Server は、Hive 2.0 以降の基になる metastore データベースとしては機能しません。SQL Server does not work as the underlying metastore database for Hive 2.0 and above.
  • HDInsight クラスターの Hive 1.2.0 または 1.2.1 metastore を外部 metastore として使用できます。You can use a Hive 1.2.0 or 1.2.1 metastore of an HDInsight cluster as an external metastore. Azure HDInsight での外部メタデータストアの使用」を参照してください。See Use external metadata stores in Azure HDInsight.
  • Azure Database for MySQL を外部 metastore として使用するには、サーバー側のデータベース構成で、lower_case_table_names プロパティの値を 1 (既定値) から2に変更する必要があります。To use Azure Database for MySQL as an external metastore, you must change the value of the lower_case_table_names property from 1 (the default) to 2 in the server-side database configuration. 詳細については、「識別子大文字小文字の区別」を参照してください。For details, see Identifier Case Sensitivity.

Hive metastore セットアップHive metastore setup

注意

このドキュメントの例では、基になる metastore データベースとして Azure SQL database を使用します。The examples in this document use Azure SQL database as the underlying metastore database.

クラスター内で実行されている metastore クライアントは、JDBC を使用して、基になる metastore データベースに直接接続します。The metastore client running inside a cluster connects to your underlying metastore database directly using JDBC.

クラスターから metastore へのネットワーク接続をテストするには、notebook 内で次のコマンドを実行します。To test network connectivity from a cluster to the metastore, you can run the following command inside a notebook:

%sh
nc -vz <DNS name> <port>

各値の説明:where

  • <DNS name> は、Azure SQL データベースのサーバー名です。<DNS name> is the server name of the Azure SQL database.
  • <port> は、データベースのポートです。<port> is the port of the database.

クラスター構成Cluster configurations

クラスターを外部 metastore に接続するには、次の2つの構成オプションセットを設定する必要があります。You must set two sets of configuration options to connect a cluster to an external metastore:

  • Spark オプションでは、metastore クライアントの Hive metastore バージョンと jar を使用して spark を構成します。Spark options configure Spark with the Hive metastore version and the JARs for the metastore client.
  • Hive オプションmetastore クライアントが外部 metastore に接続するように構成します。Hive options configure the metastore client to connect to the external metastore.

Spark 構成オプション Spark configuration options

spark.sql.hive.metastore.version を Hive metastore のバージョンに設定し、次のように spark.sql.hive.metastore.jars します。Set spark.sql.hive.metastore.version to the version of your Hive metastore and spark.sql.hive.metastore.jars as follows:

  • Hive 0.13: spark.sql.hive.metastore.jarsを設定しないでください。Hive 0.13: do not set spark.sql.hive.metastore.jars.
  • Hive 1.2.0 または 1.2.1: spark.sql.hive.metastore.jarsbuiltinに設定します。Hive 1.2.0 or 1.2.1: set spark.sql.hive.metastore.jars to builtin.
  • その他のすべての Hive バージョンでは Azure Databricks、次の手順を使用して、metastore Jar をダウンロードし、ダウンロードした Jar をポイントするように構成 spark.sql.hive.metastore.jars を設定することをお勧めします。For all other Hive versions, Azure Databricks recommends that you download the metastore JARs and set the configuration spark.sql.hive.metastore.jars to point to the downloaded JARs using the following procedure:
    1. spark.sql.hive.metastore.jarsmaven に設定してクラスターを作成し、metastore のバージョンと一致するように spark.sql.hive.metastore.version します。Create a cluster with spark.sql.hive.metastore.jars set to maven and spark.sql.hive.metastore.version to match the version of your metastore.

    2. クラスターが実行されているときに、ドライバーログを検索し、次のような行を見つけます。When the cluster is running, search the driver log and find a line like the following:

      17/11/18 22:41:19 INFO IsolatedClientLoader: Downloaded metastore jars to <path>
      

      ディレクトリ <path> は、クラスターのドライバーノードでダウンロードされた Jar の場所です。The directory <path> is the location of downloaded JARs in the driver node of the cluster.

      別の方法として、次のコードを1つの notebook で実行して、Jar の場所を出力することもできます。Alternatively you can run the following code in a Scala notebook to print the location of the JARs:

      import com.typesafe.config.ConfigFactory
      val path = ConfigFactory.load().getString("java.io.tmpdir")
      
      println(s"\nHive JARs are downloaded to the path: $path \n")
      
    3. %sh cp -r <path> /dbfs/hive_metastore_jar を実行し (<path> を実際のクラスター情報に置き換えて)、このディレクトリを DBFS 内のディレクトリにコピーします。このディレクトリは、[ドライバー] ノードの [ヒューズ] クライアントを使用して hive_metastore_jar と呼ばれます。Run %sh cp -r <path> /dbfs/hive_metastore_jar (replacing <path> with your cluster’s info) to copy this directory to a directory in DBFS called hive_metastore_jar through the Fuse client in the driver node.

    4. ノードのローカルファイルシステムに /dbfs/hive_metastore_jar をコピーするinit スクリプトを作成します。このスクリプトは、DBFS ヒューズクライアントにアクセスする前に、init スクリプトが数秒でスリープ状態になるようにします。Create an init script that copies /dbfs/hive_metastore_jar to the local filesystem of the node, making sure to make the init script sleep a few seconds before it accesses the DBFS Fuse client. これにより、クライアントの準備が完了します。This ensures that the client is ready.

    5. このディレクトリを使用するように spark.sql.hive.metastore.jars を設定します。Set spark.sql.hive.metastore.jars to use this directory. Init スクリプトで /dbfs/hive_metastore_jar/databricks/hive_metastore_jars/にコピーする場合は、spark.sql.hive.metastore.jars/databricks/hive_metastore_jars/*に設定します。If your init script copies /dbfs/hive_metastore_jar to /databricks/hive_metastore_jars/, set spark.sql.hive.metastore.jars to /databricks/hive_metastore_jars/*. 場所には /*の末尾が含まれている必要があります。The location must include the trailing /*.

    6. クラスターを再起動します。Restart the cluster.

Hive 構成オプション Hive configuration options

このセクションでは、Hive に固有のオプションについて説明します。This section describes options specific to Hive.

ローカルモードを使用して外部 metastore に接続するには、次の Hive 構成オプションを設定します。To connect to an external metastore using local mode, set the following Hive configuration options:

# JDBC connect string for a JDBC metastore
javax.jdo.option.ConnectionURL <mssql-connection-string>

# Username to use against metastore database
javax.jdo.option.ConnectionUserName <mssql-username>

# Password to use against metastore database
javax.jdo.option.ConnectionPassword <mssql-password>

# Driver class name for a JDBC metastore
javax.jdo.option.ConnectionDriverName com.microsoft.sqlserver.jdbc.SQLServerDriver

各値の説明:where

  • <mssql-connection-string> は、JDBC 接続文字列です (Azure portal で取得できます)。<mssql-connection-string> is the JDBC connection string (which you can get in the Azure portal). 接続文字列にユーザー名とパスワードを含める必要はありません。これは javax.jdo.option.ConnectionUserNamejavax.jdo.option.ConnectionDriverNameによって設定されるためです。You do not need to include username and password in the connection string, because these will be set by javax.jdo.option.ConnectionUserName and javax.jdo.option.ConnectionDriverName.
  • <mssql-username><mssql-password>、データベースへの読み取り/書き込みアクセス権を持つ Azure SQL database アカウントのユーザー名とパスワードを指定します。<mssql-username> and <mssql-password> specify the username and password of your Azure SQL database account that has read/write access to the database.

注意

運用環境では、hive.metastore.schema.verificationtrueに設定することをお勧めします。For production environments, we recommend that you set hive.metastore.schema.verification to true. これにより、metastore client のバージョンが metastore database のバージョンと一致しない場合に Hive metastore クライアントが metastore データベーススキーマを暗黙的に変更するのを防ぐことができます。This prevents Hive metastore client from implicitly modifying the metastore database schema when the metastore client version does not match the metastore database version. Hive 1.2.0 よりも前のバージョンの metastore クライアントでこの設定を有効にする場合は、metastore クライアントが metastore データベースに対する書き込みアクセス許可を持っていることを確認します ( hive-9749で説明されている問題を回避するため)。When enabling this setting for metastore client versions lower than Hive 1.2.0, make sure that the metastore client has the write permission to the metastore database (to prevent the issue described in HIVE-9749).

  • Hive metastore 1.2.0 以降では、hive.metastore.schema.verification.record.versiontrue に設定して hive.metastore.schema.verificationを有効にします。For Hive metastore 1.2.0 and higher, set hive.metastore.schema.verification.record.version to true to enable hive.metastore.schema.verification.
  • Hive metastore 2.1.1 以降では、既定で false に設定されているため、hive.metastore.schema.verification.record.versiontrue に設定します。For Hive metastore 2.1.1 and higher, set hive.metastore.schema.verification.record.version to true as it is set to false by default.

UI を使用した外部 metastore の設定Set up an external metastore using the UI

Azure Databricks UI を使用して外部 metastore を設定するには、次のようにします。To set up an external metastore using the Azure Databricks UI:

  1. サイドバーの [クラスター] ボタンをクリックします。Click the Clusters button on the sidebar.

  2. [クラスターの作成] をクリックします。Click Create Cluster.

  3. 次のSpark 構成オプションを入力します。Enter the following Spark configuration options:

    # Hive-specific configuration options.
    # spark.hadoop prefix is added to make sure these Hive specific options propagate to the metastore client.
    # JDBC connect string for a JDBC metastore
    spark.hadoop.javax.jdo.option.ConnectionURL <mssql-connection-string>
    
    # Username to use against metastore database
    spark.hadoop.javax.jdo.option.ConnectionUserName <mssql-username>
    
    # Password to use against metastore database
    spark.hadoop.javax.jdo.option.ConnectionPassword <mssql-password>
    
    # Driver class name for a JDBC metastore
    spark.hadoop.javax.jdo.option.ConnectionDriverName com.microsoft.sqlserver.jdbc.SQLServerDriver
    
    # Spark specific configuration options
    spark.sql.hive.metastore.version <hive-version>
    # Skip this one if <hive-version> is 0.13.x.
    spark.sql.hive.metastore.jars <hive-jar-source>
    
  4. クラスター構成の手順に従って、クラスター構成を続行します。Continue your cluster configuration, following the instructions in Cluster Configurations.

  5. [クラスターの作成] をクリックしてクラスターを作成します。Click Create Cluster to create the cluster.

Init スクリプトを使用した外部 metastore の設定Set up an external metastore using an init script

Init スクリプトを使用すると、必要な構成を手動で設定しなくても、既存の Hive metastore に接続できます。Init scripts let you connect to an existing Hive metastore without manually setting required configurations.

  1. Init スクリプトを格納するベースディレクトリが存在しない場合は、作成します。Create the base directory you want to store the init script in if it does not exist. 次の例では、dbfs:/databricks/scriptsを使用します。The following example uses dbfs:/databricks/scripts.

  2. Notebook で次のスニペットを実行します。Run the following snippet in a notebook. このスニペットは、 Databricks File System (DBFS)で init スクリプト /databricks/scripts/external-metastore.sh を作成します。The snippet creates the init script /databricks/scripts/external-metastore.sh in Databricks File System (DBFS). または、 DBFS REST API の put 操作を使用して、init スクリプトを作成することもできます。Alternatively, you can use the DBFS REST API’s put operation to create the init script. この init スクリプトは、<cluster-name> として指定された名前のクラスターが開始されるたびに、必要な構成オプションを、クラスターのすべてのノード内の /databricks/driver/conf/ 下にある JSON 形式の 00-custom-spark.conf という名前の構成ファイルに書き込みます。This init script writes required configuration options to a configuration file named 00-custom-spark.conf in a JSON-like format under /databricks/driver/conf/ inside every node of the cluster, whenever a cluster with the name specified as <cluster-name> starts. Azure Databricks は、/databricks/driver/conf/spark-branch.conf ファイルに既定の Spark 構成を提供します。Azure Databricks provides default Spark configurations in the /databricks/driver/conf/spark-branch.conf file. /databricks/driver/conf ディレクトリ内の構成ファイルは、アルファベットの逆順に適用されます。Configuration files in the /databricks/driver/conf directory apply in reverse alphabetical order. 00-custom-spark.conf ファイルの名前を変更する場合は、spark-branch.conf ファイルよりも前に適用されていることを確認してください。If you want to change the name of the 00-custom-spark.conf file, make sure that it continues to apply before the spark-branch.conf file.

    %scala
    
    dbutils.fs.put(
        "/databricks/scripts/external-metastore.sh",
        """#!/bin/sh
          |# Loads environment variables to determine the correct JDBC driver to use.
          |source /etc/environment
          |# Quoting the label (i.e. EOF) with single quotes to disable variable interpolation.
          |cat << 'EOF' > /databricks/driver/conf/00-custom-spark.conf
          |[driver] {
          |    # Hive specific configuration options.
          |    # spark.hadoop prefix is added to make sure these Hive specific options will propagate to the metastore client.
          |    # JDBC connect string for a JDBC metastore
          |    "spark.hadoop.javax.jdo.option.ConnectionURL" = "<mssql-connection-string>"
          |
          |    # Username to use against metastore database
          |    "spark.hadoop.javax.jdo.option.ConnectionUserName" = "<mssql-username>"
          |
          |    # Password to use against metastore database
          |    "spark.hadoop.javax.jdo.option.ConnectionPassword" = "<mssql-password>"
          |
          |    # Driver class name for a JDBC metastore
          |    "spark.hadoop.javax.jdo.option.ConnectionDriverName" = "com.microsoft.sqlserver.jdbc.SQLServerDriver"
          |
          |    # Spark specific configuration options
          |    "spark.sql.hive.metastore.version" = "<hive-version>"
          |    # Skip this one if <hive-version> is 0.13.x.
          |    "spark.sql.hive.metastore.jars" = "<hive-jar-source>"
          |}
          |EOF
          |""".stripMargin,
        overwrite = true
    )
    
  3. Init スクリプトを使用してクラスターを構成します。Configure your cluster with the init script.

  4. クラスターを再起動します。Restart the cluster.

トラブルシューティングTroubleshooting

クラスターが起動しない (init スクリプト設定が正しくないため)Clusters do not start (due to incorrect init script settings)

外部 metastore を設定するための init スクリプトによってクラスターの作成が失敗する場合は、ログを記録するように init スクリプトを構成し、ログを使用して init スクリプトをデバッグします。If an init script for setting up the external metastore causes cluster creation failure, configure the init script to log, and debug the init script using the logs.

SQL ステートメントにエラーがあります: InvocationTargetExceptionError in SQL statement: InvocationTargetException

  • 例外スタックトレース全体のエラーメッセージパターン:Error message pattern in the full exception stack trace:

    Caused by: javax.jdo.JDOFatalDataStoreException: Unable to open a test connection to the given database. JDBC url = [...]
    

    外部の metastore JDBC 接続情報が正しく構成されていません。External metastore JDBC connection information is misconfigured. 構成されたホスト名、ポート、ユーザー名、パスワード、および JDBC ドライバーのクラス名を確認します。Verify the configured hostname, port, username, password, and JDBC driver class name. また、metastore データベースにアクセスするための適切な権限がユーザー名に与えられていることを確認します。Also, make sure that the username has the right privilege to access the metastore database.

  • 例外スタックトレース全体のエラーメッセージパターン:Error message pattern in the full exception stack trace:

    Required table missing : "`DBS`" in Catalog "" Schema "". DataNucleus requires this table to perform its persistence operations. [...]
    

    外部 metastore データベースが正しく初期化されていません。External metastore database not properly initialized. Metastore データベースが作成されていることを確認し、JDBC 接続文字列に正しいデータベース名を入力します。Verify that you created the metastore database and put the correct database name in the JDBC connection string. 次に、次の2つの Spark 構成オプションを使用して、新しいクラスターを開始します。Then, start a new cluster with the following two Spark configuration options:

    datanucleus.autoCreateSchema true
    datanucleus.fixedDatastore false
    

    このようにして、Hive クライアントライブラリは、metastore データベース内のテーブルにアクセスしようとしても、存在しないことを検出すると、自動的にテーブルを作成し、初期化しようとします。In this way, the Hive client library will try to create and initialize tables in the metastore database automatically when it tries to access them but finds them absent.

SQL ステートメントにエラーがあります: AnalysisException: metastore をインスタンス化できません。 HiveMetastoreClientError in SQL statement: AnalysisException: Unable to instantiate org.apache.hadoop.hive.metastore.HiveMetastoreClient

完全な例外 stacktrace のエラーメッセージ:Error message in the full exception stacktrace:

The specified datastore driver (driver name) was not found in the CLASSPATH

不適切な JDBC driver を使用するようにクラスターが構成されています。The cluster is configured to use an incorrect JDBC driver.

Datanucleus を true に設定すると、予期したとおりに動作しませんSetting datanucleus.autoCreateSchema to true doesn’t work as expected

既定では、Databricks は datanucleus.fixedDatastoretrueに設定します。これにより、metastore データベースに対する誤った構造上の変更を防ぐことができます。By default, Databricks also sets datanucleus.fixedDatastore to true, which prevents any accidental structural changes to the metastore databases. そのため、datanucleus.autoCreateSchematrueに設定した場合でも、Hive クライアントライブラリで metastore テーブルを作成することはできません。Therefore, the Hive client library cannot create metastore tables even if you set datanucleus.autoCreateSchema to true. この戦略は、metastore データベースが誤ってアップグレードされるのを防ぐため、運用環境では一般に安全です。This strategy is, in general, safer for production environments since it prevents the metastore database to be accidentally upgraded.

Metastore データベースを初期化するために datanucleus.autoCreateSchema を使用する場合は、datanucleus.fixedDatastorefalseに設定してください。If you do want to use datanucleus.autoCreateSchema to help initialize the metastore database, make sure you set datanucleus.fixedDatastore to false. また、metastore データベースを初期化した後で両方のフラグを反転して、運用環境の保護を強化することもできます。Also, you may want to flip both flags after initializing the metastore database to provide better protection to your production environment.