Dotnet SDK

Dotnet SDK for Spice.ai

The Dotnet SDK SpiceAI is the easiest way to query Spice.ai from Dotnet.

It uses Apache Arrow Flight to efficiently stream data to the client and Apache Arrow Records as data frames.

Requirements

The package targets .NET Standard 2.0, .NET 8.0, .NET 9.0, and .NET 10.0. .NET 8.0 or later is recommended.

Installation

Add Spice SDK

dotnet add package SpiceAI

Usage

1. Create a SpiceClient by providing your API key to SpiceClientBuilder. Get your free API key at Spice.ai.

SpiceClient implements IDisposable, so declare it with using.

using Spice;

using var client = new SpiceClientBuilder()
    .WithSpiceCloud("API_KEY")
    .Build();

WithSpiceCloud takes the API key, not a URL, and applies the Spice.ai Cloud endpoints itself. The key must be in appId|key form. To connect to a custom endpoint, use WithFlightAddress instead.

The builder also accepts WithApiKey(string), WithFlightAddress(string), WithHttpAddress(string), WithMaxRetries(int) (default 3), WithUserAgent(string), and WithTls(bool).

1. Execute a query and get back an Apache Arrow Flight Client Record Batch Stream Reader.

var result = await client.SqlAsync("SELECT * FROM tpch.lineitem LIMIT 10;");

1. Iterate through the reader to access the records.

var enumerator = result.GetAsyncEnumerator();
while (await enumerator.MoveNextAsync())
{
    var batch = enumerator.Current;
    // Process batch
}

Parameterized queries

SqlWithParamsAsync(string sql, params object?[] parameters) binds positional $1, $2 placeholders:

var data = await client.SqlWithParamsAsync(
    "SELECT * FROM tpch.lineitem WHERE l_quantity > $1 LIMIT 10;", 10);

var batch = await data!.ReadNextRecordBatchAsync();

Parameters are positional only. Named placeholders such as :product_id are not supported.

Asynchronous queries

QueryAsync(string sql) and QueryWithParamsAsync(string sql, params object?[] parameters) submit a query for asynchronous execution and return an AsyncQuery handle instead of a reader. They require the runtime to be running in distributed (scheduler) mode.

var query = await client.QueryAsync("SELECT * FROM taxi_trips");
var stream = await query.GetResultsAsync(); // waits for completion

The handle also exposes Id, GetStatusAsync(), WaitAsync(), and CancelAsync().

Usage with local Spice runtime

Follow the quickstart guide to install and run spice locally. The builder defaults to the local runtime:

using Spice;

using var client = new SpiceClientBuilder()
    .Build();

var data = await client.SqlAsync("SELECT trip_distance, total_amount FROM taxi_trips ORDER BY trip_distance DESC LIMIT 10;");

Or using a custom flight address:

using var client = new SpiceClientBuilder()
    .WithFlightAddress("http://localhost:50051")
    .Build();

Default endpoints

Target	Arrow Flight	HTTP
Spice.ai Cloud	https://flight.spiceai.io:443	https://data.spiceai.io
Local runtime	http://localhost:50051	http://localhost:8090

The Cloud endpoints can be set with SPICE_FLIGHT_URL and SPICE_HTTP_URL, and the local endpoints with SPICE_LOCAL_FLIGHT_URL and SPICE_LOCAL_HTTP_URL.

Refreshing a dataset

RefreshDatasetAsync(string datasetName) triggers a refresh of an accelerated dataset.

Contributing

Contribute to or file an issue with the spice-dotnet library at: https://github.com/spiceai/spice-dotnet