メインコンテンツまでスキップ

DuckDB データ ソース

はじめに​

DuckDB は、高速なローカル分析向けに設計されたインプロセスの分析データベースです。Reveal は DuckDB データベース ファイルと MotherDuck データベースの両方をサポートしているため、同じデータ ソース タイプから埋め込みデータ セット、ローカル ファイル、クラウドでホストされる DuckDB ワークロードを視覚化および分析できます。

サーバー構成​

インストール​

手順 1 - Reveal DuckDB コネクタ パッケージをインストールします。

ASP.NET アプリケーションの場合、DuckDB サポートを有効にするには、別の NuGet パッケージをインストールする必要があります。

dotnet add package Reveal.Sdk.Data.DuckDB

手順 2 - アプリケーションに DuckDB データ ソースを登録します。

builder.Services.AddControllers().AddReveal( builder =>
{
    builder.DataSources.RegisterDuckDB();
});

接続構成​

// Create a data source provider
public class DataSourceProvider : IRVDataSourceProvider
{
    public async Task<RVDataSourceItem> ChangeDataSourceItemAsync(IRVUserContext userContext, string dashboardId, RVDataSourceItem dataSourceItem)
    {
        // Required: Update the underlying data source
        await ChangeDataSourceAsync(userContext, dataSourceItem.DataSource);

        if (dataSourceItem is RVDuckDBDataSourceItem duckDBItem)
        {
            // Configure specific item properties if needed
            if (duckDBItem.Id == "duckdb_orders")
            {
                duckDBItem.Table = "orders";
                duckDBItem.Schema = "main";

                // Optional: use a custom query instead of a table
                // duckDBItem.CustomQuery = "SELECT * FROM orders WHERE ship_country = 'USA'";

                // Optional: call a DuckDB table macro
                // duckDBItem.Procedure = "top_customers";
                // duckDBItem.ProcedureParameters = new Dictionary<string, object>
                // {
                //     ["min_total"] = 1000
                // };
            }
        }

        return dataSourceItem;
    }

    public Task<RVDashboardDataSource> ChangeDataSourceAsync(IRVUserContext userContext, RVDashboardDataSource dataSource)
    {
        if (dataSource is RVDuckDBDataSource duckDBDS)
        {
            // Configure connection properties
            duckDBDS.Database = "data\\northwind.duckdb";
            duckDBDS.Schema = "main";

            // For MotherDuck use:
            // duckDBDS.Database = "md:your_database_name";
        }

        return Task.FromResult(dataSource);
    }
}

Database は、絶対パスと相対パスの両方の DuckDB ファイル パスを受け入れます。ASP.NET の場合、相対パスは AppContext.BaseDirectory を基準に解決されます。MotherDuck の場合は、値を md:databaseName に設定します。

Schema は RVDuckDBDataSource と RVDuckDBDataSourceItem の両方でオプションです。設定しない場合、Reveal は既定の DuckDB スキーマである main を使用します。

DuckDB は、サーバー側でカスタム クエリと DuckDB テーブル マクロをサポートします。詳細については、カスタム クエリ を参照してください。

重要

ChangeDataSourceAsync メソッドでデータ ソースに加えた変更は、ChangeDataSourceItemAsync メソッドには引き継がれません。両方のメソッドでデータ ソースのプロパティを更新する必要があります。上記の例に示すように、ChangeDataSourceItemAsync メソッド内で、データ ソース項目の基になるデータ ソースをパラメーターとして渡して ChangeDataSourceAsync メソッドを呼び出すことをお勧めします。

認証​

ローカル DuckDB データベース ファイルでは認証は必要ありません。MotherDuck に接続する場合は、認証プロバイダーを使用してサーバー側で個人用アクセス トークンを提供します。

public class AuthenticationProvider: IRVAuthenticationProvider
{
    public Task<IRVDataSourceCredential> ResolveCredentialsAsync(IRVUserContext userContext, RVDashboardDataSource dataSource)
    {
        IRVDataSourceCredential userCredential = null;
        if (dataSource is RVDuckDBDataSource duckDBDS && duckDBDS.Database?.StartsWith("md:") == true)
        {
            userCredential = new RVPersonalAccessTokenDataSourceCredential("your_motherduck_access_token");
        }
        return Task.FromResult<IRVDataSourceCredential>(userCredential);
    }
}

クライアント側の実装​

クライアント側では、データ ソースの id、title、subtitle などの基本プロパティだけを指定する必要があります。実際の DuckDB ファイル パス、MotherDuck データベース名、スキーマ、クエリ構成はサーバー上で行われます。

データ ソースの作成​

手順 1 - RevealView.onDataSourcesRequested イベントのイベント ハンドラーを追加します。

const revealView = new RevealView("#revealView");
revealView.onDataSourcesRequested = (callback) => {
    // Add data source here
    callback(new RevealDataSources([], [], false));
};

手順 2 - RevealView.onDataSourcesRequested イベント ハンドラーで、RVDuckDBDataSource オブジェクトの新しいインスタンスを作成します。title と subtitle プロパティを設定します。RVDuckDBDataSource オブジェクトを作成したら、それをデータ ソース コレクションに追加します。

revealView.onDataSourcesRequested = (callback) => {
    const duckDBDS = new RVDuckDBDataSource();
    duckDBDS.id = "duckdb_ds";
    duckDBDS.title = "My DuckDB Datasource";
    duckDBDS.subtitle = "DuckDB";

    callback(new RevealDataSources([duckDBDS], [], false));
};

アプリケーションが実行されたら、新しい可視化を作成すると、新しく作成された DuckDB データ ソースが [データ ソースの選択] ダイアログに表示されます。

データ ソース項目の作成​

データ ソース項目は、ユーザーが視覚化のために選択できる DuckDB データ ソース内の特定のテーブル、ビュー、または DuckDB テーブル マクロを表します。クライアント側では、ID、タイトル、サブタイトルのみを指定する必要があります。

revealView.onDataSourcesRequested = (callback) => {
    // Create the data source
    const duckDBDS = new RVDuckDBDataSource();
    duckDBDS.id = "duckdb_ds";
    duckDBDS.title = "My DuckDB Datasource";
    duckDBDS.subtitle = "DuckDB";

    // Create a data source item
    const duckDBDSI = new RVDuckDBDataSourceItem(duckDBDS);
    duckDBDSI.id = "duckdb_orders";
    duckDBDSI.title = "Orders";
    duckDBDSI.subtitle = "DuckDB";

    callback(new RevealDataSources([duckDBDS], [duckDBDSI], false));
};

アプリケーションが実行されたら、新しい可視化を作成すると、新しく作成された DuckDB データ ソース項目が [データ ソースの選択] ダイアログに表示されます。

その他のリソース​

API リファレンス​