Vespa.NET.Testcontainers
3.1.1
dotnet add package Vespa.NET.Testcontainers --version 3.1.1
NuGet\Install-Package Vespa.NET.Testcontainers -Version 3.1.1
<PackageReference Include="Vespa.NET.Testcontainers" Version="3.1.1" />
<PackageVersion Include="Vespa.NET.Testcontainers" Version="3.1.1" />
<PackageReference Include="Vespa.NET.Testcontainers" />
paket add Vespa.NET.Testcontainers --version 3.1.1
#r "nuget: Vespa.NET.Testcontainers, 3.1.1"
#:package Vespa.NET.Testcontainers@3.1.1
#addin nuget:?package=Vespa.NET.Testcontainers&version=3.1.1
#tool nuget:?package=Vespa.NET.Testcontainers&version=3.1.1
<div align="center">
Vespa.NET
Typed document, search and feed APIs for Vespa.ai on .NET 8 and .NET 10.
</div>
Use C# models for document serialization and schema generation, compose queries with the YQL builder, and feed mixed document operations with bounded concurrency.
Quick Start · Documents · Search · Grouping · Feed · Configuration · Guides
Features
| Schema | Code-first .sd generation from attributes, multi-type deploy, custom services.xml |
| Documents | CRUD, conditional writes, field-level ops, resumable visit pages, group/number addressing (read+write), selection-based update/delete/copy with continuation auto-loop + crash-safe manual paging |
| Search | Full-text, nearest-neighbor, hybrid, streaming-mode queries and lazy result pagination |
| YQL | Fluent type-safe builder with boolean composition, grouping, ranking DSL |
| Feed | Mixed puts/updates/deletes across schemas and namespaces, per-document ordering, bounded backpressure, progress callbacks |
| Models | Attribute-based field names, tensor formats and [VespaExtraFields] for fields outside the C# model |
| Cloud | mTLS (PEM, PFX, in-memory cert), Bearer token auth |
| Ops | OpenTelemetry traces + metrics, ASP.NET Core health checks, Testcontainers |
| Performance | HTTP/2 multiplexing, connection pooling, GZip/Deflate, ResponseHeadersRead |
| Resilience | HTTP retry + circuit breaker through DI, feed-level retry and source-generated logging |
Quick Start
The example targets a local Vespa 8 instance with the document/query endpoint on
port 8080 and the config server on port 19071. It deploys a generated
application package; use a separate development instance for this example.
docker run --detach --name vespa --publish 8080:8080 --publish 19071:19071 vespaengine/vespa:8
Wait for the config server at http://localhost:19071/ApplicationStatus to respond
before deploying. If your application is already deployed, configure Endpoint
and skip the deployment call.
1. Install
dotnet new console --name VespaQuickstart --framework net10.0
cd VespaQuickstart
dotnet add package Vespa.NET
Use --framework net8.0 to target .NET 8.
| Package | Use |
|---|---|
Vespa.NET |
Client, DI integration, YQL and schema builders; includes Vespa.NET.Models transitively |
Vespa.NET.Models |
DTOs, attributes and tensor types without client dependencies |
Vespa.NET.Testcontainers |
Optional Docker helper for integration tests |
2. Define a model
Add Product.cs:
using Vespa.Models.Attributes;
using Vespa.Models.Schema;
using Vespa.Models.Tensors;
[VespaDocument("product", Namespace = "myapp")]
[VespaRankProfile("semantic", Inherits = "default", FirstPhase = "closeness(field, embedding)")]
[VespaRankProfile("hybrid", Inherits = "default",
FirstPhase = "closeness(field, embedding) + nativeRank(product_name)")]
public record Product
{
[VespaId]
public string Id { get; init; } = "";
[VespaField(Name = "product_name", IndexingMode = IndexingMode.IndexAttributeSummary)]
public string Name { get; init; } = "";
[VespaField(Name = "price", IndexingMode = IndexingMode.AttributeSummary)]
public decimal Price { get; init; }
[VespaField(Name = "category", IndexingMode = IndexingMode.IndexAttributeSummary)]
public string Category { get; init; } = "";
[VespaTensor("tensor<float>(x[4])", EnableIndex = true, DistanceMetric = DistanceMetric.Euclidean)]
public VespaTensor Embedding { get; init; } = null!;
}
3. Deploy, index, search
Add the following to Program.cs. The four-dimensional vectors keep the example
self-contained; in an application, use your embedding model's vectors and dimension.
using Vespa;
using Vespa.Documents;
using Vespa.Models;
using Vespa.Models.Tensors;
using Vespa.Search;
var options = new VespaClientOptions
{
Endpoint = "http://localhost:8080",
ConfigServerEndpoint = "http://localhost:19071",
DefaultNamespace = "myapp"
};
using var client = new VespaClient(options);
// Deploy schema from C# attributes
await client.Admin.DeploySchemaAsync<Product>();
// Allow the application container to become ready after activation
using var startup = new CancellationTokenSource(TimeSpan.FromMinutes(2));
while (!await client.IsReadyAsync(startup.Token))
await Task.Delay(TimeSpan.FromMilliseconds(500), startup.Token);
// Index a document
var product = new Product
{
Id = "p-1",
Name = "Laptop",
Price = 999.99m,
Category = "electronics",
Embedding = VespaTensor.FromDenseValues<float>([0.1f, 0.2f, 0.3f, 0.4f])
};
await client.Documents.PutAsync(product.Id, product);
// Retrieve it directly, or search with the generated semantic rank profile
var document = await client.Documents.GetAsync<Product>(product.Id);
Console.WriteLine(document?.Fields?.Name);
var queryEmbedding = VespaTensor.FromDenseValues<float>([0.1f, 0.2f, 0.3f, 0.5f]);
var results = await client.Search.NearestNeighborSearchAsync<Product>(
queryEmbedding, p => p.Embedding, topK: 10, rankProfile: "semantic");
foreach (var hit in results.Root.Children)
Console.WriteLine($"{hit.Fields?.Name}: {hit.Relevance:F3}");
Writes can become visible to search after the write response; a direct document GET and a search do not have the same visibility guarantees.
The options-only constructor configures its HTTP handler and owns its lifetime.
For factory-managed HTTP retry and circuit breaking, use
AddVespaClient. Feed-level retry is also available with
a directly constructed client.
Model-Aware API
The following examples are independent and reuse the model and client above.
Document extensions infer the schema and namespace from [VespaDocument];
search extensions infer the schema. [VespaField(Name)] drives both schema
generation and JSON serialization.
// CRUD — no documentType needed
await client.Documents.PutAsync(product.Id, product);
var doc = await client.Documents.GetAsync<Product>(product.Id);
// Request options with model-inferred schema and namespace
var readOptions = new DocumentRequestOptions { Cluster = "content", Timeout = TimeSpan.FromSeconds(5) };
var routedDoc = await client.Documents.GetAsync<Product>(readOptions, product.Id);
// Field-level update with typed lambda builder
await client.Documents.UpdateFieldsAsync<Product>(product.Id, ops => ops
.Field(p => p.Name, FieldOp.Assign("New Name"))
.Field(p => p.Price, FieldOp.Multiply(0.9)));
// Nearest-neighbor — field name resolved via lambda
var results = await client.Search.NearestNeighborSearchAsync<Product>(
queryEmbedding, p => p.Embedding, topK: 10, rankProfile: "semantic");
// Visit
await foreach (var d in client.Documents.VisitAsync<Product>(selection: "product.price > 100"))
Console.WriteLine(d.Fields?.Name);
// One visit page; persist Continuation after processing to resume later
var page = await client.Documents.VisitPageAsync<Product>(cluster: "content");
foreach (var visited in page.Documents)
Console.WriteLine(visited.Fields?.Name);
if (!page.IsComplete)
page = await client.Documents.VisitPageAsync<Product>(
cluster: "content", continuation: page.Continuation);
// Selection-based bulk ops — typed builder, auto-loops on Vespa's continuation token
var resp = await client.Documents.UpdateBySelectionAsync<Product>(
"product.price > 100",
ops => ops.Field(p => p.Price, FieldOp.Multiply(0.9)),
cluster: "content");
// resp.DocumentCount is the total across all chunks
await client.Documents.DeleteAsync<Product>(product.Id);
Persist a visit continuation after processing that page. An empty page may
still have a continuation; use IsComplete to decide whether visiting has ended.
Pass a bare ID such as "p-1" or a full ID such as "id:myapp:product::p-1".
Full IDs retain their namespace, type and group/number addressing; incompatible
targets throw. Returned documents expose FullId as well as the user-specified Id.
YQL Builder
using Vespa.Query;
var yql = YqlBuilder<Product>
.Select(p => p.Name, p => p.Price)
.Where(w =>
{
w.Field(p => p.Price).GreaterThan(10);
w.Field(p => p.Name).Contains("laptop");
})
.OrderBy(p => p.Price, descending: true)
.Limit(20)
.Build();
Fluent request builder captures YQL + ranking in one chain:
var request = YqlBuilder<Product>
.Select()
.Where(w => w.HybridSearch(p => p.Embedding, "query_embedding", "text", totalTargetHits: 100))
.Limit(20)
.ToSearchRequest()
.WithRankProfile("hybrid")
.WithQueryTensor("query_embedding", queryEmbedding)
.WithUserInput("text", "laptop");
var results = await client.Search.SearchAsync<Product>(request);
HybridSearch retrieves with nearest-neighbor search and uses text matches for
ranking through Vespa's rank() operator. The example's hybrid rank profile is
declared on Product above. embed(...) inputs are also supported when you have
configured an embedder in Vespa.
Additional query parameters can be sent with request.WithParameter(name, value).
For example, request.WithParameter("ranking.matching.anntimebudget", "25ms")
sets an ANN time budget on Vespa 8.684.9 or newer.
SearchStreamAsync paginates ordinary search results lazily and is subject to
Vespa's maxHits/maxOffset limits. Use document visiting to export a corpus.
Vespa's separate streaming search mode requires a streaming-mode content cluster
and request properties such as StreamingGroupName.
Full predicate reference, boolean composition, and validation rules in docs/yql-builder.md
Grouping & Aggregation
using Vespa.Query;
var request = new VespaSearchRequest
{
Yql = YqlBuilder<Product>
.Select()
.GroupBy(
GroupingBuilder.All()
.Group("category")
.Max(10)
.OrderByDescending(GroupingAgg.Count())
.Each(e => e.Output(GroupingAgg.Count(), GroupingAgg.Avg("price"))))
.Build(),
Hits = 0
};
var result = (await client.Search.GroupByAsync<Product>(request)).AsTyped();
foreach (var group in result.GroupingResults[0].Groups)
Console.WriteLine($"{group.Value}: {group.GetAggregation<long>("count()")} documents");
Typed grouping, exact aggregation values, buckets, summaries and pagination in docs/grouping.md
Bulk Feed
using Vespa.Feed;
// Mixed operations with per-document ordering
FeedOperation[] operations =
[
FeedOperation.Put("p-1", product),
FeedOperation.Update<Product>("p-1", update => update.Field(p => p.Price, FieldOp.Assign(49.99m))),
FeedOperation.Delete<Product>("p-2")
];
var mixed = await client.Feed.FeedAsync(operations, new FeedOptions { MaxConcurrency = 32 });
Console.WriteLine($"{mixed.SuccessCount}/{mixed.TotalOperations} operations succeeded");
foreach (var error in mixed.Errors)
Console.WriteLine($"{error.OperationIndex}: {error.DocumentId} — {error.Message}");
The mixed feed accepts both IEnumerable<FeedOperation> and
IAsyncEnumerable<FeedOperation>. FeedOptions.BoundedCapacity limits buffered
work; operations for the same document preserve source order, including retries.
Mixed operations, ordering, per-document conditions, BulkPut/Update/Delete, and FeedResult details in docs/feed.md
Fields Outside the C# Model
Use [VespaExtraFields] to preserve Vespa fields without declaring a C# property
for each one. These fields must still exist in your deployed Vespa schema.
using System.Text.Json;
using Vespa.Models.Attributes;
using Vespa.Models.Schema;
public record ProductFields
{
// App-owned fields — strongly typed, used for ranking
[VespaField(IndexingMode = IndexingMode.AttributeSummary)]
public double Popularity { get; init; }
// Tenant-defined fields — captured dynamically
[VespaExtraFields]
public Dictionary<string, JsonElement>? TenantFields { get; init; }
}
- Unmapped JSON fields are captured in the dictionary during deserialization
- Serialized flat alongside declared properties (not nested)
- Values are retained as
JsonElementfor round trips - The schema builder skips the dictionary; declare its fields in the Vespa schema separately
Admin API
// Deploy from C# attributes
await client.Admin.DeploySchemaAsync<Product>();
// Multi-tenant: override tenant per-call
await client.Admin.DeploySchemaAsync<Product>(tenant: "acme");
// Deploy raw ZIP
using var zipStream = File.OpenRead("application.zip");
await client.Admin.DeployAsync(zipStream);
// Application status and readiness
var status = await client.Admin.GetApplicationStatusAsync();
var ready = await client.IsReadyAsync();
var version = await client.GetVersionAsync();
var metrics = await client.GetMetricsAsync();
Note:
ApiKey,DefaultRequestHeaders, compression, timeout, and mTLS settings are applied to both the data-plane client and the admin/config-server client.
Note: Retry and circuit-breaker options are enforced by the DI registrations (
AddVespaClient). A directly constructedVespaClientapplies feed-level retry only; usenew VespaClient(options)(options-only constructor) to get a fully configured handler (mTLS, compression, pooling) without DI.
Tip: Health/state helpers such as
HealthCheckAsync,IsReadyAsync,GetMetricsAsync,GetVersionAsync, andGetHistogramsAsyncare best-effort on ordinary failures, but they still propagateOperationCanceledExceptionwhen the request is cancelled.
Schema attributes,
[VespaExtraFields],ApplicationPackageOptions, andCustomServicesXmlin docs/schema.md
Configuration & Ops
<details> <summary><strong>DI Integration</strong></summary>
In an ASP.NET Core application, register the client before building the app:
using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.DependencyInjection;
using Vespa;
using Vespa.Documents;
using Vespa.Models;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddVespaClient(new VespaClientOptions
{
Endpoint = "http://localhost:8080",
DefaultNamespace = "myapp",
EnableRetry = true
});
// Named client (multi-cluster)
builder.Services.AddVespaClient("analytics", new VespaClientOptions
{
Endpoint = "http://analytics-vespa:8080"
});
// Inject
public class ProductService(IVespaClient vespa)
{
public Task<VespaDocument<Product>?> GetAsync(string id)
=> vespa.Documents.GetAsync<Product>(id);
}
Calling AddVespaClient again replaces the previous Vespa configuration: the last
call supplies the options, configureHttpClient callback and resilience strategy.
This lets an application override a registration supplied by a shared setup method:
builder.Services.AddVespaClient(new VespaClientOptions { Endpoint = "http://default-vespa:8080" });
builder.Services.AddVespaClient(new VespaClientOptions { Endpoint = "https://production-vespa.example.com" });
// IVespaClient uses the production endpoint; only one client registration remains.
The same rule applies to named clients with the same name, and when switching
between AddVespaClient and AddVespaClientWithResilienceStrategy. Other named
clients are unaffected. Vespa handlers and retry policies are registered once,
so repeated calls do not stack them. Additional configuration applied through
the returned IHttpClientBuilder follows the usual .NET composition rules.
Register clients before building the service provider; existing providers retain
their configuration. Consumer-registered unnamed VespaClientOptions singletons
are preserved and do not override the options passed to AddVespaClient.
</details>
<details> <summary><strong>Vespa Cloud (mTLS)</strong></summary>
var options = new VespaClientOptions
{
Endpoint = "https://myapp.vespa-cloud.com",
CertificatePath = "/path/to/cert.pem",
ClientKeyPath = "/path/to/key.pem",
// or: ClientCertificate = myCert,
// or: ApiKey = "bearer-token"
};
</details>
<details> <summary><strong>Observability (OpenTelemetry)</strong></summary>
Install OpenTelemetry.Extensions.Hosting and register the SDK's sources in your
OpenTelemetry setup:
using OpenTelemetry.Metrics;
using OpenTelemetry.Trace;
builder.Services.AddOpenTelemetry()
.WithTracing(b => b.AddSource("Vespa.NET"))
.WithMetrics(m => m.AddMeter("Vespa.NET"));
Spans: vespa.search, vespa.document.*, vespa.feed.pipeline, etc.
Query text (YQL) and document ids are excluded from span tags by default; opt in with VespaClientOptions.RecordQueryTextInTraces = true.
Metrics: vespa.client.requests, vespa.client.request_duration, vespa.client.documents_written, etc.
</details>
<details> <summary><strong>Health Checks</strong></summary>
builder.Services.AddHealthChecks().AddVespa();
</details>
<details> <summary><strong>Testcontainers</strong></summary>
using Vespa.Testcontainers;
await using var vespa = new VespaContainer();
await vespa.StartAsync();
var client = vespa.CreateClient("test");
await client.Admin.DeploySchemaAsync<Product>();
Install Vespa.NET.Testcontainers and have Docker running. The container owns the
client created by CreateClient. To run this repository's integration suite,
set VESPA_INTEGRATION_TESTS=1; this flag is not required by the helper itself.
</details>
Full configuration reference, exceptions, metrics table, and more in docs/configuration.md
Documentation
The VectorData connector is a separate optional package for typed vector-store access and Microsoft Agent Framework retrieval tools. Its guide includes a complete quickstart and the current schema requirements and limitations.
| Guide | Content |
|---|---|
| Schema & Attributes | Code-first generation, [VespaExtraFields], ApplicationPackageOptions |
| Document Operations | CRUD, field ops, conditional writes, visit, addressing |
| Search | Basic, nearest-neighbor, hybrid, streaming, request options |
| YQL Builder | Fluent query builder, predicates, boolean composition |
| Grouping | Aggregations, buckets, nested grouping, pagination |
| Ranking DSL | RankingBuilder, code-first rank profiles |
| Feed | Bulk operations, streaming pipeline, backpressure |
| Configuration | Options, DI, mTLS, observability, health checks, testing |
Running the Sample App
The sample app uses the local Vespa instance described in Quick Start:
dotnet run --project samples/Vespa.NET.Samples
Dependencies
| Package | Purpose |
|---|---|
Microsoft.Extensions.Http |
IHttpClientFactory |
Microsoft.Extensions.Http.Resilience |
Retry + circuit breaker (Polly) |
Microsoft.Extensions.Diagnostics.HealthChecks |
ASP.NET Core health check |
System.Text.Json |
JSON serialization (built-in) |
Testcontainers (optional helper package) |
Docker fixtures through Vespa.NET.Testcontainers |
Resources
License
MIT License — see LICENSE for details.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. net9.0 was computed. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
-
net10.0
- Microsoft.Extensions.Logging.Abstractions (>= 10.0.7)
- Testcontainers (>= 4.16.0)
- Vespa.NET (>= 3.1.1)
-
net8.0
- Microsoft.Extensions.Logging.Abstractions (>= 10.0.7)
- Testcontainers (>= 4.16.0)
- Vespa.NET (>= 3.1.1)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.