Weaviate C# Client

Welcome to the official C# client for Weaviate, the open-source vector database. This library provides a convenient and idiomatic way for .NET developers to interact with a Weaviate instance.

---

🚀 Installation

You can install the Weaviate C# client via the NuGet Package Manager or the dotnet CLI.

dotnet add package Weaviate.Client --version 1.0.0

Alternatively, you can add the PackageReference to your .csproj file:

<ItemGroup>
  <PackageReference Include="Weaviate.Client" Version="1.0.0" />
</ItemGroup>

---

✨ Getting Started

The best way to get started is by following our quickstart guide. It will walk you through setting up the client, connecting to Weaviate, creating a collection, and performing your first vector search.

• ➡️ Quickstart Guide

Quickstart example

string weaviateUrl = Environment.GetEnvironmentVariable("WEAVIATE_URL");
string weaviateApiKey = Environment.GetEnvironmentVariable("WEAVIATE_API_KEY");

// 1. Connect to Weaviate Cloud
var client = await Connect.Cloud(weaviateUrl, weaviateApiKey);

// 2. Prepare data
var dataObjects = new List<object>
{
    new { title = "The Matrix", description = "A computer hacker learns about the true nature of reality and his role in the war against its controllers.", genre = "Science Fiction", },
    new { title = "Spirited Away", description = "A young girl becomes trapped in a mysterious world of spirits and must find a way to save her parents and return home.", genre = "Animation", },
    new { title = "The Lord of the Rings: The Fellowship of the Ring", description = "A meek Hobbit and his companions set out on a perilous journey to destroy a powerful ring and save Middle-earth.", genre = "Fantasy", },
};

var CollectionName = "Movie";

// 3. Create the collection
var movies = await client.Collections.Create(
    new CollectionCreateParams
    {
        Name = CollectionName,
        VectorConfig = Configure.Vector("default", v => v.Text2VecWeaviate()),
    }
);

// 4. Import the data
var result = await movies.Data.InsertMany(dataObjects);

// 5. Run the query
var response = await movies.Query.NearText("sci-fi", limit: 2);

// 6. Inspect the results
foreach (var obj in response.Objects)
{
    Console.WriteLine(JsonSerializer.Serialize(obj.Properties));
}

---

🔌 Microsoft.Extensions.VectorData Integration

The Weaviate.Client.VectorData package wraps the Weaviate client in the standard .NET vector database abstraction layer. Use it when you want your code to be portable across vector stores, or when you're building on top of Semantic Kernel.

dotnet add package Weaviate.Client.VectorData

using Microsoft.Extensions.VectorData;
using Weaviate.Client.VectorData;
using Weaviate.Client.VectorData.DependencyInjection;

// DI registration (requires Weaviate.Client to be registered first)
builder.Services.AddWeaviate(options => { options.RestEndpoint = "localhost"; });
builder.Services.AddWeaviateVectorStore();

// Or use directly
var store = new WeaviateVectorStore(weaviateClient);
var collection = store.GetCollection<Guid, Article>("Article");
await collection.EnsureCollectionExistsAsync();

await collection.UpsertAsync(article);

await foreach (var result in collection.SearchAsync(queryEmbedding, top: 10))
    Console.WriteLine($"[{result.Score:F4}] {result.Record.Title}");

See Microsoft.Extensions.VectorData Integration for the full guide.

---

📚 Documentation

For more detailed information on specific features, please refer to the official documentation and the how-to guides.

• Client library overview
• How-to: Configure the client
• How-to: Manage collections
• How-to: Manage data objects
• How-to: Query & search data

Additional Guides

• Batch API Usage: Server-side streaming batch operations Note: Server-side batch requires Weaviate v1.36.0 or newer (or v1.35 with the experimental flag enabled). Earlier versions will not work.
• Error Handling: Exception types and error handling patterns
• RBAC API Usage: Managing users, roles, permissions, and groups
• Backup API Usage: Creating and restoring backups
• Nodes API Usage: Querying cluster node information
• Aggregate Result Accessors: Type-safe access to aggregation results
• Microsoft.Extensions.VectorData Integration: Standard .NET vector store abstraction support

---

🤝 Community

Connect with the Weaviate community and the team through our online channels. We would love to hear your feedback!

• GitHub Issues: For specific feature requests, bug reports, or issues with the client.
• Weaviate Forum: For questions and discussions.

🧪 Integration Testing

To run the integration test suite locally you need a Weaviate server at version >= 1.31.0.

Start a local instance with the helper script (defaults to the minimum supported version):

./ci/start_weaviate.sh            # uses 1.31.0
# or explicitly
./ci/start_weaviate.sh 1.32.7     # any version >= 1.31.0

Run the tests:

dotnet test src/Weaviate.Client.Tests/Weaviate.Client.Tests.csproj

Filtering Slow Tests

Some tests (backups and replication) are marked as slow and can take several minutes. You can control which tests run using the --filter option:

# Run all tests including slow ones (default)
dotnet test src/Weaviate.Client.Tests/Weaviate.Client.Tests.csproj

# Exclude slow tests (recommended for quick feedback during development)
dotnet test src/Weaviate.Client.Tests/Weaviate.Client.Tests.csproj --filter "Category!=Slow"

# Run ONLY slow tests
dotnet test src/Weaviate.Client.Tests/Weaviate.Client.Tests.csproj --filter "Category=Slow"

Stop the environment when finished:

./ci/stop_weaviate.sh

If the server version is below 1.31.0 the integration tests will be skipped automatically.