feat: add SearchAsync for vector, keyword, and hybrid search

Wraps POST /v1/search, which was previously unreachable from .NET without
hand-rolling the HTTP call. spice.js is the only other SDK that exposes it.

Only Text is required; Datasets, Limit, Where, AdditionalColumns and Keywords
are optional. Supplying Keywords pre-filters the embedding column with a lexical
search before the vector search, making the search hybrid.

SearchMatch maps the runtime's wire format, including the `_score` field name
and the objects the runtime omits when empty; those default to empty
dictionaries so callers can read them without a null check.

System.Text.Json was already resolved transitively via Apache.Arrow.Adbc; it is
now referenced explicitly at the version that dependency already selects, since
netstandard2.0 has no in-box System.Text.Json.

Author: lukekim

README.md

@@ -215,6 +215,50 @@ using var client = new SpiceClientBuilder()
 await client.RefreshDatasetAsync("my_dataset");
 ```
 
+#### Search
+
+`SearchAsync` runs vector similarity, keyword, and hybrid search against datasets that have
+an embedding column and a loaded embedding model.
+
+```csharp
+using Spice;
+using Spice.Search;
+
+using var client = new SpiceClientBuilder().Build();
+
+var response = await client.SearchAsync(new SearchRequest("tickets to Tokyo")
+{
+    Datasets = new[] { "app_messages" },
+    Limit = 3,
+});
+
+Console.WriteLine($"{response.Results.Count} matches in {response.DurationMs}ms");
+foreach (var match in response.Results)
+{
+    Console.WriteLine($"{match.Dataset} {match.Score}");
+}
+```
+
+Only `Text` is required. `Datasets` restricts the search — leave it unset to search every
+dataset with an embedding column. `Limit` caps matches per dataset, `Where` applies an SQL
+predicate before the search, and `AdditionalColumns` names extra columns to return. Setting
+`Keywords` pre-filters the embedding column with a lexical search before the vector search
+runs, making the search hybrid:
+
+```csharp
+var response = await client.SearchAsync(new SearchRequest("tickets to Tokyo")
+{
+    Where = "city = 'Tokyo'",
+    AdditionalColumns = new[] { "timestamp" },
+    Keywords = new[] { "plane", "tickets" },
+});
+```
+
+Each `SearchMatch` carries the `Dataset` it was found in, its similarity `Score`, the
+matched column values in `Matches`, the row's `PrimaryKey`, the columns requested via
+`AdditionalColumns` in `Data`, and any `Metadata`. The runtime omits the last three when
+empty; they default to empty dictionaries, so they can be read without a null check.
+
 ### Memory Management
 
 The `SpiceClient` implements `IDisposable` and should be properly disposed to release network resources (gRPC channels, HTTP clients). Use the `using` statement or `using` declaration for automatic disposal:

Spice/Spice.csproj

@@ -55,4 +55,14 @@
         </AssemblyAttribute>
     </ItemGroup>
 
+    <!--
+        System.Text.Json arrives transitively via Apache.Arrow.Adbc, but search
+        serialization depends on it directly, so pin it explicitly. The version matches
+        what Apache.Arrow.Adbc already resolves to; netstandard2.0 needs the package
+        because, unlike net8.0+, it has no in-box System.Text.Json.
+    -->
+    <ItemGroup>
+        <PackageReference Include="System.Text.Json" Version="9.0.9" />
+    </ItemGroup>
+
 </Project>

Spice/src/Http/ISpiceHttpClient.cs

@@ -20,6 +20,8 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 */
 
+using Spice.Search;
+
 namespace Spice.Http;
 
 /// <summary>
@@ -44,4 +46,15 @@ public interface ISpiceHttpClient : IDisposable
     /// <exception cref="System.ArgumentException">Thrown when datasetName is null or empty</exception>
     /// <exception cref="System.Net.Http.HttpRequestException">Thrown when the HTTP request fails</exception>
     Task RefreshDatasetAsync(string datasetName);
+
+    /// <summary>
+    /// Runs a vector, keyword, or hybrid search against datasets with an embedding column.
+    /// </summary>
+    /// <param name="request">The search to run</param>
+    /// <param name="cancellationToken">Token to cancel the request</param>
+    /// <returns>The matches, ordered by descending score</returns>
+    /// <exception cref="System.ArgumentNullException">Thrown when request is null</exception>
+    /// <exception cref="System.ArgumentException">Thrown when the search text is null or empty</exception>
+    /// <exception cref="System.Net.Http.HttpRequestException">Thrown when the HTTP request fails</exception>
+    Task<SearchResponse> SearchAsync(SearchRequest request, CancellationToken cancellationToken = default);
 }

Spice/src/Http/SpiceHttpClient.cs

@@ -22,7 +22,9 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 
 using System.Net.Http.Headers;
 using System.Text;
+using System.Text.Json;
 using Spice.Auth;
+using Spice.Search;
 
 namespace Spice.Http;
 
@@ -136,6 +138,89 @@ public async Task RefreshDatasetAsync(string datasetName)
         response.EnsureSuccessStatusCode();
     }
 
+    /// <summary>
+    /// Options used to serialize search requests and deserialize search responses.
+    /// </summary>
+    private static readonly JsonSerializerOptions SearchJsonOptions = new()
+    {
+        PropertyNamingPolicy = null,
+    };
+
+    /// <summary>
+    /// Runs a vector, keyword, or hybrid search against datasets with an embedding column.
+    /// </summary>
+    /// <param name="request">The search to run</param>
+    /// <param name="cancellationToken">Token to cancel the request</param>
+    /// <returns>The matches, ordered by descending score</returns>
+    /// <exception cref="System.ArgumentNullException">Thrown when request is null</exception>
+    /// <exception cref="System.ArgumentException">Thrown when the search text is null or empty</exception>
+    /// <exception cref="System.Net.Http.HttpRequestException">Thrown when the HTTP request fails</exception>
+    public async Task<SearchResponse> SearchAsync(SearchRequest request, CancellationToken cancellationToken = default)
+    {
+#if NET8_0_OR_GREATER
+        ObjectDisposedException.ThrowIf(_disposed, this);
+        ArgumentNullException.ThrowIfNull(request);
+        ArgumentException.ThrowIfNullOrWhiteSpace(request.Text, nameof(request));
+#else
+        if (_disposed) throw new ObjectDisposedException(GetType().FullName);
+        ThrowHelper.ThrowIfNull(request, nameof(request));
+        ThrowHelper.ThrowIfNullOrWhiteSpace(request.Text, nameof(request));
+#endif
+
+        var url = $"{_httpAddress}/v1/search";
+        var json = JsonSerializer.Serialize(request, SearchJsonOptions);
+
+        using var content = new StringContent(json, Encoding.UTF8, "application/json");
+        using var response = await _httpClient.PostAsync(url, content, cancellationToken).ConfigureAwait(false);
+
+#if NET8_0_OR_GREATER
+        var body = await response.Content.ReadAsStringAsync(cancellationToken).ConfigureAwait(false);
+#else
+        // netstandard2.0 has no CancellationToken overload for ReadAsStringAsync.
+        var body = await response.Content.ReadAsStringAsync().ConfigureAwait(false);
+#endif
+
+        if (!response.IsSuccessStatusCode)
+        {
+            // Surface the runtime's own message — it names what the caller needs to fix.
+            throw new HttpRequestException(
+                $"Search failed with status {(int)response.StatusCode}: {ExtractErrorMessage(body)}");
+        }
+
+        return JsonSerializer.Deserialize<SearchResponse>(body, SearchJsonOptions) ?? new SearchResponse();
+    }
+
+    /// <summary>
+    /// Pulls the runtime's error message out of a failed response body, falling back to
+    /// the raw body when it is not the expected shape.
+    /// </summary>
+    /// <param name="body">The response body</param>
+    /// <returns>The message to report</returns>
+    private static string ExtractErrorMessage(string body)
+    {
+        if (string.IsNullOrWhiteSpace(body))
+        {
+            return "(no response body)";
+        }
+
+        try
+        {
+            using var document = JsonDocument.Parse(body);
+            if (document.RootElement.ValueKind == JsonValueKind.Object
+                && document.RootElement.TryGetProperty("error", out var error)
+                && error.ValueKind == JsonValueKind.String)
+            {
+                return error.GetString() ?? body;
+            }
+        }
+        catch (JsonException)
+        {
+            // Not JSON — fall through and report the body verbatim.
+        }
+
+        return body;
+    }
+
     /// <summary>
     /// Releases all resources used by the <see cref="SpiceHttpClient"/>.
     /// </summary>

Spice/src/Search/SearchTypes.cs

@@ -0,0 +1,161 @@
+/*
+Copyright 2024 The Spice.ai OSS Authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+*/
+
+using System.Text.Json;
+using System.Text.Json.Serialization;
+
+namespace Spice.Search;
+
+/// <summary>
+/// A search over datasets that have an embedding column and a loaded embedding model.
+/// </summary>
+/// <remarks>
+/// Only <see cref="Text"/> is required. Leave <see cref="Datasets"/> unset to search every
+/// dataset with an embedding column, and set <see cref="Keywords"/> to pre-filter the
+/// embedding column with a lexical search first, making the search hybrid.
+/// </remarks>
+public class SearchRequest
+{
+    /// <summary>
+    /// Creates a search request.
+    /// </summary>
+    /// <param name="text">The query to find similar documents for</param>
+    public SearchRequest(string text)
+    {
+        Text = text;
+    }
+
+    /// <summary>
+    /// The query to find similar documents for.
+    /// </summary>
+    [JsonPropertyName("text")]
+    public string Text { get; set; }
+
+    /// <summary>
+    /// Restricts the search to these datasets. Null searches every dataset with an
+    /// embedding column.
+    /// </summary>
+    [JsonPropertyName("datasets")]
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public IReadOnlyList<string>? Datasets { get; set; }
+
+    /// <summary>
+    /// Maximum matches to return per dataset. Null uses the runtime's default.
+    /// </summary>
+    [JsonPropertyName("limit")]
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public int? Limit { get; set; }
+
+    /// <summary>
+    /// An SQL predicate applied before the search, without the WHERE keyword —
+    /// for example <c>city = 'Tokyo'</c>.
+    /// </summary>
+    [JsonPropertyName("where")]
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public string? Where { get; set; }
+
+    /// <summary>
+    /// Extra dataset columns to return. A column that is part of the primary key is
+    /// returned in <see cref="SearchMatch.PrimaryKey"/> rather than <see cref="SearchMatch.Data"/>.
+    /// </summary>
+    [JsonPropertyName("additional_columns")]
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public IReadOnlyList<string>? AdditionalColumns { get; set; }
+
+    /// <summary>
+    /// Pre-filters the embedding column with a lexical search before the vector search
+    /// runs, making the search hybrid.
+    /// </summary>
+    [JsonPropertyName("keywords")]
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public IReadOnlyList<string>? Keywords { get; set; }
+}
+
+/// <summary>
+/// A single document matched by a search.
+/// </summary>
+/// <remarks>
+/// The runtime omits <see cref="Data"/>, <see cref="PrimaryKey"/> and <see cref="Metadata"/>
+/// when they are empty; they default to empty dictionaries so they can be read without a
+/// null check.
+/// </remarks>
+public class SearchMatch
+{
+    /// <summary>
+    /// The dataset the match was found in.
+    /// </summary>
+    [JsonPropertyName("dataset")]
+    public string Dataset { get; set; } = string.Empty;
+
+    /// <summary>
+    /// Similarity of the match to the query text. Higher is closer.
+    /// </summary>
+    /// <remarks>The runtime serializes this as <c>_score</c>.</remarks>
+    [JsonPropertyName("_score")]
+    public double Score { get; set; }
+
+    /// <summary>
+    /// The matched values of each searched column.
+    /// </summary>
+    [JsonPropertyName("matches")]
+    public IReadOnlyDictionary<string, IReadOnlyList<JsonElement>> Matches { get; set; }
+        = new Dictionary<string, IReadOnlyList<JsonElement>>();
+
+    /// <summary>
+    /// Primary key identifying the matched row, if the dataset declares one.
+    /// </summary>
+    [JsonPropertyName("primary_key")]
+    public IReadOnlyDictionary<string, JsonElement> PrimaryKey { get; set; }
+        = new Dictionary<string, JsonElement>();
+
+    /// <summary>
+    /// Columns requested via <see cref="SearchRequest.AdditionalColumns"/>.
+    /// </summary>
+    [JsonPropertyName("data")]
+    public IReadOnlyDictionary<string, JsonElement> Data { get; set; }
+        = new Dictionary<string, JsonElement>();
+
+    /// <summary>
+    /// Any additional metadata the runtime attached to the match.
+    /// </summary>
+    [JsonPropertyName("metadata")]
+    public IReadOnlyDictionary<string, JsonElement> Metadata { get; set; }
+        = new Dictionary<string, JsonElement>();
+}
+
+/// <summary>
+/// The result of a search.
+/// </summary>
+public class SearchResponse
+{
+    /// <summary>
+    /// Matches, ordered by descending score.
+    /// </summary>
+    [JsonPropertyName("results")]
+    public IReadOnlyList<SearchMatch> Results { get; set; } = new List<SearchMatch>();
+
+    /// <summary>
+    /// How long the runtime took to run the search.
+    /// </summary>
+    [JsonPropertyName("duration_ms")]
+    public long DurationMs { get; set; }
+}

Spice/src/SpiceClient.cs

@@ -26,6 +26,7 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 using Spice.Config;
 using Spice.Flight;
 using Spice.Http;
+using Spice.Search;
 
 namespace Spice;
 
@@ -189,6 +190,33 @@ public Task RefreshDatasetAsync(string datasetName)
         return HttpClient.RefreshDatasetAsync(datasetName);
     }
 
+    /// <summary>
+    /// Runs a vector, keyword, or hybrid search.
+    /// </summary>
+    /// <remarks>
+    /// Searches datasets that have an embedding column and a loaded embedding model,
+    /// returning the documents most similar to the request text. Setting
+    /// <see cref="SearchRequest.Keywords"/> pre-filters the embedding column with a
+    /// lexical search first, making the search hybrid.
+    /// </remarks>
+    /// <param name="request">The search to run</param>
+    /// <param name="cancellationToken">Token to cancel the request</param>
+    /// <returns>The matches, ordered by descending score</returns>
+    /// <exception cref="System.ArgumentNullException">Thrown when request is null</exception>
+    /// <exception cref="System.ArgumentException">Thrown when the search text is null or empty</exception>
+    /// <exception cref="System.Net.Http.HttpRequestException">Thrown when the HTTP request fails</exception>
+    public Task<SearchResponse> SearchAsync(SearchRequest request, CancellationToken cancellationToken = default)
+    {
+#if NET8_0_OR_GREATER
+        ObjectDisposedException.ThrowIf(_disposed, this);
+#else
+        if (_disposed) throw new ObjectDisposedException(GetType().FullName);
+#endif
+        if (HttpClient == null) throw new InvalidOperationException("HttpClient not initialized");
+
+        return HttpClient.SearchAsync(request, cancellationToken);
+    }
+
     private bool _disposed;
 
     /// <summary>