データ依存ルーティングを使用して、クエリを適切なデータベースにルーティングする

2025-06-13

データ依存ルーティングは、クエリ内のデータを使用して、要求を適切なデータベースにルーティングできる機能です。データ依存ルーティングは、シャード化されたデータベースを操作するときの基本的なパターンです。要求コンテキストは、特にシャーディングキーがクエリの一部ではない場合に、要求をルーティングするためにも使用できます。データ依存ルーティングを使用したアプリケーションで、特定のクエリまたはトランザクションがそれぞれアクセスするデータベースは、要求ごとに 1 つに制限されています。 Azure SQL Database エラスティックツールの場合、このルーティングは ShardMapManager (Java、 .NET) クラスを使用して実現されます。

アプリケーションは、シャード化された環境の各種データスライスに関連付けられた、さまざまな接続文字列または DB の場所を追跡する必要はありません。代わりに、シャードマップマネージャーを使用してデータベースをスケールアウトすると、シャードマップ内のデータと、アプリケーションの要求のターゲットであるシャーディングキーの値に基づいて、必要に応じて適切なデータベースへの接続が開かれます。通常、このキーは、データベース要求の基本的なパラメーターである、customer_id、tenant_id、date_key、または他の特定の識別子です。

詳細については、「データ依存型ルーティングを使用した SQL Server のスケールアウト」を参照してください。

クライアントライブラリのダウンロード

ダウンロードの対象:

Java バージョンのライブラリは、Maven Central Repository をご覧ください。
.NET バージョンのライブラリは、NuGet をご覧ください。

データ依存ルーティングアプリケーションで ShardMapManager を使用する

アプリケーションでは、ファクトリ呼び出しShardMapManager (GetSQLShardMapManager、.NET) を使用して、初期化中にをインスタンス化する必要があります。この例では、 ShardMapManager と、それに含まれる特定の ShardMap の両方が初期化されます。また、GetSqlShardMapManager メソッドと GetRangeShardMap (Java、.NET) メソッドを使用しています。

ShardMapManager smm = ShardMapManagerFactory.getSqlShardMapManager(connectionString, ShardMapManagerLoadPolicy.Lazy);
RangeShardMap<int> rangeShardMap = smm.getRangeShardMap(Configuration.getRangeShardMapName(), ShardKeyType.Int32);

ShardMapManager smm = ShardMapManagerFactory.GetSqlShardMapManager(smmConnectionString, ShardMapManagerLoadPolicy.Lazy);
RangeShardMap<int> customerShardMap = smm.GetRangeShardMap<int>("customerMap");

シャードマップの取得には最小限のアクセス許可を持つ資格情報を使用する

アプリケーションでシャードマップ自体を操作しない場合は、ファクトリメソッドで使用される資格情報には、グローバルシャードマップ データベースに対する読み取り専用アクセス許可を付与します。これらの資格情報は、通常、シャードマップマネージャーへの接続で使用される資格情報とは異なります。「 Elastic Database クライアントライブラリへのアクセスに使用する資格情報」も参照してください。

OpenConnectionForKey メソッドを呼び出す

ShardMap.OpenConnectionForKey メソッド (Java、.NET) は、key パラメーターの値に基づいて、適切なデータベースにコマンドを発行できる接続を返します。シャード情報は ShardMapManagerによってアプリケーションにキャッシュされるため、これらの要求には通常、 グローバルシャードマップ データベースに対するデータベース参照は含まれません。

// Syntax:
public Connection openConnectionForKey(Object key, String connectionString, ConnectionOptions options)

// Syntax:
public SqlConnection OpenConnectionForKey<TKey>(TKey key, string connectionString, ConnectionOptions options)

key パラメーターは、要求に適したデータベースを決定するために、シャードマップの参照キーとして使用されます。
connectionStringは、目的の接続のユーザー資格情報のみを渡すために使用されます。メソッドはを使用してデータベースとサーバーを決定するため、この ShardMap にはデータベース名またはサーバー名は含まれません。
connectionOptions (Java、.NET) は、シャードマップが変更される可能性があり、行が分割またはマージ操作の結果として他のデータベースに移動する可能性がある場合は、ConnectionOptions.Validateに設定する必要があります。この検証では、接続要求がアプリケーションに配信される前に、ターゲットデータベースにあるローカルのシャードマップ (グローバルシャードマップではない) に対する簡単なクエリが実行されます。

ローカルのシャードマップの検証が失敗した (キャッシュが正しくないことが示された) 場合は、シャードマップマネージャーがグローバルシャードマップに対してクエリを実行し、ルックアップの正しい値を新しく取得します。その後、キャッシュを更新してから適切なデータベース接続を取得して戻します。

アプリケーションがオンラインのときにシャードマッピングの変更が予期されない場合にのみ、 ConnectionOptions.None を使用します。その場合、キャッシュされた値は常に正しいと見なすことができ、ターゲットデータベースに対する今後のラウンドトリップ検証呼び出しを安全にスキップすることができます。これによりデータベーストラフィックを軽減できます。 connectionOptions を構成ファイルの値で設定し、一定期間内にシャーディングの変更が想定されるかどうかを示すことができます。

この例では、CustomerID という名前のShardMap オブジェクトを使用して、整数キー customerShardMapの値を使用します。

int customerId = 12345;
int productId = 4321;
// Looks up the key in the shard map and opens a connection to the shard
try (Connection conn = shardMap.openConnectionForKey(customerId, Configuration.getCredentialsConnectionString())) {
    // Create a simple command that will insert or update the customer information
    PreparedStatement ps = conn.prepareStatement("UPDATE Sales.Customer SET PersonID = ? WHERE CustomerID = ?");

    ps.setInt(1, productId);
    ps.setInt(2, customerId);
    ps.executeUpdate();
} catch (SQLException e) {
    e.printStackTrace();
}

int customerId = 12345;
int newPersonId = 4321;

// Connect to the shard for that customer ID. No need to call a SqlConnection
// constructor followed by the Open method.
using (SqlConnection conn = customerShardMap.OpenConnectionForKey(customerId, Configuration.GetCredentialsConnectionString(), ConnectionOptions.Validate))
{
    // Execute a simple command.
    SqlCommand cmd = conn.CreateCommand();
    cmd.CommandText = @"UPDATE Sales.Customer
                        SET PersonID = @newPersonID WHERE CustomerID = @customerID";

    cmd.Parameters.AddWithValue("@customerID", customerId);cmd.Parameters.AddWithValue("@newPersonID", newPersonId);
    cmd.ExecuteNonQuery();
}

OpenConnectionForKey メソッドは、正しいデータベースへの新しい既に開いている接続を返します。この方法で接続した場合も引き続き接続プーリングの利点を最大限に活用できます。

アプリケーションで非同期プログラミングを使用する場合は、 OpenConnectionForKeyAsync メソッド (Java、 .NET) も使用できます。

一時的な障害処理との統合

クラウドでのデータアクセスアプリケーション開発のベストプラクティスは、一時的な障害をアプリケーションで確実に捕捉し、エラーがスローされる前に操作を確実にリトライすることです。クラウドアプリケーションにおける一時的な障害処理の詳細については、一時的な障害処理 (Java、.NET) に関するページをご覧ください。

一時的な障害処理は、データ依存ルーティングのパターンと自然に共存できます。そのための主な要件は、データ依存ルーティング接続を取得した using ブロックを含めたデータアクセス要求全体をリトライすることです。前の例は次のように書き換えることができます。

例 - 一時的な障害処理機能を伴うデータ依存ルーティング

int customerId = 12345;
int productId = 4321;
try {
    SqlDatabaseUtils.getSqlRetryPolicy().executeAction(() -> {
        // Looks up the key in the shard map and opens a connection to the shard
        try (Connection conn = shardMap.openConnectionForKey(customerId, Configuration.getCredentialsConnectionString())) {
            // Create a simple command that will insert or update the customer information
            PreparedStatement ps = conn.prepareStatement("UPDATE Sales.Customer SET PersonID = ? WHERE CustomerID = ?");

            ps.setInt(1, productId);
            ps.setInt(2, customerId);
            ps.executeUpdate();
        } catch (SQLException e) {
            e.printStackTrace();
        }
    });
} catch (Exception e) {
    throw new StoreException(e.getMessage(), e);
}

int customerId = 12345;
int newPersonId = 4321;

Configuration.SqlRetryPolicy.ExecuteAction(() -> {

    // Connect to the shard for a customer ID.
    using (SqlConnection conn = customerShardMap.OpenConnectionForKey(customerId, Configuration.GetCredentialsConnectionString(), ConnectionOptions.Validate))
    {
        // Execute a simple command
        SqlCommand cmd = conn.CreateCommand();

        cmd.CommandText = @"UPDATE Sales.Customer
                            SET PersonID = @newPersonID
                            WHERE CustomerID = @customerID";

        cmd.Parameters.AddWithValue("@customerID", customerId);
        cmd.Parameters.AddWithValue("@newPersonID", newPersonId);
        cmd.ExecuteNonQuery();

        Console.WriteLine("Update completed");
    }
});

一時的な障害処理の実装に必要なパッケージは、エラスティックデータベースのサンプルアプリケーションのビルド時に自動的にダウンロードされます。

トランザクションの整合性

トランザクションのプロパティは、シャードにとってローカルなすべての操作で保証されています。たとえば、データ依存ルーティングを通じて送信されるトランザクションは、接続するターゲットシャードの範囲内で実行されます。現時点では、複数の接続を 1 つのトランザクションに登録するために提供された機能はありません。したがって、複数のシャードにまたがる操作にもトランザクション上の保証はありません。

次のステップ

RecoveryManager クラスを使用したシャードマップの問題の修正

まだ弾力性データベースツールを使用していない場合は、ファーストステップガイドを参照してください。ご質問がある場合は、SQL Database に関する Microsoft Q&A 質問ページを参照してください。機能に関するご要望は、SQL Database に関するフィードバックフォーラムで新しいアイデアを追加したり、既存のアイデアに投票したりしてください。

次の方法で共有

データ依存ルーティングを使用して、クエリを適切なデータベースにルーティングする

クライアント ライブラリのダウンロード

データ依存ルーティング アプリケーションで ShardMapManager を使用する

シャード マップの取得には最小限のアクセス許可を持つ資格情報を使用する